Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster - Container Service for Kubernetes

In addition to the Container Service console, you can use the Kubernetes command-line tool kubectl to manage clusters and applications. This topic describes how to obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.

1. Install kubectl

Determine the client machine where you want to install kubectl, and download and install kubectl.

Select the correct version of kubectl based on your operating environment. The following example uses a Linux environment.

2. Select a kubeconfig type

ACK clusters provide kubeconfig files for both public and internal network access.

Public network connection: You can use any machine on the Internet as a client to connect to the cluster.
Internal network connection: The kubectl client machine must be in the same VPC as the cluster.

Note

Before RAM users can connect to a cluster, they must be granted the permissions to operate the cluster in addition to the system permissions of Container Service. For more information, see Authorization.

Log on to the ACK console. In the left-side navigation pane, click Clusters.
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.
On the Cluster Information page, click the Connection Information tab, and select the public or internal network access credential as needed.
For scenarios where you do not need to connect to the cluster API Server for a long time, we recommend that you use a temporary kubeconfig file to reduce security risks if the kubeconfig credential is leaked.

3. Configure the kubeconfig file and verify cluster connectivity

Important

The default validity period of a kubeconfig file is three years. Within 180 days before the expiration date, you can obtain a rotated and refreshed kubeconfig file through the Container Service console or the API for obtaining the kubeconfig file of a cluster. The validity period of the new kubeconfig file is still three years, and the old kubeconfig credential remains valid before the certificate expires. Please obtain the rotated credential in a timely manner according to the expiration time displayed in the console or returned by the API.
According to the shared responsibility model, you are responsible for maintaining the kubeconfig credentials. Please carefully maintain the rationality and validity of the credentials to avoid security risks caused by kubeconfig leakage.

By default, kubectl looks for a file named config in the $HOME/.kube directory of the client machine. The file stores the credentials that are used to access the cluster. Kubectl uses this file to connect to the cluster.

Select the Public Access or Internal Access tab, and click Copy.
Paste the copied cluster credential content into the config file in the $HOME/.kube directory, save the file, and exit.
If the .kube directory and the config file do not exist in the $HOME/ directory, create them yourself.
If your cluster is an ACK dedicated cluster and has public SSH logon enabled, the Connection Information tab displays the SSH tab. In addition to the above method, you can also log on to the master node through SSH, configure the cluster access credential, and then use kubectl to manage the cluster. For more information, see Connect to the master node of an ACK dedicated cluster by using SSH.

After the cluster credential is configured, run a kubectl command to verify the connectivity of the cluster.

The following example shows how to query namespaces.

kubectl get namespace

Expected output:

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

Related operations

Generate a temporary kubeconfig file

To implement more flexible cluster connection strategies, you can generate a temporary kubeconfig file and set its validity period.

Log on to the ACK console. In the left-side navigation pane, click Clusters.
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.
On the Cluster Information page, click the Connection Information tab, and then click Generate Temporary Kubeconfig.
In the Temporary Kubeconfig dialog box, follow the page prompts to set the validity period of the temporary credential and the method to access the cluster (including public access and internal access).
- Public access: Select Public Access, click Generate Temporary Kubeconfig, and then click Copy to paste the content into the $HOME/.kube/config file on your local computer.
- Internal access: Select Internal Access, click Generate Temporary Kubeconfig, and then click Copy to paste the content into the $HOME/.kube/config file on your local computer.
After configuration, you can connect to the cluster using the temporary credential. You cannot connect to the cluster after the temporary kubeconfig file expires.

Revoke a kubeconfig file

When an employee leaves the company or a kubeconfig file is suspected to be leaked, you can revoke the kubeconfig file of the cluster to ensure cluster security. After you revoke the kubeconfig file, the system generates a new kubeconfig file and authorization binding. The kubeconfig file previously issued to the RAM user or RAM role becomes invalid. For more information, see Revoke the kubeconfig file of a cluster.

Clear and restore kubeconfig files

You can batch clear the kubeconfig permissions of a specified cluster or RAM user or role within your management scope. After clearing, the system will not generate a new kubeconfig file. You can also restore the cleared kubeconfig permissions through the kubeconfig recycle bin feature. For more information, see Clear kubeconfig files, Clear the permissions of a specified user in a cluster by using ack-ram-tool, Use the kubeconfig recycle bin.

FAQ

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

Run the following command to obtain the information.

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

Note

By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. You can also set the KUBECONFIG environment variable or use the --kubeconfig parameter to specify another kubeconfig file.

Expected output:

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

Where:

O: The Kubernetes user group information. In the example, the group name is system:users.
CN: The associated user information. In the example, the user is 1***-1673419473, where 1*** is associated with an Alibaba Cloud user ID in your account.

How do I query 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:

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

Note

Expected output:

notAfter=Jan 10 06:44:34 2026 GMT

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

You can use the console or API to obtain a kubeconfig file that uses a new certificate within 180 days before the expiration date of the current certificate or after the current certificate expires.

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

When you bind a new IP address to the SLB instance of the cluster API Server and then use kubectl to access this new IP address, kubectl commands may fail with the error Error while proxying request: x509: certificate is valid for xxx or Unable to connect to the server: x509: certificate is valid for xxx.

ACK managed cluster: Add the new IP address to the API Server certificate SAN. For more information, see Customize the SAN of the API server certificate for a cluster.
ACK dedicated cluster: Configure kubectl to use the insecure-skip-tls-verify configuration to ignore this error.
Important
However, this method will cause the client to no longer verify the API Server certificate. We recommend that you migrate an ACK dedicated cluster to an ACK Pro managed cluster, and then add the new IP address to the API Server certificate SAN to solve this problem.
- Method 1: Specify the --insecure-skip-tls-verify parameter when running kubectl commands.
```
kubectl -s https://<IP>:6443 --insecure-skip-tls-verify get ns
```
- Method 2: Modify the kubeconfig file content, add the insecure-skip-tls-verify: true configuration, and then delete the certificate-authority-data configuration.
```
apiVersion: v1
clusters:
- cluster:
    server: https://<IP>:6443
    insecure-skip-tls-verify: true
  name: kubernetes
contexts:
```

How do I extract CA, key, and API server information?

You can use the following commands to extract CA, Key, and API Server information from a kubeconfig file.

cat  ./kubeconfig |grep client-certificate-data | awk -F ' ' '{print $2}' |base64 -d > ./client-cert.pem
cat  ./kubeconfig |grep client-key-data | awk -F ' ' '{print $2}' |base64 -d > ./client-key.pem
APISERVER=`cat  ./kubeconfig |grep server | awk -F ' ' '{print $2}'`

Can ACK managed clusters provide cluster root certificate keys for self-generation of kubeconfig certificates?

ACK managed clusters do not provide cluster root certificate keys externally. We recommend that you obtain cluster kubeconfig files through the console or API.

References

For information about how to call an API to query the kubeconfig file of a cluster, see DescribeClusterUserKubeconfig.
If you need to log on to a node, see Overview of connection methods.

1. Install kubectl

2. Select a kubeconfig type

3. Configure the kubeconfig file and verify cluster connectivity

Related operations

Generate a temporary kubeconfig file

Revoke a kubeconfig file

Clear and restore kubeconfig files

FAQ

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

How do I query the expiration date of the certificate used in a kubeconfig file?

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

How do I extract CA, key, and API server information?

Can ACK managed clusters provide cluster root certificate keys for self-generation of kubeconfig certificates?

References

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