All Products
Search

This Product

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

    Document Center

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

    Last Updated:Apr 09, 2025

    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 use kubectl to connect to the cluster.

    1. Install kubectl

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

    Select the 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 public and internal network access.

    • Public network connection: You can use any device on the Internet as a client to connect to the cluster.

    • Internal network connection: The kubectl client must be in the same virtual private cloud (VPC) as the cluster.

    Note

    Before Resource Access Management (RAM) users can connect to a cluster, they must be granted the permissions to operate the cluster in addition to the system permissions of ACK. For more information, see Authorization.

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. 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.

    3. 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.

      image

    3. Configure the kubeconfig file and verify cluster connectivity

    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. Obtain the rotated credential in a timely manner according to the expiration time displayed in the console or returned by the API.

    • Based on the shared responsibility model, you are responsible for maintaining the kubeconfig credentials. 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 of the client. The file stores the credentials that are used to access the cluster. Kubectl uses this file to connect to the cluster.

    1. Select the Public Access or Internal Access tab, and click Copy.

    2. Paste the copied cluster credential 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, 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 Connect to the master node of an ACK dedicated cluster by using SSH.

    3. 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.

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. 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.

    3. On the Cluster Information page, click the Connection Information tab, and then click Generate Temporary kubeconfig.

    4. 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 on-premises 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 on-premises computer.

      After configuration, you can connect to the cluster by 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 by using the kubeconfig recycle bin feature. For more information, see Delete kubeconfig files, Use ack-ram-tool to revoke the permissions of specified users on ACK clusters, 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

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

    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:

    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.

    • ACK managed cluster: Add the new IP address to the subject alternative names (SANs) for the API server certificate. For more information, see Customize the SANs of the API server certificate when you create an ACK cluster.

    • ACK dedicated cluster: Configure kubectl to use the insecure-skip-tls-verify configuration to ignore this error.

      Important

      This method will cause the client to no longer verify the API server certificate. We recommend that you perform a Hot migration from ACK dedicated clusters to ACK managed Pro clusters, and then add the new IP address to the API server certificate SAN to resolve this problem.

      • Method 1: Specify the --insecure-skip-tls-verify parameter when you run the kubectl command.

        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 obtain the information about the CA, key, and API server?

    Run the following command to extract the certificate authority (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 cluster root certificate keys to external users. We recommend that you obtain cluster kubeconfig files in the ACK console or by calling the ACK API.

    References