Install kubectl and configure cluster access

Autopilot Standard

---

This page explains how to install and configure the kubectl command-line tool to interact with your Google Kubernetes Engine (GKE) clusters.

Overview

kubectl is a command-line tool that you can use to interact with your GKE clusters. To use kubectl with GKE, you must install the tool and configure it to communicate with your clusters. Further kubectl configuration is required if you run multiple clusters in Google Cloud.

This page shows you the following:

• How kubectl works.
• How to install kubectl and any required dependencies.
• How to set a default cluster for kubectl.
• How to run kubectl commands against a specific cluster.

Before you begin

Before you start, make sure you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
  Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Install kubectl

You can install kubectl using the Google Cloud CLI or an external package manager such as apt or yum.

gcloud

1. Install the kubectl component:

   gcloud components install kubectl
   

2. Verify that kubectl is installed by checking it has the latest version:

   kubectl version --client
   

apt

1. Verify that you have the cloud-sdk repository:

   grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
   

   The output is similar to the following:

   deb  [signed-by=/usr/share/keyrings/cloud.google.gpg]  https://packages.cloud.google.com/apt cloud-sdk main
   

2. If the cloud-sdk repository is not listed then install the gcloud CLI.

3. Install the kubectl component:

   apt-get update
   apt-get install -y kubectl
   

4. Verify that kubectl is installed by checking it has the latest version:

   kubectl version --client
   

yum

1. Verify that you have the cloud-sdk repository:

   yum repolist | grep "google-cloud-sdk"
   

   Output is similar to the following:

   google-cloud-sdk    Google Cloud SDK    2,205
   

2. Install the kubectl component:

   yum install -y kubectl
   

3. Verify that kubectl is installed by checking it has the latest version:

   kubectl version --client
   

Install required plugins

kubectl and other Kubernetes clients require an authentication plugin, gke-gcloud-auth-plugin, which uses the Client-go Credential Plugins framework to provide authentication tokens to communicate with GKE clusters.

Before Kubernetes version 1.26 is released, gcloud CLI will start to require that the gke-gcloud-auth-plugin binary is installed. If not installed, existing installations of kubectl or other custom Kubernetes clients will stop working.

You must install this plugin to use kubectl and other clients to interact with GKE. Existing clients display an error message if the plugin is not installed.

Before you begin, check whether the plugin is already installed:

gke-gcloud-auth-plugin --version

If the output displays version information, skip this section.

You can install the authentication plugin using the gcloud CLI or an external package manager such as apt or yum.

gcloud

Install the gke-gcloud-auth-plugin binary:

  gcloud components install gke-gcloud-auth-plugin

apt

Install the gke-gcloud-auth-plugin binary:

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

yum

Install the gke-gcloud-auth-plugin binary:

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

Verify the gke-gcloud-auth-plugin binary installation:

1. Check the gke-gcloud-auth-plugin binary version:

   gke-gcloud-auth-plugin --version
   

2. Update the kubectl configuration to use the plugin:

   gcloud container clusters get-credentials CLUSTER_NAME \
       --region=COMPUTE_REGION
   

   Replace the following:

   • CLUSTER_NAME: the name of your cluster.
   • COMPUTE_REGION: the Compute Engine region for your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.

3. Verify the configuration:

   kubectl get namespaces
   

   The output is similar to the following:

   NAME              STATUS   AGE
   default           Active   51d
   kube-node-lease   Active   51d
   kube-public       Active   51d
   kube-system       Active   51d
   

For more information about why this plugin is required, see the Kubernetes KEP.

Interact with kubectl

Kubernetes uses a YAML file called kubeconfig to store cluster authentication information for kubectl. By default, the file is saved at $HOME/.kube/config.

kubeconfig contains a group of access parameters called contexts. Each context contains a Kubernetes cluster, a user, and an optional default namespace. kubectl refers to contexts when running commands.

The following are tasks you can complete to configure kubectl:

• Choose which cluster kubectl talks to.
• Set a default cluster for kubectl by setting the current context in the kubeconfig file.
• Run kubectl commands against a specific cluster using the --cluster flag.

View kubeconfig

To view your environment's kubeconfig, run the following command:

kubectl config view

The command returns a list of all clusters for which kubeconfig entries have been generated. If a GKE cluster is listed, you can run kubectl commands against it in your current environment. Otherwise, you need to Store cluster information for kubectl.

View the current context for kubectl

The current context is the cluster that is currently the default for kubectl. All kubectl commands run against that cluster.

When you create a cluster using gcloud container clusters create-auto, an entry is automatically added to the kubeconfig file in your environment, and the current context changes to that cluster. For example:

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

To view the current context for kubectl, run the following command:

kubectl config current-context

Store cluster information for kubectl

When you create a cluster using the Google Cloud console or using gcloud CLI from a different computer, your environment's kubeconfig file is not updated. Additionally, if a project team member uses gcloud CLI to create a cluster from their computer, their kubeconfig is updated but yours is not. The kubeconfig entry contains either:

