All Products
Search
Document Center

:Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster

Last Updated:Aug 22, 2024

This topic describes how to obtain the kubeconfig file of a cluster and then use kubectl to connect to the cluster.

Introduction to kubectl and kubeconfig files

kubectl is a standard Kubernetes command-line tool. You can use kubectl to connect to and manage Alibaba Cloud Container Compute Service (ACS) clusters. A kubeconfig file stores information about a cluster, users, namespaces, and identity authentication mechanism. Kubectl uses a kubeconfig file to connect to an ACS cluster.

Connection methods

You can connect to an ACS cluster over the Internet or an internal network.

  • Connect to a cluster over the Internet

    If an elastic IP address (EIP) is associated with the API server of a cluster, the API server is exposed to the Internet. In this case, the cluster has no limits on the client that you choose to access the cluster. For more information about how to enable Internet access for the API server, see Control public access to the API server of a cluster.

  • Connect to a cluster over an internal network

    If you want to connect to a cluster over an internal network, your client must be deployed in the same virtual private cloud (VPC) as the cluster.

Step 1: Install kubectl

Note

If you use a RAM user, you must authorize the RAM user to manage your cluster before you connect to the cluster from a kubectl client. For more information, see Authorization overview.

  1. Determine the machine on which the kubectl client is installed and choose a method to connect to the cluster.

  2. Download kubectl and install it on the machine.

    For more information, see Download and install kubectl. Kubernetes is developed based on the Linux kernel. Therefore, you must download the Linux version of kubectl and run Linux commands.

Step 2: Select a type of cluster credentials

Each ACS cluster provides two types of cluster credentials for you to connect to the cluster over the Internet or an internal network. The cluster credentials are stored in the kubeconfig file. By default, kubectl searches for the config file in the $HOME/.kube directory on the machine. The file stores the credentials that are used to access the cluster. Kubectl uses this file to connect to the cluster.

  1. Log on to the ACS console. In the left-side navigation pane, click Clusters.

  2. On the Clusters page, find the cluster that you want to manage and click the name of the cluster, or click Details in the Actions column. The details page of the cluster appears.

  3. On the details page of the cluster, click the Connection Information tab. Then, click the Public Access or Internal Access tab and click Copy to copy the credentials that are used to access the cluster.

    Note

    You can also use a temporary kubeconfig file to specify the validity period of the cluster credentials. This allows you to access the cluster in a more flexible manner. For more information, see Generate a temporary kubeconfig file.

  4. Paste the credentials to the config file in the $HOME/.kube directory, save the file, and then exit.

    If the .kube folder and the config file do not exist in the $HOME/ directory, you must manually create the folder and file.

Step 3: Verify the connectivity

After you add the cluster credentials, run the kubectl command to verify the connectivity to the cluster. Run the following command to query the namespaces of the cluster:

kubectl get namespace

Expected output:

NAME              STATUS   AGE
default           Active   4h39m
kube-node-lease   Active   4h39m
kube-public       Active   4h39m
kube-system       Active   4h39m

Generate a temporary kubeconfig file

You can use a temporary kubeconfig file to specify the validity period of the cluster credentials. This allows you to access the cluster in a more flexible manner.

  1. Log on to the ACS console. In the left-side navigation pane, click Clusters.

  2. On the Clusters page, find the cluster that you want to manage and click the name of the cluster, or click Details in the Actions column. The details page of the cluster appears.

  3. On the details page of the cluster, click the Connection Information tab. Then, click Generate Temporary kubeconfig.

  4. In the Temporary kubeconfig dialog box, specify the validity period of the temporary kubeconfig file and select a connection mode: Public Access or Internal Access. Click Generate Temporary kubeconfig and then click Copy to copy the content in the code block to the $HOME/.kube/config file on your client.

    tempo

    After you complete the configuration, you can use the temporary kubeconfig file to connect to the cluster. You cannot connect to the cluster after the temporary kubeconfig file expires.

FAQ

Issue 1: How do I obtain the identity information of the user that is associated with the certificate used in a kubeconfig file?

Run the following command to obtain the identity information of the user that is associated with the certificate used in a kubeconfig file.

Note

When you run the command, replace YOUR_KUBECONFIG_PATH with the absolute path of the kubeconfig file that you want to query. By default, kubectl uses the $HOME/.kube/config file to connect to a cluster. You can also configure the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

grep client-certificate-data YOUR_KUBECONFIG_PATH |awk '{print $2}' |base64 -d | openssl x509 -noout -text |grep Subject:

Expected output:

        Subject: O=system:users, OU=, CN=1***-1673419473

Parameters:

  • O specifies the information about the Kubernetes user group. In this example, the name of the user group is system:users.

  • CN specifies the user information. In this example, the user is 1***-1673419473. 1*** is the RAM user ID.

Issue 2: How do I obtain the expiration date of the certificate used in a kubeconfig file?

Run the following command to query the expiration date of the certificate used in a kubeconfig file.

Note

When you run the command, replace YOUR_KUBECONFIG_PATH with the absolute path of the kubeconfig file that you want to query. By default, kubectl uses the $HOME/.kube/config file to connect to a cluster. You can also configure the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

grep client-certificate-data YOUR_KUBECONFIG_PATH |awk '{print $2}' |base64 -d | openssl x509 -noout -enddate

Expected output:

notAfter=Jan 10 06:44:34 2026 GMT

Jan 10 06:44:34 2026 GMT is the expiration date of the certificate.

You can log on to the console or call the specific API to obtain a kubeconfig file that uses a new certificate within 60 days before the expiration date of the current certificate or after the current certificate expires.

Issue 3: What do I do if the following error is prompted when I use kubectl to connect to a cluster: certificate is valid for?

When you use kubectl to access a new IP address assigned to the Server Load Balancer (SLB) instance of the Kubernetes API server in a cluster, the access failed and the Error while proxying request: x509: certificate is valid for xxx or Unable to connect to the server: x509: certificate is valid for xxx error is prompted.