This page explains how to configure cluster access for the kubectl
command-line tool in Google Kubernetes Engine.
Overview
If you run multiple clusters within your Google Cloud project, you need to
choose which cluster kubectl
talks to. You can set a
default cluster for kubectl
by setting the current context in Kubernetes'
kubeconfig
file. Additionally, you can run kubectl
commands against a
specific cluster using the --cluster
flag.
The following sections explain how kubeconfig
works, how to set a default
cluster for kubectl
, and how to run individual kubectl
commands against
a specific cluster.
Before you begin
Before you start, make sure you have performed the following tasks:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
Set up default gcloud
settings using one of the following methods:
- Using
gcloud init
, if you want to be walked through setting defaults. - Using
gcloud config
, to individually set your project ID, zone, and region.
Using gcloud init
If you receive the error One of [--zone, --region] must be supplied: Please specify
location
, complete this section.
-
Run
gcloud init
and follow the directions:gcloud init
If you are using SSH on a remote server, use the
--console-only
flag to prevent the command from launching a browser:gcloud init --console-only
-
Follow the instructions to authorize
gcloud
to use your Google Cloud account. - Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.
Using gcloud config
- Set your default project ID:
gcloud config set project PROJECT_ID
- If you are working with zonal clusters, set your default compute zone:
gcloud config set compute/zone COMPUTE_ZONE
- If you are working with Autopilot or regional clusters, set your default compute region:
gcloud config set compute/region COMPUTE_REGION
- Update
gcloud
to the latest version:gcloud components update
Kubernetes configuration file
Kubernetes uses a YAML file called kubeconfig
to store
cluster authentication information for kubectl
. kubeconfig
contains a list
of contexts to which kubectl
refers when running commands. By default, the
file 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 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 updated but yours is not. Follow the
instructions below to add these clusters to your
local kubeconfig
.
About the cluster endpoint
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 (master). The endpoint IP is displayed in Cloud Console under
the Endpoints field of the cluster's Details tab, and in the output of
gcloud container clusters describe
in the endpoint
field.
When you run gcloud container clusters get-credentials
, you see that the
command gets the cluster endpoint as part of updating kubeconfig
.
Private clusters have two separate endpoint IP addresses: privateEndpoint
,
which is an internal IP address, and publicEndpoint
, which is an external one.
The endpoint
field refers to the external IP, unless public access to the
endpoint is disabled, in which case the private IP will be used.
Running get-credentials
uses the IP specified in the endpoint
field by default.
For private clusters if you prefer to use the internal IP as the endpoint, see
Generating a kubeconfig
entry using a private cluster's internal IP address.
About authentication for kubectl
All GKE clusters are configured to accept Google Cloud
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 or existing 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 configure kubectl
to use the credentials of a
Google Cloud 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. Therefore, you must add
this scope explicitly, such as by using the --scopes
flag when the
Compute Engine instance is created.
Once users or Google Cloud service accounts are authenticated, they must also be authorized to perform any action on a GKE cluster. See role-based access control for more information on how to configure authorization.
For information on supported authentication methods when connecting to the Kubernetes API server, see Authenticating to the Kubernetes API server.
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 for the cluster.
Generating a kubeconfig
entry
To run kubectl
commands against a cluster created in Cloud 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
where cluster-name is the name of the cluster.
This command requires you to have the container.clusters.get
permission. The
least-privileged IAM role that provides this permission is
container.clusterViewer
.
The kubeconfig
entry contains either:
- Your credentials as shown in
gcloud auth list
, or - application default credentials, if configured.
Generating a kubeconfig
entry using a private cluster's internal IP address
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
Setting 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:
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
. To switch the current context
from my-new-cluster
to my-cluster
, you'd run the following command:
gcloud container clusters get-credentials my-cluster
Running individual kubectl
commands against a specific cluster
You can run individual kubectl
commands against a specific cluster by passing
in the name of the cluster as it appears in
kubeconfig
as the argument for the --cluster
flag.
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'd run the following command:
kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster
Troubleshooting
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.
What's next
- Learn how to authorize access to resources in GKE clusters.
- Learn how to authenticate to Google Cloud services from Kubernetes workloads with Google Cloud service accounts.
- 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