• Your credentials as shown in gcloud auth list, or
• The application default credentials, if configured.

To generate a kubeconfig context in your environment, ensure that you have the container.clusters.get permission. The least-privileged IAM role that provides this permission is container.clusterViewer.

To generate a kubeconfig context for a specific cluster, run the following command:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=CLUSTER_REGION

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• COMPUTE_REGION: the Compute Engine region for your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.

Note: Running gcloud container clusters get-credentials also changes the current context for kubectl to that cluster.

Generate a kubeconfig entry using a private cluster's internal IP address

All clusters have a canonical endpoint. The endpoint exposes the Kubernetes API server that kubectl and other services use to communicate with your cluster control plane.

Private clusters have two separate endpoint IP addresses: privateEndpoint, which is an internal IP address, and publicEndpoint, which is an external external IP address. The endpoint field refers to the external IP address, unless public access to the endpoint is disabled, in which case the private IP address will be used.

For private clusters, if you prefer to use the internal IP address as the endpoint, run the following command:

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Replace CLUSTER_NAME with the name of your cluster.

Running get-credentials uses the IP address specified in the endpoint field by default.

Set a default cluster for kubectl commands

If you have previously generated a kubeconfig entry for clusters, you can switch the current context for kubectl to that cluster by running the following command:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• COMPUTE_REGION: the Compute Engine region for your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.

For example, consider a project with two clusters, my-cluster and my-new-cluster. The current context is my-new-cluster, but you want to run all kubectl commands against my-cluster. To switch the current context from my-new-cluster to my-cluster, run the following command:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

Run individual kubectl commands against a specific cluster

You can run individual kubectl commands against a specific cluster by using --cluster=CLUSTER_NAME.

For example, consider an environment with two clusters, my-cluster and my-new-cluster, in which the current context is my-cluster. You want to deploy an application to my-new-cluster, but you don't want to change the current context. To deploy the application to my-new-cluster without changing the current context, you would run the following command:

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

Troubleshooting

For additional troubleshooting, refer to Troubleshooting common issues.

Insufficient authentication scopes

When you run gcloud container clusters get-credentials you receive the following error:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

This error occurs because you are attempting to access the Kubernetes Engine API from a Compute Engine VM that does not have the cloud-platform scope. For instructions on changing the scopes on your Compute Engine VM instance, see Creating and enabling service accounts for instances.

ERROR: executable gke-gcloud-auth-plugin not found

If the following error is received while trying to run kubectl or custom clients interacting with GKE, install the gke-gcloud-auth-plugin as described in Installation instructions. The error messages are similar to the following:

• Error sample

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.

• Error sample

Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

ERROR: panic: no Auth Provider found for name gcp

The error no Auth Provider found for name "gcp" is received if kubectl or custom Kubernetes clients have been built with Kubernetes client-go version 1.26 or later, as described in How it works. This can be resolved by the following steps:

1. Install gke-gcloud-auth-plugin as described in Installation instructions.

2. Update to the latest version of the gcloud CLI using gcloud components update.

3. Update the kubeconfig file.

   gcloud container clusters get-credentials CLUSTER_NAME \
       --region=COMPUTE_REGION
   

   Replace the following:

   • CLUSTER_NAME: the name of your cluster.
   • COMPUTE_REGION: the Compute Engine region for your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.

WARNING: the gcp auth plugin is deprecated, use gcloud instead

You might notice this warning message after you install the gke-gcloud-auth-plugin and run a kubectl command against a GKE cluster. This message appears if your client version is earlier than 1.26.

To tell your client to use the gke-gcloud-auth-plugin authentication plugin instead, do the following:

1. Open your shell login script in a text editor:

   Bash

   vi ~/.bashrc
   

   Zsh

   vi ~/.zshrc
   

   If you're using PowerShell, skip this step.

2. Set the following environment variable:

   Bash

   export USE_GKE_GCLOUD_AUTH_PLUGIN=True
   

   Zsh

   export USE_GKE_GCLOUD_AUTH_PLUGIN=True
   

   PowerShell

   [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
   

3. Apply the variable in your environment:

   Bash

   source ~/.bashrc
   

   Zsh

   source ~/.zshrc
   

   PowerShell

   Exit the terminal and open a new terminal session.

4. Update the gcloud CLI:

   gcloud components update
   

5. Authenticate to your cluster:

   gcloud container clusters get-credentials CLUSTER_NAME \
       --region=COMPUTE_REGION
   

   Replace the following:

   • CLUSTER_NAME: the name of your cluster.
   • COMPUTE_REGION: the Compute Engine region for your cluster. For zonal clusters, use --zone=COMPUTE_ZONE.

What's next

• Learn how to authorize access to resources in GKE clusters.
• Authenticate to Google Cloud services from GKE workloads.
• Read the kubectl cheat sheet.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how GKE performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try GKE free