Accessing a Cluster Using kubectl

Working Principles

kubectl retrieves cluster information from kubeconfig and communicates with the Kubernetes API server. kubeconfig is the identity credential for kubectl to access the cluster. It contains the API server address, user authentication credentials, and other configuration details. With these details, kubectl can interact with the cluster to perform management tasks.

Figure 1 Using kubectl to access a cluster

Prerequisites

• A client that can access the Internet is available.
• If private network access is used, the client and the cluster to be accessed must be in the same VPC.
• If public network access is used, the cluster to be accessed has an EIP bound. For details about how to bind an EIP, see Binding an EIP to an API Server.
  

  In a cluster with an EIP bound, kube-apiserver is exposed to the public internet and may be subject to attacks. You are advised to configure Advanced Anti-DDoS (AAD) for the kube-apiserver EIP.

Constraints

The kubeconfig.json file contains user information. CCE determines which Kubernetes resources can be accessed by kubectl based on the user information. The permissions recorded in a kubeconfig.json file vary by user.

For details about user permissions, see Permission Overview.

Step 1: Download kubectl

Before using kubectl to access a cluster, install kubectl on the client. Run the kubectl version command to check whether kubectl is installed. If it is installed, skip this step. Linux is used as an example to describe how to install and configure kubectl. For details, see Installing kubectl.

1. Log in to the client and download kubectl. v1.25.0 specifies the version. Replace it as needed.

   cd /home
   curl -LO https://dl.k8s.io/release/v1.25.0/bin/linux/amd64/kubectl

2. Run the following command to install kubectl:

   chmod +x kubectl
   mv -f kubectl /usr/local/bin

3. Run the following command to check whether kubectl has been installed:

   kubectl version

   If information similar to the following is displayed, kubectl has been installed:

   Client Version: xxx
   Kustomize Version: xxx
   Server Version: xxx

Step 2: Obtain the kubectl Configuration File (kubeconfig)

Obtain kubeconfig (the kubectl configuration file) from the cluster.

1. On the Overview page of the cluster console, go to the Connection Information area and click Configure next to kubectl.
   Figure 2 Cluster connection information
   

2. On the slide-out panel, locate the Download the kubeconfig file area, select Private access or Public access for Current data, and copy the configuration file.
   • If a cluster version is v1.27.7-r0, v1.28.5-r0, or later, access via private domain names, access via private IP addresses, and public network access are supported.
   • If a cluster version is earlier than v1.27.7-r0 or v1.28.5-r0, both private network access and public network access are supported. For private network access, only domain names can be used for access, and private IP addresses cannot be used.
   Figure 3 Downloading the configuration file
   
   

   • kubeconfig is the kubectl configuration file, which is used for cluster authentication. If the file is leaked, the cluster may be attacked.
   • For IAM users, the Kubernetes permissions specified in the configuration file are the same as those granted on the CCE console.
   • If the KUBECONFIG environment variable is configured in the Linux OS, kubectl preferentially loads this environment variable instead of $home/.kube/config.

Step 3: Configure kubectl

kubeconfig is stored on the client and used by kubectl to access and interact with the cluster.

1. Log in to the client.
2. Create the kubeconfig.yaml file. You can change the file name as needed. The file is used to store the configuration file information obtained in 2.

   vim kubeconfig.yaml

   Copy the configuration file information obtained in 2 to kubeconfig.yaml and save the file.

3. Save the kubeconfig.yaml file to $HOME/.kube/config. kubectl will automatically read from it. If you save the kubeconfig.yaml file in a different path, set the KUBECONFIG environment variable to point to that path.

   cd /home
   mkdir -p $HOME/.kube
   mv -f ~/kubeconfig.yaml $HOME/.kube/config  # Change kubeconfig.yaml to the file name.

4. Switch the kubectl access mode based on service scenarios.
   • If a private domain name is used for access within a VPC, run the following command:

     kubectl config use-context internal

   • If a private IP address is used for access within a VPC, run the following command:

     kubectl config use-context internalIP

   • If public network access is enabled and two-way domain name trust is not required, ensure the cluster has an EIP bound and then run the following command:

     kubectl config use-context external

   • If public network access is enabled and two-way domain name trust is required, ensure the cluster has an EIP bound and then run the following command:

     kubectl config use-context externalTLSVerify

     For more information about two-way domain name trust, see Two-Way Domain Name Trust.

5. Run the following command on the client to check whether the client can access the cluster using kubectl:

   kubectl cluster-info    # Check the cluster information.

   If the following information is displayed, the client can access the cluster using kubectl:

   Kubernetes control plane is running at https://xx.xx.xx.xx:5443
   CoreDNS is running at https://xx.xx.xx.xx:5443/api/v1/namespaces/kube-system/services/coredns:dns/proxy
   To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Two-Way Domain Name Trust

Two-way domain name trust is a mutual authentication mechanism that verifies the identities of both the client and server. This mechanism enhances security between clusters and clients, preventing unauthorized access.

• After an EIP is bound to the cluster's API server, two-way domain name trust is disabled by default if kubectl is used to access the cluster. You can run kubectl config use-context externalTLSVerify to enable the two-way domain name trust.
• When an EIP is bound to or unbound from the cluster, the cluster access address (including the EIP bound to the cluster) will be added to the cluster server certificate.
• Asynchronous cluster synchronization takes about 5 to 10 minutes. You can view the synchronization results in Synchronize Certificate in Operation Records.
• For a cluster that has an EIP bound, if the authentication fails (for example, "x509: certificate is valid" is displayed) when two-way domain name trust is used, bind the EIP again and download kubeconfig.yaml again.
• If two-way domain name trust is not supported, the kubeconfig.yaml file contains the "insecure-skip-tls-verify": true field, as shown in the figure below. To use two-way domain name trust, download the kubeconfig.yaml file again and enable two-way domain name trust.
  Figure 4 Two-way domain name trust disabled
  

Common Issues

• Error from server Forbidden

  When you use kubectl to create or query Kubernetes resources, the following information is displayed:

  # kubectl get deploy Error from server (Forbidden): deployments.apps is forbidden: User "0c97ac3cb280f4d91fa7c0096739e1f8" cannot list resource "deployments" in API group "apps" in the namespace "default"

  This is because the user does not have the permissions to operate the Kubernetes resources. For details about how to grant permissions, see Namespace Permissions (Kubernetes RBAC-based Authorization).

• The connection to the server localhost:8080 was refused

  When you use kubectl to create or query Kubernetes resources, the following information is displayed:

  The connection to the server localhost:8080 was refused - did you specify the right host or port?

  This is because cluster authentication is not configured for the kubectl client. For details, see Step 2: Obtain the kubectl Configuration File (kubeconfig).

Related Operations

• Connect to multiple clusters using kubectl.
• Configure the kubeconfig file for fine-grained management on cluster resources