Import a Kubernetes cluster

This topic describes how to import a Kubernetes cluster on the console.

Prerequisites

• You have registered an account.
• You have prepared at least one Kubernetes cluster.

Import a Kubernetes cluster

1. Log in to the KubeSphere Cloud platform with your account.

2. In the upper-right corner, hover your cursor over the username area and click Console from the drop-down list.

3. In the navigation pane on the left, click Resource Management. On the Kubernetes Clusters page, click Import Self-build Cluster.

   common:NOTE

   On the Overview page, you can also click Add Cluster > Import under Resource Management.

4. On the Import Kubernetes Cluster page, set the following parameters:

   Parameter	Required	Description
   Cluster Name	Yes	User-defined name of the cluster. The name can contain only lowercase letters, numbers, and hyphens (-), and must start and end with a lowercase letter or number. The maximum length is 63 characters.
   Tag	No	User-defined tag of the cluster. Select a tag from the drop-down list to tag the cluster: Production Development Testing Demo
   Connection Method	Yes	Select a connection method for importing the cluster, including: Direct Connection: To use this method, enter the kubeconfig of the Kubernetes cluster, and you have to ensure that the address of cluster.server is exposed to the public network. Agent Connection: To use this method, you have to install the agent connection component in the Kubernetes cluster. For more information, see Use Agent Connection.
   Skip TLS verification	No	Skip TLS verification or not. If selected, the verification of the Kubernetes server certificate will be skipped. Note: This option is displayed only after you select Direct Connection. The HTTPS connection to the Kubernetes cluster will become insecure if you select this item. If the service fails to connect to the Kubernetes cluster while you are certain that the address of cluster.server is exposed to the public network, please select this item and try clicking Connect again.

5. After setting the parameters, click Connect. After the service successfully connects to the cluster, click Import. The imported cluster is displayed in the cluster list.

   common:NOTE

   • You may need to configure port forwarding rules and open the port in the firewall depending on the environment where the cluster is deployed. If the service cannot connect to the cluster after you click Connect, refer to Obtain Kubeconfig.

   • After the cluster is imported, a namespace qiming-backend will be automatically created to install backup and recovery components.

(Recommended) Use Agent Connection

To use Agent Connection to import your Kubernetes cluster, perform the following steps:

1. On the Import Kubernetes Cluster page, set the required parameters, and select Agent Connection for Connection Method.

2. On the control plane of the cluster, run the command that is displayed at the bottom of the page to install agent connection component.

   common:NOTE

   If you have limited network access, enable domain names kubesphere.cloud and tower.kubesphere.cloud and ports 80 and 443.

3. Click Agent Component Installed and wait until the connection is established.

4. If the connection is successfully established, the page will be redirected to the cluster details page.

5. (Optional) If the agent connection fails, the page will be redirected to the cluster details page. Please click Note and refer to the instructions to do troubleshooting through the following steps.

   • Step 1:

     1. On the node where the agent connection component is installed, run the following command to check the status of the components. The READY and AVAILABLE column should be 1/1 and 1 respectively.

        kubectl get deploy cluster-agent -n kubesphere-cloud-system
        

        

     2. If the agent connection component is not running properly, run the following command to check the logs for further troubleshooting.

        kubectl logs -l app=agent -n kubesphere-cloud-system
        

        

   • Step 2:

     1. If the component cannot run properly, run the command shown on the page to uninstall the component.

     2. Run the command shown on the page to install the agent connection component again.

     3. After the component is successfully installed, click Connect to establish the agent connection.

Obtain kubeconfig

Managed Kubernetes clusters

If you use managed Kubernetes cluster service from cloud providers, use the kubeconfig exposed to the public network to import your cluster. For example:

• If you use Alibaba Cloud Container Service for Kubernetes (ACK):
  • Make sure you select the Expose API Server with EIP for Access to API Server. For more information, see Alibaba Cloud documentation.
  • On the Cluster Information page, click the Connection Information tab and you can find the kubeconfig under Public Access. For more information, see Alibaba Cloud documentation.
• If you use Cloud Container Engine (CCE) of Huawei Cloud:
  • Make sure you have bound EIP for Public API Server Address on the Cluster Details page, and download the kubeconfig from the Kubectl tab. For more information, see Huawei Cloud documentation.
• If you use Tencent Kubernetes Engine (TKE):
  • Make sure you have enabled Internet access on the Cluster APIServer information page, and copy or download the kubeconfig. For more information, see Tencent Cloud documentation.

Self-managed Kubernetes clusters

If you use self-managed Kubernetes clusters, run the command cat $HOME/.kube/config to obtain the kubeconfig for importing the cluster. Make sure the address of cluster.server is exposed to the public network, or select Skip TLS verification at the same time to import the cluster.

If you cannot import the cluster, please take the following steps to obtain the kubeconfig again:

1. On every control plane of the Kubernetes cluster, go to the directory /etc/kubernetes/pki/ and use the sample file to create a script file.

2. Run the following command to make the script file executable:

   chmod +x <script file name>
   

3. Run the following command to run the script on every control plane of the cluster:

   ./<script file name> <public IP address>
   

4. Forward the private IP address and port of the control plane to a public IP address and port.

5. Run the following command on the control plane to obtain the kubeconfig:

   cat $HOME/.kube/config
   

6. Replace the address of cluster.server with the public IP address and port, and use the modified kubeconfig to import the cluster.

No Kubernetes cluster deployed

1. Run the following command to download the latest version of KubeKey:

   curl -sfL https://get-kk.kubesphere.io | VERSION=v2.2.2 sh -
   

   common:NOTE

   • It is recommended that you use KubeKey to deploy a Kubernetes cluster.

   • If your network connection to GitHub is slow, run the command export KKZONE=cn first before downloading KubeKey.

2. Run the following command to create a sample configuration file, and refer to Edit the configuration file to edit the configuration file for your cluster.

   ./kk create config [--with-kubernetes version] [(-f | --file) path]
   

3. In the configuration file of the cluster (for example, config-sample.yaml), add the following content under spec.kubernetes:

   apiserverCertExtraSans: <[public IP address]>
   

   common:NOTE

   Make sure you indent 2 spaces at the beginning of the line.

4. Run the following command to create the cluster:

   ./kk create cluster -f config-sample.yaml
   

   common:NOTE

   Make sure you replace config-sample.yaml with your configuration file name.

5. Forward the private IP address and port of the control plane to a public IP address and port.

6. Run the following command on the control plane to obtain the kubeconfig:

   cat $HOME/.kube/config
   

7. Replace the address of cluster.server with the public IP address and port, and use the modified kubeconfig to import the cluster.