How to connect to an ACS cluster by using kubectl - Container Compute Service

A kubeconfig file stores the cluster access credential, including identity information of the currently logged-on user. After you obtain a kubeconfig file from the console, use a kubectl client to connect to and manage an Alibaba Cloud Container Compute Service (ACS) cluster.

kubectl and kubeconfig

kubectl is the standard command-line tool for managing Kubernetes. Use kubectl to connect to and manage ACS clusters. A kubeconfig file contains information about clusters, users, namespaces, and authentication mechanisms. kubectl uses a kubeconfig file to connect to a cluster.

Connection methods

Choose a connection method based on the location of your kubectl client machine.

Public network connection: Use this method when your client machine is on the public network. The cluster must have public access to the API server enabled, which exposes the API server through an Elastic IP Address (EIP). For instructions on enabling public access, see Control public access to the API server of a cluster.
Internal network connection: Use this method when you only need internal access. Your kubectl client machine must reside 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 the cluster credential

ACS clusters provide two cluster credentials, which are 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 directory on the client machine. This file stores the access credential of the cluster to manage, and kubectl uses this configuration file to connect to the cluster.

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster, or click Details in the Actions column.
On the Cluster Information page, click the Connection Information tab. Select a temporary or long-term kubeconfig. For a temporary kubeconfig, set the validity period.
Click the Internal Access or Public Access tab, then click Copy.
Paste the content into the $HOME/.kube/config file on your client, and save the file.

Note: If the directory or file does not exist, create it first.

Verify the connection by listing all namespaces:

kubectl get namespaces

Expected output:

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

FAQ

The following commands use YOUR_KUBECONFIG_PATH as a placeholder for the absolute path of the kubeconfig file. By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. To specify a different kubeconfig file, set the KUBECONFIG environment variable or the --kubeconfig parameter.

Question 1: How do I get the identity information associated with the certificate used in a kubeconfig file?

Run the following command:

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 following list describes the parameters in the output:

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

Question 2: How do I get the expiration time of the certificate used in a kubeconfig file?

Run the following command:

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

The expected output is similar to the following:

notAfter=Jan 10 06:44:34 2026 GMT

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

Obtain a kubeconfig file that contains a new certificate from the console or by using OpenAPI within 60 days before the certificate expires, or at any time after it expires.

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

If you bind a new IP address to the Server Load Balancer (SLB) instance of the cluster API server and then use kubectl to access the new IP address, the kubectl command fails and returns the Error while proxying request: x509: certificate is valid for xxx error or the Unable to connect to the server: x509: certificate is valid for xxx error.

Add the new IP address to the subject alternative name (SAN) of the API server certificate, as described in Customize the SAN of the API server certificate for a cluster. The following example shows the configuration:

In the Update Custom Certificate SAN dialog box, enter the new IP address, such as 192.168.1.137, in the Custom Certificate SAN field. Separate multiple IP addresses or domain names with commas (,). Then, click OK. Note: Modifying the SAN causes the API server to restart briefly.