Obtain a kubeconfig file and connect to a cluster by using kubectl - Container Service for Kubernetes

In addition to the Container Service for Kubernetes (ACK) console, you can use the Kubernetes command line interface (kubectl) to manage your clusters and applications. To connect to a cluster using kubectl, first get its kubeconfig file, which contains the credentials and connection information for accessing the cluster.

Step 1: Install and configure the kubectl client

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

Step 2: Get and use a kubeconfig file

1. Choose a kubeconfig type

A kubeconfig file contains the authentication information for accessing a cluster. Choose a kubeconfig type based on your security requirements and use case.

Important

According to the shared responsibility model, you are responsible for securing and maintaining your kubeconfig credentials. To mitigate security risks from credential leakage, regularly rotate your kubeconfig and follow the principle of least privilege.

By validity period:
- Temporary kubeconfig: You can configure a validity period from 30 minutes to 3 days. The file automatically expires, reducing the security risk of credential exposure. This is the recommended option for daily O&M, troubleshooting, and CI/CD pipelines where long-term access to the API server is not required.
- Long-term kubeconfig: This type has a default validity period of 3 years. This is suitable for automated systems or long-running monitoring services where frequent credential rotation is impractical.
By access method:
- Private access: Use this option when your client machine is in the same virtual private cloud (VPC) as the cluster. Connecting over the internal network through kubeconfig provides lower latency and enhanced security.
- Public access: Use this option to connect to the cluster from any machine with Internet access. This method relies on an Elastic IP (EIP) to expose the API server. It is suitable for local development and remote O&M.
  For fees associated with a bound EIP, see Pay-as-you-go.
If you have an ACK dedicated cluster with public access enabled, you can get the kubeconfig file from the master node via SSH, and use kubectl locally to manage the cluster. For more information, see Connect to the master node of an ACK dedicated cluster by using SSH.

2. Get a kubeconfig file and connect to the cluster

After you get the kubeconfig file from the console, kubectl can use it to connect to and manage the cluster.

Before a Resource Access Management (RAM) user can connect to a cluster, they must be granted the required permissions in both ACK globally and for the specific cluster. For more information, see Authorization.

Log on to the ACK console. In the left 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 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

Clean up permissions: When a user no longer requires access (for example, project completion or employee departure), revoke their kubeconfig permissions in bulk. After the permissions are revoked, the system does not generate a new kubeconfig. For details, see Delete kubeconfig files and Use ack-ram-tool to revoke the permissions of specified users on ACK clusters.

To avoid accidental deletion of permissions, you can use the kubeconfig recycle bin to restore specific revoked kubeconfig permissions.

FAQ

How can I find the identity information associated with a kubeconfig certificate?

Run the following command, replacing kubeconfig with the path to your file:

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

By default, kubectl uses $HOME/.kube/config to connect to a cluster. You can also specify other kubeconfig files by setting the KUBECONFIG environment variable or the --kubeconfig parameter.

The output is similar to:

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

Where:

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

How can I check the expiration date of a kubeconfig certificate?

Run the following command to retrieve the expiration date of the certificate associated with the kubeconfig, replacing kubeconfig with the path to your file:

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

By default, kubectl uses $HOME/.kube/config to connect to a cluster. You can also specify other kubeconfig files by setting the KUBECONFIG environment variable or the --kubeconfig parameter.

The output is similar to:

notAfter=Jan 10 06:44:34 2026 GMT

In this example, Jan 10 06:44:34 2026 GMT is the certificate's expiration date.

You can get a new kubeconfig from the console or by calling an API operation within 180 days before the certificate expires, or at any time after it has expired.

How do I extract the client certificate, client private key, and API server information from a kubeconfig?

You can use the following commands, replacing kubeconfig with the path to your 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}'`

By default, kubectl uses $HOME/.kube/config to connect to a cluster. You can also specify other kubeconfig files by setting the KUBECONFIG environment variable or the --kubeconfig parameter.

What to do next

After the preceding operations are complete, you can use kubectl to connect to the ACK cluster from your on-premises machine.