7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

Kubernetes Engine  (https://cloud.google.com/kubernetes-engine/)  Documentation  (https://cloud.google.c

Con guring cluster access for kubectl
This page explains how to con gure cluster access for the kubectl command-line tool in
Google Kubernetes Engine.

Overview

If you run multiple clusters

 (https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-architecture) within your Google
Cloud Platform project, you need to choose which cluster kubectl
 (https://kubernetes.io/docs/reference/kubectl/overview/) talks to. You can set a default cluster for
kubectl by setting the current context in Kubernetes' kubeconfig le. Additionally, you can run
kubectl commands against a speci c cluster using the --cluster ag.

The following sections explain how kubeconfig works, how to set a default cluster for
kubectl, and how to run individual kubectl commands against a speci c cluster.

Before you begin

To prepare for this task, perform the following steps:

Ensure that you have enabled the Google Kubernetes Engine API.

ENABLE GOOGLE KUBERNETES ENGINE API (HTTPS://CONSOLE.CLOUD.GOOGLE.COM/APIS/LIBRARY

Ensure that you have installed the Cloud SDK (https://cloud.google.com/sdk/downloads).

Set your default project ID  (https://support.google.com/cloud/answer/6158840):

gcloud config set project [PROJECT_ID] 

If you are working with zonal clusters, set your default compute zone
 (https://cloud.google.com/compute/docs/zones#available):

gcloud config set compute/zone [COMPUTE_ZONE] 

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 1/6
7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

If you are working with regional clusters, set your default compute region
 (https://cloud.google.com/compute/docs/zones#available):

gcloud config set compute/region [COMPUTE_REGION] 

Update gcloud to the latest version:

gcloud components update 

 Note: You can override these default settings in gcloud commands using the --project, --zone, and
--region operational ags.

Kubernetes con guration le

Kubernetes uses a YAML le called kubeconfig

 (https://kubernetes.io/docs/tasks/access-application-cluster/con gure-access-multiple-clusters/) to
store cluster authentication information for kubectl. kubeconfig contains a list of contexts to
which kubectl refers when running commands. By default, the le is saved at
$HOME/.kube/config.

A context is a group of access parameters. Each context contains a Kubernetes cluster, a user,
and a namespace. 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, an entry is
automatically added to the kubeconfig in your environment, and the current context changes
to that cluster:

gcloud container clusters create my-cluster

Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

When you create a cluster using Google Cloud Platform Console or using gcloud from a
different computer, your environment's kubeconfig is not updated. Additionally, if a project
team member uses gcloud to create a cluster from their computer, their kubeconfig is

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 2/6
7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

updated but yours is not. Follow the instructions below (#generate_kubecon g_entry) to add these
clusters to your local kubeconfig.

About the cluster endpoint

All clusters have a canonical endpoint. The endpoint is the IP address of the Kubernetes API
server that kubectl and other services use to communicate with your cluster master. The
endpoint is displayed in GCP Console under the Endpoints eld of the cluster's Details tab, and
in the output of gcloud container clusters describe in the endpoint eld.

When you run gcloud container clusters get-credentials, you see that the command
gets the cluster endpoint as part of updating kubeconfig.

Private clusters (https://cloud.google.com/kubernetes-engine/docs/concepts/private-clusters#endpoints)
have two unique endpoint values: privateEndpoint, which is an internal IP address, and
publicEndpoint, which is an external one. Running get-credentials against a private
cluster sets the external IP address as the endpoint by default. If you prefer to use the internal
IP as the endpoint, see Generating a kubeconfig entry using a private cluster's internal IP
address (#internal_ip).

About authentication for kubectl

All GKE clusters are con gured to accept GCP user and service account identities, by validating
the credentials presented by kubectl and retrieving the email address associated with the
user or service account identity. As a result, the credentials for those accounts must include
the userinfo.email OAuth scope in order to successfully authenticate.

When you use gcloud to set up your environment's kubeconfig for a new (#kubecon g) or
existing (#generate_kubecon g_entry) cluster, gcloud gives kubectl the same credentials used by
gcloud itself. For example, if you use gcloud auth login, your personal credentials are
provided to kubectl, including the userinfo.email scope. This allows the GKE cluster to
authenticate the kubectl client.

Alternatively, you may choose to con gure kubectl to use the credentials of a GCP service
account, while running on a Compute Engine instance. However, by default, the
userinfo.email scope is not included in credentials created by Compute Engine instances.

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 3/6
7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

Therefore, you must add this scope explicitly, such as by using the --scopes ag when the
Compute Engine instance is created.

Once users or GCP service accounts are authenticated, they must also be authorized to
perform any action on a GKE cluster. See role-based access control
 (https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control) for more
information on how to con gure authorization.

Viewing the current context for kubectl

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

kubectl config current-context 

Viewing 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 generate a kubeconfig entry (#generate_kubecon g_entry)
for the cluster.

Generating a kubeconfig entry

To run kubectl commands against a cluster created in GCP Console, from another computer,
or by another member of the project, you need to generate a kubeconfig entry in your
environment.

Generate a kubeconfig entry by running the following command:

gcloud container clusters get-credentials [CLUSTER_NAME] 

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 4/6
7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

where [CLUSTER_NAME] is the name of the cluster.

The kubeconfig entry contains either:

A. Your credentials as shown in gcloud auth list, or

B. Your application default

 (https://cloud.google.com/sdk/gcloud/reference/auth/application-default/) credentials, if
con gured.

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

Generating a kubeconfig entry using a private cluster's internal IP

address

Beta

This is a Beta release of the --internal-ip ag. This feature is not covered by any SLA or deprecation
policy and might be subject to backward-incompatible changes.

When you run get-credentials, you can specify the --internal-ip to write a private
cluster's internal IP address to kubeconfig:

gcloud container clusters get-credentials --internal-ip [CLUSTER_NAME] 

Se ing a default cluster for kubectl commands

If you have previously generated a kubeconfig entry for clusters (#generate_kubecon g_entry),

you can switch the current context for kubectl to that cluster by running gcloud container
clusters get-credentials.

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.

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 5/6
7/28/2019 Configuring cluster access for kubectl | Kubernetes Engine Documentation | Google Cloud

To switch the current context to my-cluster, you'd run the following command:

gcloud container clusters get-credentials my-cluster

Running individual kubectl commands against a speci c cluster

You can run individual kubectl commands against a speci c cluster by passing in the name of
the cluster as it appears in kubeconfig (#viewing_kubecon g) as the argument for the --
cluster ag.

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, you'd run the following command:

kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster

What's next

Learn how to authorize access to resources in GKE clusters

 (https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).

Learn how to authenticate to GCP services from Kubernetes workloads with GCP service
accounts
 (https://cloud.google.com/kubernetes-engine/docs/tutorials/authenticating-to-cloud-platform).

Read the kubectl cheat sheet  (https://kubernetes.io/docs/reference/kubectl/cheatsheet/).

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
 (https://creativecommons.org/licenses/by/4.0/), and code samples are licensed under the Apache 2.0 License
 (https://www.apache.org/licenses/LICENSE-2.0). For details, see our Site Policies
 (https://developers.google.com/terms/site-policies). Java is a registered trademark of Oracle and/or its a liates.

Last updated April 15, 2019.

https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry 6/6