Get a kubeconfig and use kubectl to connect to a cluster - Container Service for Kubernetes

Prerequisites

Before you begin, ensure that you have:

kubectl installed on your client machine. Install it from Install kubectl based on your OS and cluster version. To verify the installed version, run kubectl version --client.
Access to the ACK console
(If you are a Resource Access Management (RAM) user) The required permissions granted in both ACK globally and for the specific cluster. For details, see Authorization.

Choose a kubeconfig type

A kubeconfig file contains the authentication information for accessing a cluster. Before getting one, decide which type fits your use case.

By validity period:

Type	Validity period	Best for
Temporary kubeconfig	30 minutes to 3 days (configurable)	Daily O&M, troubleshooting, CI/CD pipelines
Long-term kubeconfig	3 years (default)	Automated systems, long-running monitoring services

Temporary kubeconfig files auto-expire, which reduces the risk of credential exposure. Use long-term kubeconfig only when frequent credential rotation is impractical.

By access method:

Type	Requirement	Best for
Internal access	Client machine in the same virtual private cloud (VPC) as the cluster	Lower latency, enhanced security
Public access	Any machine with internet access; requires an elastic IP address (EIP) on the API server	Local development, remote O&M

Note

EIP usage incurs charges. For pricing details, see Pay-as-you-go.

Important

Under the shared responsibility model, you are responsible for securing and maintaining your kubeconfig credentials. Regularly rotate your kubeconfig and follow the principle of least privilege.

If you have an ACK dedicated cluster with public access enabled, you can also get the kubeconfig file directly from the master node via SSH. For details, see Connect to the master node of an ACK dedicated cluster by using SSH.

Get a kubeconfig file and connect to the cluster

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, find the cluster you want to manage, then click the cluster name or click Details in the Actions column.
On the cluster details page, click the Connection Information tab. Select Temporary kubeconfig or Long-term kubeconfig. If you select temporary, set a validity period.
Select the Public Access or Internal Access tab, then click Copy to copy the kubeconfig content.
Paste the copied content into $HOME/.kube/config on your client machine, then save the file.
Note
If the file or directory does not exist, run the following commands to create it first:
```
mkdir -p $HOME/.kube
touch $HOME/.kube/config
```

Verify the connection. The following command returns a list of namespaces in the cluster:

kubectl get namespaces

A successful connection returns output similar to:

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

Clean up access

When a user no longer needs cluster access, revoke their kubeconfig permissions in bulk. After revocation, the system does not generate a new kubeconfig for that user. For details, see Delete kubeconfig files. To revoke permissions for multiple users at once, see Use ack-ram-tool to revoke the permissions of specified users on ACK clusters.

Note

To recover accidentally revoked permissions, use the kubeconfig recycle bin to restore specific kubeconfig entries.

FAQ

How do I find the identity associated with a kubeconfig certificate?

Run the following command, replacing kubeconfig with the path to your file. By default, kubectl uses $HOME/.kube/config; specify a different file with the KUBECONFIG environment variable or the --kubeconfig flag.

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

The output is similar to:

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

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

How do I check when a kubeconfig certificate expires?

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 -enddate

The output is similar to:

notAfter=Jan 10 06:44:34 2026 GMT

In this example, the certificate expires on January 10, 2026. Get a new kubeconfig from the console or via an API call within 180 days before expiry, or at any time after it has expired.

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

Run 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}'`

What's next

After connecting, use kubectl to deploy workloads, inspect cluster resources, and manage applications on your ACK cluster.