All Products
Search

This Product

    Container Service for Kubernetes:Connect to an ACK cluster using kubectl

    Document Center

    Container Service for Kubernetes:Connect to an ACK cluster using kubectl

    Last Updated:Oct 14, 2026

    In addition to the Container Service for Kubernetes (ACK) console, you can use kubectl, the Kubernetes command-line tool, to manage clusters and applications. Before you connect to a cluster by using kubectl, obtain the cluster kubeconfig, which contains your current user identity information.

    Step 1: Install and configure the kubectl client

    Identify the client machine on which you want to install kubectl. Based on your operating environment and cluster version, install kubectl.

    Step 2: Get and use the kubeconfig

    1. Select a kubeconfig type

    A kubeconfig contains the authentication information that is required to access the cluster. Select a kubeconfig type based on your security requirements and use case.

    Important

    Under Shared responsibility model, you are responsible for managing and maintaining your kubeconfig credentials. Keep them appropriate and valid, rotate the kubeconfig regularly, and follow the principle of least privilege to avoid the security risks of a leaked kubeconfig.

    • By kubeconfig validity period:

      • Temporary kubeconfig: You can configure a kubeconfig validity period from 30 minutes to 3 days. The kubeconfig automatically expires after the configured period to reduce the security risk of a leak. This type is suitable for use cases that do not require a long-term connection to the API server, such as daily O&M, troubleshooting, and CI/CD pipelines.

      • Long-term kubeconfig: The default validity period is 3 years. This type is suitable for automated systems or long-running monitoring services that cannot renew the kubeconfig frequently.

    • By cluster access method:

      • Internal access: Obtain a kubeconfig for internal access. The kubectl client machine must be in the same Virtual Private Cloud (VPC) as the cluster. Connections over the Alibaba Cloud internal network have lower latency and are more secure.

      • Public access: Obtain a kubeconfig for public access, and use any machine on the Internet as a client to connect to the cluster. This method relies on an Elastic IP Address (EIP) to connect to the API Server and is suitable for local development or remote O&M.

        After you bind the EIP, see Pay-as-you-go for information about the associated fees.

    • If you use an ACK dedicated cluster with public access enabled, you can obtain the kubeconfig from the master node over SSH and then use kubectl locally to manage the cluster. For more information, see Connect to the master node of an ACK dedicated cluster over SSH.

    2. Get the kubeconfig and connect to the cluster

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

    Before a Resource Access Management (RAM) user connects to the cluster, the user must be granted cluster operation permissions in addition to the Container Service system permissions. For more information, see Authorization.

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

    2. On the Cluster List page, click the name of the destination cluster or click Details in the Actions column.

    3. On the Cluster Information page, click the Connection Information tab, and select a temporary or long-term kubeconfig. For a temporary kubeconfig, set an appropriate validity period.

    4. Select the Public Access or Internal Access tab, click Copy, paste the copied kubeconfig content into the $HOME/.kube/config file on the client, and save and exit the file.

      If the $HOME/.kube/config file does not exist, run mkdir -p $HOME/.kube and touch $HOME/.kube/config to create it.

    5. After the configuration is complete, run a kubectl command to verify cluster connectivity.

      The following example queries namespaces.

      kubectl get namespaces

      Expected output:

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

    Use in production

    • Make sure that the kubeconfig is valid: To prevent cluster access from being interrupted when a kubeconfig expires, renew it promptly.

      A long-term kubeconfig is valid for 3 years. As a best practice, obtain a new kubeconfig within 180 days before expiration through the ACK console or by calling DescribeClusterUserKubeconfig.

      The new kubeconfig is also valid for 3 years. The old kubeconfig remains valid until its certificate expires.

    • Quickly revoke a kubeconfig: If you suspect that a kubeconfig has been leaked, immediately Revoke a cluster's kubeconfig file. After the revocation, the system generates a new kubeconfig and authorization binding, and all connections based on the old kubeconfig become invalid.

    • Clean up permissions: When users no longer need access permissions, such as after a project ends or an employee leaves, use the Clean Up feature to revoke kubeconfig permissions in bulk. The system does not generate a new kubeconfig after cleanup. For instructions, see Delete kubeconfig files and Clean up user permissions with ack-ram-tool.

      To avoid deleting permissions by mistake, you can Use the kubeconfig recycle bin to restore the specified kubeconfig permissions that were cleared.

    FAQ

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

    Run the following command to obtain the identity information.

    grep client-certificate-data kubeconfig |awk '{print $2}' |base64 -d | openssl x509 -noout -text |grep Subject:
    Replace the kubeconfig path with your actual path. By default, kubectl uses $HOME/.kube/config to connect to the cluster. You can also set the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

    The expected output is similar to the following:

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

    Where:

    • O: The Kubernetes user group information. 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 associated with an Alibaba Cloud user ID under the account.

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

    Run the following command to obtain the expiration time associated with the certificate used by the kubeconfig file.

    grep client-certificate-data kubeconfig |awk '{print $2}' |base64 -d | openssl x509 -noout -enddate
    Replace the kubeconfig path with your actual path. By default, kubectl uses $HOME/.kube/config to connect to the cluster. You can also set the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

    The expected output is similar to the following:

    notAfter=Jan 10 06:44:34 2026 GMT

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

    Within 180 days before the certificate expires or after it expires, you can obtain a kubeconfig that uses a certificate with a new expiration time from the console or through OpenAPI.

    How do I get the client certificate, client private key, and API Server information?

    Use the following commands to extract the client certificate, client private 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}'`
    Replace the kubeconfig path with your actual path. By default, kubectl uses $HOME/.kube/config to connect to the cluster. You can also set the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

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

    After you bind a new IP address to the Server Load Balancer (SLB) instance of the cluster API Server, running kubectl commands to access the new IP address may fail with 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.

    • ACK managed cluster: Add the new IP address to the API Server certificate SAN. For more information, see Customize ACK API server certificate SANs.

    • ACK dedicated cluster: Configure kubectl to ignore this error by using the insecure-skip-tls-verify setting.

      Important

      This method prevents the client from verifying the API Server certificate and is not recommended for production environments. Instead, Hot migrate an ACK dedicated cluster to an ACK Pro cluster and then add the new IP address to the API Server certificate SAN to resolve this issue.

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

        kubectl -s https://<IP>:6443 --insecure-skip-tls-verify get ns

      • Method 2: Modify the kubeconfig file, add the insecure-skip-tls-verify: true setting, and then remove the certificate-authority-data setting.

        apiVersion: v1
clusters:
- cluster:
    server: https://<IP>:6443
    insecure-skip-tls-verify: true
  name: kubernetes
contexts:
...

    ACK managed cluster Can I obtain the cluster root certificate key to generate a kubeconfig certificate myself?

    ACK managed cluster does not provide the cluster root certificate key externally. Obtain the cluster kubeconfig through the console or OpenAPI instead.

    References