All Products
Search
Document Center

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

Last Updated:Oct 08, 2023

In addition to using the Container Service for Kubernetes (ACK) console to manage clusters, you can also use kubectl, a command-line interface, to manage clusters and applications. This topic describes how to obtain the kubeconfig file of a cluster and then use kubectl to connect to the cluster

Introduction to kubectl and kubeconfig files

kubectl is a standard Kubernetes command-line tool. You can use kubectl to connect to and manage all types of ACK clusters, such as ACK dedicated clusters, ACK managed clusters, and ACK Serverless clusters. ACK managed clusters include ACK basic clusters and ACK Pro clusters.

A kubeconfig file stores information about the cluster, users, namespaces, and identity authentication mechanism. Kubectl uses a kubeconfig file to connect to an ACK cluster.

Connection methods

You can connect to an ACK cluster over the Internet or through a private connection.

  • Connect to the cluster over the Internet

    If an elastic IP address (EIP) is associated with the API server of the cluster, the API server is exposed to the Internet. In this case, the cluster has no limits on the client that you choose to access the cluster. For more information about how to enable Internet access for the API server, see Control public access to the API server of a cluster.

  • Connect to the cluster through a private connection

    If you want to connect to the cluster through a private connection, your client must be deployed in the same virtual private cloud (VPC) as the cluster.

    Log on to the ACK console and click the name of the cluster that you want to manage. Choose Cluster Information > Cluster Resources to obtain the VPC information.

Step 1: Install kubectl

Note

If you use a Resource Access Management (RAM) user, you must authorize the RAM user to manage your cluster before you connect to the cluster from a kubectl client. For more information, see Authorization overview.

  1. Decide the machine on which the kubectl client is installed and choose a method to connect to the cluster.

  2. Download kubectl and install it on the machine

    For more information, see Download and install kubectl.

Step 2: Select a type of cluster credentials

ACK Serverless provides two types of cluster credentials (kubeconfig files), which allow you to connect to a cluster over the Internet or through a private connection.

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

  2. On the Clusters page, click the name of the cluster that you want to manage and click Cluster Information in the left-side navigation pane.

  3. On the Cluster Information page, click the Connection Information tab. Then, select cluster credentials for connecting to the cluster over the Internet or through a private connection.

    Note

    You can also use a temporary kubeconfig file to control the validity period of the cluster credentials. This allows you to access the cluster in a more flexible manner. For more information, see Generate a temporary kubeconfig file.

    集群连接信息

Step 3: Add cluster credentials

By default, kubectl searches for the config file in the $HOME/.kube directory on the machine. The file stores the credentials that are used to access the cluster. Kubectl uses this file to connect to the cluster.

  1. Click the Public Access or Internal Access tab and then click Copy.

  2. Paste the credentials to the config file in the $HOME/.kube directory, save the file, and then exit.

    Note

    If the .kube folder 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 about how to connect to an ACK dedicated cluster by using SSH, see Use SSH to connect to the master nodes of an ACK dedicated cluster. 专有版集群

Step 4: Verify the connectivity

After you add the cluster credentials, run the kubectl command to verify the connectivity to the cluster. Run the following command to query the namespaces of the cluster:

kubectl get namespace

Expected output:

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

Generate a temporary kubeconfig file

You can use a temporary kubeconfig file to store cluster credentials and set the validity period of the temporary kubeconfig file. This allows you to access the cluster in a more flexible manner.

  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, set the validity period of the temporary kubeconfig file and select a connection mode: Public Access or Internal Access.

    tempo
    • To connect to the cluster over the Internet, select Public Access and click Generate Temporary kubeconfig. Then, click Copy to copy the content in the code block to the $HOME/.kube/config file on your client.

    • To connect to the cluster through a private connection, select Internal Access and click Generate Temporary kubeconfig. Then, click Copy to copy the content in the code block to the $HOME/.kube/config file on your client.

    After you complete the configuration, you can use the temporary kubeconfig file to connect to the cluster. You cannot connect to the cluster after the temporary kubeconfig file expires.

FAQ

Issue 1: How do I obtain the identity information of the user that is associated with the certificate used in a kubeconfig file?

Run the following command to obtain the identity information of the user that is associated with the certificate used in a kubeconfig file:

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 a cluster. You can also configure the KUBECONFIG environment variable or the --kubeconfig parameter to specify another kubeconfig file.

Expected output:

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

  • O indicates the information about the Kubernetes user group. In this example, the name of the user group is system:users.

  • CN indicates the user information. In this example, the user is 1***-1673419473. 1*** indicates the ID of an Alibaba Cloud user managed by your account.

Issue 2: 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 a cluster. You can also configure the KUBECONFIG environment variable or 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 indicates the expiration date of the certificate.

You can use the console or API to obtain a kubeconfig file that uses a new certificate within 60 days before the expiration date or after the current certificate expires.

Issue 3: What do I do if the "certificate is valid for" error is prompted when I use kubectl to connect to a cluster?

When the Server Load Balancer (SLB) instance of the API server is assigned a new IP address and you use kubectl to access the IP address, the kubectl command fails 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 returned.

  • If the cluster is an ACK managed cluster, you can resolve this issue by adding the IP address to the custom subject alternative names (SANs) for the API server certificate. For more information, see Customize the SAN of the API server certificate when you create an ACK cluster.

  • If the cluster is an ACK dedicated cluster, configure kubectl to ignore this issue.

    • You can specify the --insecure-skip-tls-verify parameter when you run the kubectl command.

      kubectl -s https://<IP>:6443 --insecure-skip-tls-verify get ns
    • You can also add the insecure-skip-tls-verify: true setting to the kubeconfig file and delete the certificate-authority-data setting.

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

Issue 4: Can I generate a kubeconfig file based on the private key of the root certificate used by an ACK managed cluster?

No, you cannot generate a kubeconfig file based on the private key of the root certificate used by an ACK managed cluster. The private key of the root certificate used by an ACK managed cluster is confidential. You can generate a kubeconfig file only in the ACK console or by calling the ACK API.

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.