This page provides instructions to install thekubectl command-line tool that'sused to manage and access Google Kubernetes Engine (GKE) clusters. Thekubectlconfiguration is required if you run multiple clusters in Google Cloud.

You learn the following:

• Howkubectl works.
• How toinstallkubectl and anyrequired dependencies.
• How toset a default cluster forkubectl.
• How torunkubectl commands against a specific cluster.

This page is for IT administrators, Operators, andDevelopers who set up, monitor, and manage cloud infrastructure,including provisioning and configuring cloud resources. To learn more aboutcommon roles and example tasks that are referenced in Google Cloud documentation,seeCommon GKE user roles andtasks.

Before reading this page, ensure that you're familiar withKuberneteskubectl.

Before you begin

Before you start, make sure that 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 theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

• Ensure that you have an existing Autopilot or Standardcluster. To create a new cluster, seeCreate an Autopilot cluster.

Installkubectl

You can installkubectl using the Google Cloud CLI or an external package manager, such asapt oryum.

Install required plugins

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

Before Kubernetes version 1.26 is released, gcloud CLI will startto require that thegke-gcloud-auth-plugin binary is installed. If the pluginis not installed, existing installations ofkubectl or other custom Kubernetesclients stop working.

Youmustinstall this plugin to usekubectl 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 anexternal package manager such asapt oryum.

gcloudcomponentsinstallgke-gcloud-auth-plugin

apt-getinstallgoogle-cloud-sdk-gke-gcloud-auth-plugin

yuminstallgoogle-cloud-sdk-gke-gcloud-auth-plugin

Verify thegke-gcloud-auth-plugin binary installation:

1. Check thegke-gcloud-auth-plugin binary version:

   gke-gcloud-auth-plugin--version

2. Update thekubectl configuration to use the plugin:

   gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

   Replace the following:

   • CLUSTER_NAME: the name of your cluster.
   • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

3. Verify the configuration by running the following command:

   kubectlgetnamespaces

   The output is similar to the following:

   NAME              STATUS   AGEdefault           Active   51dkube-node-lease   Active   51dkube-public       Active   51dkube-system       Active   51d

For more information about this plugin, see theKubernetesKEP.

Interact withkubectl

Kubernetes uses a YAML file calledkubeconfigto store cluster authentication information forkubectl. By default,the file is saved at$HOME/.kube/config.

kubeconfig contains a group of access parameters calledcontexts. Eachcontext contains a Kubernetes cluster, a user, and an optional defaultnamespace.kubectl refers to contexts when running commands.

Optionally, you can configurekubectl using the following tasks:

• Choose the cluster thatkubectl talks to.
• Set the default cluster forkubectl by setting the current context in thekubeconfig file.
• Runkubectl commands against a specific cluster by using the--clusterflag.

Viewkubeconfig

To view your environment'skubeconfig, run the following command:

kubectlconfigview

The command returns a list of all clusters for whichkubeconfig entries havebeen generated. If a GKE cluster is listed, you can runkubectlcommands against it in your current environment. Otherwise, you need toStorecluster information for kubectl.

View the current context forkubectl

Thecurrent context is the cluster that is currently the default forkubectl. Allkubectl commands run against that cluster.

When you create a cluster usinggcloud container clusters create-auto, anentry is automatically added to thekubeconfig file in your environment, andthe current context changes to that cluster. For example:

gcloud container clusters create-auto my-clusterCreating my-cluster...doneFetching cluster endpoint and auth data.kubeconfig entry generated for my-cluster

To view the current context forkubectl, run the following command:

kubectlconfigcurrent-context

Store cluster information forkubectl

When you create a cluster using the Google Cloud console or using gcloud CLI from adifferent computer, your environment'skubeconfig file isnot updated.Additionally, if a project team member uses gcloud CLI to create a cluster fromtheir computer, theirkubeconfig is updated but yours is not. Thekubeconfigentry contains either:

• Your credentials as shown ingcloud auth list, or
• Theapplication default credentials, if configured.

To generate akubeconfig context in your environment, ensure that you have thecontainer.clusters.get permission. The least-privileged IAMrole that provides this permission iscontainer.clusterViewer.

To generate akubeconfig context for a specific cluster, run thefollowing command:

gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

• The external IP address (if you have enabled the external endpoint)
• The internal IP address
• The DNS address (if IP access is disabled)To use the canonical endpoint by default, run theget-credentialscommand. For more control over which endpointkubectl uses, use the--internal-ip or--dns-endpoint flag.To update yourkubeconfig file to use the internal IP address, run thefollowing command:

gcloudcontainerclustersget-credentialsCLUSTER_NAME--internal-ip

To update yourkubeconfig file to use the DNS address, run the followingcommand:

gcloudcontainerclustersget-credentialsCLUSTER_NAME--dns-endpoint

ReplaceCLUSTER_NAME with the name of your cluster.

By default, runningget-credentials uses the IP address specified in theendpoint field.

Set a default cluster forkubectl commands

If you have previously generated a kubeconfig entry for clusters, you can switchthe current context forkubectl to that cluster by running the followingcommand:

gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

For example, consider a project with two clusters,my-cluster andmy-new-cluster. The current context ismy-new-cluster, but you want to runallkubectl commands againstmy-cluster. To switch the current contextfrommy-new-cluster tomy-cluster, run the following command:

gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

Run individualkubectl commands against a specific cluster

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

For example, consider an environment with two clusters,my-cluster andmy-new-cluster, in which the current context ismy-cluster. You want todeploy an application tomy-new-cluster, but you don't want to change thecurrent context. To deploy the application tomy-new-cluster without changingthe 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

What's next

• Learn how toauthorize access to resources in GKE clusters.
• Authenticate to Google Cloud services from GKE workloads.
• Read thekubectl cheat sheet.
• Troubleshoot thekubectl command-line tool.