Migrating to VCN-Native Clusters

To migrate an existing cluster to integrate its Kubernetes API endpoint into your own VCN:

1. Open the navigation menu and click Developer Services. Under Containers & Artifacts, click Kubernetes Clusters (OKE).

2. Choose a Compartment you have permission to work in.

   Migration required labels appear on the Cluster List page beside the names of clusters with Kubernetes API endpoints that are not integrated into your VCN.

3. On the Cluster List page, click the name of the cluster that you want to migrate.

   When you select a cluster that you can migrate, the Migrate Cluster button appears at the top of the Cluster Details page.

4. If you want the cluster's Kubernetes API endpoint to be publicly accessible from the internet and hosted in a new public subnet in the same VCN as the cluster (creating and configuring new network resources as required), perform an Automatic Migration as follows:
   1. At the top of the Cluster Details page, click Migrate Cluster to integrate the cluster's Kubernetes API endpoint into your own VCN.
   2. In the Migrate to VCN-Native Cluster dialog box, select Automatic Migration to create a new regional subnet in the cluster's VCN with a 10.0.0.0/28 CIDR block, along with security lists and route tables.
   3. Click Launch Workflow and review the migration summary in the VCN-Native Endpoint Cluster Migration dialog box.
   4. Click Migrate to create new network resources and migrate the cluster.

      Kubernetes Engine starts migrating the cluster, as shown in the Migrating Cluster dialog.

   5. Click Close to close the Migrating Cluster dialog.
5. If you want the cluster's Kubernetes API endpoint to be privately accessible within your VCN or publicly accessible from the internet, and hosted in an existing regional public or private subnet in the same VCN as the cluster, perform a Custom Migration as follows:
   1. Confirm the following network resources already exist in the VCN and are configured correctly to host the Kubernetes API endpoint (if not, create and configure them appropriately):
      • a regional public or private subnet (see Kubernetes API Endpoint Subnet Configuration)
      • if the subnet is public, an internet gateway (see Internet Gateway Configuration)
      • if the subnet is private, a NAT gateway (see NAT Gateway Configuration) and a service gateway (see Service Gateway Configuration)
      • a route table with the necessary route rules (see Route Table for Kubernetes API Endpoint Subnets)
      • a network security group (recommended) and/or security list with the necessary ingress and egress rules (see Security Rules for the Kubernetes API Endpoint)

      For example configurations, see Example Network Resource Configurations.

   2. At the top of the Cluster Details page, click Migrate Cluster to integrate the cluster's Kubernetes API endpoint into your own VCN.
   3. In the Migrate to VCN-Native Cluster dialog box, select Custom Migration.
   4. Click Launch Workflow and specify:
      • Kubernetes API Endpoint Subnet: A regional subnet to host the cluster's Kubernetes API endpoint. The subnet you specify can be public or private. The Kubernetes API endpoint is always assigned a private IP address. If you specify a public subnet, you can optionally expose the Kubernetes API endpoint to the internet by assigning a public IP address to the endpoint (as well as the private IP address). To simplify access management, Oracle recommends the Kubernetes API endpoint is in a different subnet to worker nodes and load balancers. For more information, see Kubernetes Cluster Control Plane and Kubernetes API.
      • Use network security groups to control traffic: Optionally, restrict the access to the cluster's Kubernetes API endpoint using one or more network security groups (NSGs) that you specify. For more information about the security rules to specify for the NSG, see Security Rules for the Kubernetes API Endpoint.
      • Assign a public IP address to the API endpoint: If you selected a public subnet for the Kubernetes API endpoint, you can optionally expose the endpoint to the internet by assigning a public IP address to the endpoint (as well as the private IP address). If you do not assign a public IP address, update route rules and security rules to enable access to the endpoint using a service gateway and a NAT gateway (see Kubernetes API Endpoint Subnet Configuration).
   5. Click Migrate to create new network resources and migrate the cluster.

      Kubernetes Engine starts migrating the cluster.

Migration usually takes around 15 minutes to complete. During this time, the Kubernetes API continues to be accessible via the public endpoint that is not integrated into your own VCN. However, cluster lifecycle operations (such as cluster updates, node pool creation and deletion) are unavailable.

When migration is complete, the Cluster Details page shows the name of the Kubernetes API Endpoint Subnet, the IP address of the Kubernetes API Private Endpoint, and (if you assigned a public IP address to the Kubernetes API endpoint) the IP address of the Kubernetes API Public Endpoint.

The Cluster Details page also indicates that you have 30 days to update the configuration of your kubectl, tools, and CI/CD pipelines to access the new Kubernetes API endpoint (see Setting Up Access to a Migrated Cluster). During this decommissioning period, the newly migrated cluster is accessible via both the new Kubernetes API endpoint in your VCN, and via the public Kubernetes API endpoint that is not integrated into your own VCN.

Having migrated a cluster to integrate its Kubernetes API endpoint into your own VCN, you have to update the configuration of your kubectl, tools, and CI/CD pipelines to use the new Kubernetes API endpoint. At a minimum, you'll want to update the cluster's Kubernetes configuration file (commonly known as the 'kubeconfig' file) to enable access to the migrated cluster using kubectl, as described in this topic. You also need to update any manifest files that include references to the cluster's Kubernetes API endpoint IP address.

Follow the instructions in this topic to generate a new kubeconfig file. These instructions assume the cluster's kubeconfig file is saved in the default location ($HOME/.kube) and with the default name (config). If that is not the case, adapt the instructions accordingly.

1. In the terminal window where you normally run Oracle Cloud Infrastructure CLI commands, run the following command to update the cluster's existing kubeconfig file:

   oci ce cluster create-kubeconfig --cluster-id <cluster-ocid> --file <kubeconfig-file-location> --region <region-name> --token-version 2.0.0 --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT

   where:

   • --cluster-id <cluster-ocid> is the OCID of the existing cluster you want to make VCN-native.
   • --file <kubeconfig-file-location> is the location of the cluster's kubeconfig file.
   • --region <region-name> is the region in which the cluster is located.
   • --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT specifies whether to add the private IP address or the public IP address of the cluster's Kubernetes API endpoint to the kubeconfig file. For more information, see Kubernetes Cluster Control Plane and Kubernetes API.

   For example:

   oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file $HOME/.kube/config --region us-phoenix-1 --token-version 2.0.0 --kube-endpoint PUBLIC_ENDPOINT

   Assuming the kubeconfig file already exists in the location you specify, details about the cluster are added as a new context to the existing kubeconfig file, including the cluster's new Kubernetes API endpoint in your own VCN. The current-context: element in the kubeconfig file is set to point to the newly-added context.

   For more information about setting up the kubeconfig file, see Setting Up Cluster Access.

2. Verify that kubectl can connect to the cluster using the Kubernetes API endpoint in your own VCN by entering the following command:

   kubectl get nodes

   Information about the nodes in the cluster is shown.

   You can now use kubectl to perform operations on the cluster using the Kubernetes API endpoint in your own VCN.