How to use kubectl to connect to an ACS cluster - Container Compute Service

This topic describes how to obtain a cluster kubeconfig file that contains the credentials for the current user. It also describes how to use a kubectl client to connect to the cluster.

Introduction to kubectl and kubeconfig

kubectl is the standard command-line tool for Kubernetes. You can use kubectl to connect to and manage Alibaba Cloud Container Service (ACS) clusters. A kubeconfig file contains information about clusters, users, namespaces, and authentication mechanisms. kubectl uses the kubeconfig file to connect to a cluster.

Connection methods

You can connect to a cluster over the internet or an internal network.

Internet connection
If you enable public network access for the API server of a cluster, you can connect to the cluster from any client over the internet. When you enable this feature, the API server is exposed through an Alibaba Cloud Elastic IP Address (EIP). For more information about how to enable public network access for the API server, see Control public network access to the API server of a cluster.
Internal network connection
To connect to the cluster only over an internal network, your kubectl client must be in the same Virtual Private Cloud (VPC) as the cluster.

Step 1: Install kubectl

Install kubectl on your client machine based on your OS and cluster version.

Step 2: Configure cluster credentials

ACS clusters provide two types of cluster credentials, also known as kubeconfig files: one for public network access and one for internal network access. By default, kubectl searches for a file named config in the $HOME/.kube folder on the client machine. This file stores the access credentials that kubectl uses to connect to and manage your clusters.

Log on to the ACS console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its ID or click Details in the Actions column of the cluster.
On the cluster details page, click the Connection Information tab, and choose between a temporary or long-term kubeconfig. If you select a temporary kubeconfig, set an appropriate validity period.
Select the Public Access or Internal Access tab, then click Copy to copy the kubeconfig content. Paste the copied content into the $HOME/.kube/config file on your client machine, then save and exit the file.
If this file or directory does not exist, run mkdir -p $HOME/.kube and touch $HOME/.kube/config to create it.

Verify the connection by running a kubectl command. For example, to list all namespaces:

kubectl get namespaces

A successful connection will return a list of namespaces:

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

FAQ

How do I get the identity information associated with the certificate in a kubeconfig file?

When you run this command, replace YOUR_KUBECONFIG_PATH with the absolute path of the configuration file that you want to query. By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. You can also specify other kubeconfig files by setting the kubeconfig environment variable or the --kubeconfig parameter.

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

The expected output is similar to the following:

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

The parameters are described as follows:

O indicates the Kubernetes user group. In this example, the group name is system:users.
CN indicates the associated user. In this example, the user is 1***-1673419473. 1*** corresponds to an Alibaba Cloud user ID in the account.

How do I get the expiration date of the certificate used by a kubeconfig file?

When you run this command, replace YOUR_KUBECONFIG_PATH with the absolute path of the configuration file to query. By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. You can also specify other kubeconfig files by setting the kubeconfig environment variable or using the --kubeconfig parameter.

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

The following is an example of the output:

notAfter=Jan 10 06:44:34 2026 GMT

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

You can obtain a kubeconfig file with a new certificate from the console or using OpenAPI from 60 days before to 60 days after the certificate expires.

Question 3: How do I resolve the `certificate is valid for` error when connecting to a cluster using kubectl?

When you attach a new IP address to the API server's Server Load Balancer (SLB) instance and then use kubectl to access this new IP address, kubectl commands fail. An error message is returned, such as Error while proxying request: x509: certificate is valid for xxx or Unable to connect to the server: x509: certificate is valid for xxx.

You can add the new IP address to the API server certificate's Subject Alternative Name (SAN). For more information, see Customize the SAN field of a cluster's API server certificate. The following figure shows a sample configuration: