This page explains how to configure cluster access for the
command-line tool in Google Kubernetes Engine.
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
The following sections explain how
kubeconfig works, how to set a default
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:
gcloud init, if you want to be walked through setting defaults.
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.
gcloud initand follow the directions:
If you are using SSH on a remote server, use the
--console-onlyflag to prevent the command from launching a browser:
gcloud init --console-only
Follow the instructions to authorize
gcloudto 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
gcloudto the latest version:
gcloud components update
Kubernetes configuration file
Kubernetes uses a YAML file called
kubeconfig to store
cluster authentication information for
kubeconfig contains a list
of contexts to which
kubectl refers when running commands. By default, the
file is saved at
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 commands run against that
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
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
When you run
gcloud container clusters get-credentials, you see that the
command gets the cluster endpoint as part of updating
Private clusters have two separate endpoint IP addresses:
which is an internal IP address, and
publicEndpoint, which is an external one.
endpoint field refers to the external IP, unless public access to the
endpoint is disabled, in which case the private IP will be used.
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
kubeconfig entry using a private cluster's internal IP address.
About authentication for
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
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,
kubectl the same credentials used by
gcloud itself. For example, if
gcloud auth login, your personal credentials are provided to
kubectl, including the
userinfo.email scope. This allows the
GKE cluster to authenticate the
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
To view the current context for
kubectl, run the following command:
kubectl config current-context
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
commands against it in your current environment. Otherwise, you need to
kubeconfig entry for the cluster.
kubectl commands against a cluster created in Cloud Console,
from another computer, or by another member of the project, you need to generate
kubeconfig entry in your environment.
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
kubeconfig entry contains either:
- Your credentials as shown in
gcloud auth list, or
- application default credentials, if configured.
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
gcloud container clusters get-credentials --internal-ip cluster-name
Setting a default cluster for
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-new-cluster. The current context is
my-new-cluster, but you want to
kubectl commands against
my-cluster. To switch the current context
my-cluster, you'd run the following command:
gcloud container clusters get-credentials my-cluster
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
For example, consider an environment with two clusters,
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 us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster
Insufficient authentication scopes
When you run
gcloud container clusters get-credentials you receive the following
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.
- 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
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