In addition to the Container Service for Kubernetes (ACK) console, you can also 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 then use kubectl to connect to the cluster.
Introduction to kubectl and kubeconfig files
kubectl is a standard Kubernetes command-line tool used to connect and manage all types of ACK clusters, such as ACK managed clusters and ACK dedicated clusters.
A kubeconfig file stores information about the cluster, users, namespaces, and identity authentication mechanism. Kubectl uses a kubeconfig file to connect to an ACK cluster.
Connection methods (public and internal connections)
You can connect to an ACK cluster through the public or internal network.
Connect to the cluster through public network
If an elastic IP address (EIP) is associated with the API server of the 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 the cluster through internal network
If you want to connect to the cluster through internal connection, your client must be deployed in the same virtual private cloud (VPC) as the cluster.
Step 1: Install kubectl
Note
If you use a Resource Access Management (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.
Determine the machine on which the kubectl client is installed and choose a method to connect to the cluster.
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 ACK cluster provides two types of cluster credentials for you to connect to the cluster through the public or internal connection. The cluster credentials are stored in a kubeconfig file.
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. Then, select cluster credentials for accessing the cluster through public or internal connection.
![image](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/2649416371/p894719.png)
Step 3: Add cluster credentials
Important
The default validity period of a kubeconfig file is three years. 180 days before a kubeconfig file expires, you can obtain the renewed kubeconfig file in the ACK console or by performing the steps in the Query the kubeconfig file of a cluster topic. After a kubeconfig file is renewed, its validity period is reset to 3 years. The previous kubeconfig file remains valid until it expires. We recommend that you renew your kubeconfig file at the earliest opportunity.
In scenarios that do not require long-term connection to the cluster API server, we recommend that you generate a temporary kubeconfig file to reduce the security risks caused by credential leaks.
Based on the shared responsibility model, you are responsible for the maintenance of the kubeconfig files. We recommend that you maintain the use and validity of the credentials to avoid the security risks caused by credential leaks.
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.
Select the Public Access or Internal Access tab and then click Copy.
Paste the credential to the config
file in the $HOME/.kube
directory, save the file, and then exit.
Note
If the .kube
folder and the config
file do not exist in the $HOME/
directory, you must manually create the folder and file.
If an ACK dedicated cluster is used and you have enabled SSH logon over the Internet for the cluster, the SSH tab appears on the Connection Information tab. You can also log on to a master node by using SSH. After you add the cluster credentials to the kubeconfig file, you can use kubectl to connect to and manage the cluster. For more information, see Use SSH to connect to the master nodes of a dedicated Kubernetes cluster.
![image](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/2649416371/p894742.png)
Step 4: 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:
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
You can use a temporary kubeconfig to store cluster credentials and set the validity period of the temporary kubeconfig. This allows you to access the cluster in a more flexible manner.
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, set the validity period of the temporary kubeconfig file and select a connection mode: Public Access or Internal Access.
To connect to the cluster over the Internet, select Public Access and click Generate Temporary kubeconfig. Then, click Copy to copy the content in the code block to the $HOME/.kube/config
file on your client.
To connect to the cluster through a private connection, select Internal Access and click Generate Temporary kubeconfig. Then, click Copy to copy the content in the code block to the $HOME/.kube/config
file on your client.
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.
Revoke a kubeconfig file
When an employee resigns or an issued kubeconfig file is disclosed, you can revoke the kubeconfig file to protect the cluster that the kubeconfig file can be used to access. 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.
FAQ
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:
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 a cluster. You can also configure the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.
Expected output:
Subject: O=system:users, OU=, CN=1***-1673419473
The following information is displayed:
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.
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:
grep client-certificate-data kubeconfig |awk '{print $2}' |base64 -d | openssl x509 -noout -enddate
Note
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.
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 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.
What do I do if the error certificate is valid for
is prompted when I use kubectl to connect to a cluster?
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.
If the cluster is an ACK managed cluster, you can resolve this issue by adding the IP address to the custom subject alternative names (SANs) for the API server certificate. For more information, see Customize the SAN of the API server certificate when you create an ACK cluster.
If the cluster is an ACK dedicated cluster, configure kubectl to ignore this issue.
Important
If you use the insecure-skip-tls-verify
setting to ignore the issue, the client no longer verifies the certificate of the API server. We recommend that you upgrade your ACK dedicated cluster to ACK Pro, and then resolve the issue by adding the new IP address to the SANs for the API server certificate. For more information, see Hot migration from ACK dedicated clusters to ACK Pro clusters.
You can specify the --insecure-skip-tls-verify
parameter when you run the kubectl command.
kubectl -s https://<IP>:6443 --insecure-skip-tls-verify get ns
You can also add the insecure-skip-tls-verify: true
setting to the kubeconfig file and delete the certificate-authority-data
setting.
apiVersion: v1
clusters:
- cluster:
server: https://<IP>:6443
insecure-skip-tls-verify: true
name: kubernetes
contexts:
How do I obtain the information about the certificate authority (CA), key, and API server?
Run the following commands to extract the CA, key, and API server information from the 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}'`
Does an ACK managed cluster provide a root certificate private key which can be used to generate kubeconfig files?
ACK managed clusters do not provide root certificate private keys to external users. You can generate a kubeconfig file only in the ACK console or by calling the ACK API.