Obtain a kubeconfig file to connect to a cluster with kubectl - Container Compute Service

This topic describes how to obtain a kubeconfig file from the ACS console and use it to connect to an ACS cluster with kubectl.

Overview

This topic describes how to obtain a kubeconfig file from the ACS console and use it to connect to an ACS cluster with kubectl.

ACS provides two kubeconfig types based on the network path you use to reach the cluster API server:

Public Access kubeconfig: connects to the cluster API server over the internet through an Elastic IP Address (EIP).
Internal Access kubeconfig: connects to the cluster API server over an internal network within the same Virtual Private Cloud (VPC).

Each kubeconfig can be issued as a temporary credential with a configurable validity period, or as a long-term credential.

By default, kubectl searches for a file named config in the $HOME/.kube directory on the client machine.

Prerequisites

Confirm the following requirements before you begin.

Prerequisite	Requirement	How to verify
kubectl	Version within one minor version of the cluster Kubernetes version	Run `kubectl version --client`
Network access	Client has internet access (public endpoint) or is in the same VPC as the cluster (internal endpoint)	Check the Connection Information tab in the ACS console
Operating system (OS)	Linux, macOS, or Windows	—

Connection methods

Select the connection type that matches your network environment.

Your situation	Connection type	Prerequisite
Client is outside Alibaba Cloud	Public Access (internet)	Enable public network access (EIP) for the cluster API server
Client is in the same VPC as the cluster	Internal Access	Client machine must be in the same VPC as the cluster

To enable public network access for the API server, see Control public network access to the API server of a cluster.

Step 1: Install kubectl

Determine the client machine on which you want to install kubectl, and install kubectl based on your operating system (OS) and cluster version.

Step 2: Obtain and configure the kubeconfig file

ACS clusters provide two types of cluster credentials, also known as 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 folder on the client machine. This file stores the access credentials that kubectl uses to connect to and manage your clusters.

Log on to the ACS console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster you want to connect to, then click the cluster ID or click Details in the Actions column.
On the cluster details page, click the Connection Information tab.
Select the kubeconfig credential type:
- Temporary: Set a validity period for the credential.
- Long-term: The credential does not expire automatically.
Select the Public Access or Internal Access tab, then click Copy to copy the kubeconfig content.
On your client machine, paste the copied content into $HOME/.kube/config, then save and exit the file.

Note: If the $HOME/.kube directory or the config file does not exist, create them first:
```
mkdir -p $HOME/.kube
touch $HOME/.kube/config
```

Step 3: Verify the connection

Run the following command to verify that kubectl can connect to the cluster:

kubectl get namespaces

If the connection is successful, the output looks similar to the following:

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

FAQ

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

When you run this command, replace YOUR_KUBECONFIG_PATH with the absolute path of the configuration file that you want to query. By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. You can also specify other kubeconfig files by setting the kubeconfig environment variable or the --kubeconfig parameter.

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 output contains the following fields:

O (Organization): The Kubernetes user group. Example: system:users.
OU (Organizational Unit): Shown in the output as OU=.
CN (Common Name): The associated user. Example: 1***-1673419473, where 1*** corresponds to your Alibaba Cloud user ID in the account.

How do I get the expiration date of the certificate used by a kubeconfig file?

When you run this command, replace YOUR_KUBECONFIG_PATH with the absolute path of the configuration file to query. By default, kubectl uses the $HOME/.kube/config file to connect to the cluster. You can also specify other kubeconfig files by setting the kubeconfig environment variable or the --kubeconfig parameter.

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

You can obtain a kubeconfig file with a new certificate from the console or using OpenAPI from 60 days before to 60 days after the certificate expires.

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

Cause: This error occurs when you attach a new IP address to the cluster API server's Server Load Balancer (SLB) instance. The new IP address is not included in the API server certificate's Subject Alternative Name (SAN) field, so kubectl rejects the connection.

Error messages:

Error while proxying request: x509: certificate is valid for xxx

Unable to connect to the server: x509: certificate is valid for xxx

Resolution: Add the new IP address to the API server certificate's SAN field. For step-by-step instructions, see Customize the SAN field of a cluster's API server certificate. The following figure shows a sample configuration: