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 Platform 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
To prepare for this task, perform the following steps:
- Ensure that you have enabled the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- Ensure that you have installed the Cloud SDK.
- 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 regional clusters, set your default compute region:
gcloud config set compute/region [COMPUTE_REGION]
- Update
gcloudto 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 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 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 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 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 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.
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 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]
where [CLUSTER_NAME] is the name of the cluster.
The kubeconfig entry contains either:
- Your credentials as shown in
gcloud auth list, or - Your 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 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, you'd run the following command:
kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster
