This page describes the supported authentication methods when connecting to the Kubernetes API server in Google Kubernetes Engine (GKE).
For information on authenticating Kubernetes workloads to Google Cloud APIs, see Workload Identity instead.
Overview
There are several methods for authenticating to a Kubernetes API server. In GKE, OAuth authentication is recommended for cluster authentication and is automatically configured for you.
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
Authenticating users
GKE manages end-user authentication for you through the
gcloud
command-line tool. The gcloud
tool authenticates users to
Google Cloud, sets up the Kubernetes configuration, gets an OAuth access
token for the cluster, and keeps the access token up-to-date. You can control
access to your cluster Identity and Access Management (IAM) or Kubernetes Role Based Access Control (RBAC).
Prior to GKE's integration with OAuth, the pre-provisioned x509 certificate or static password were the only available authentication methods, but these methods are now not recommended and are disabled by default on new clusters since GKE version 1.12 and later. If you are using legacy authentication methods, we recommend that you migrate off these methods.
Authenticating using OAuth
To authenticate to your cluster using the OAuth method, perform the following:
Sign in to the
gcloud
tool using your credentials. This will open a web browser to complete the authentication process to Google Cloud:gcloud auth login
Retrieve the Kubernetes credentials for a specific cluster:
gcloud container clusters get-credentials CLUSTER_NAME \ --zone=COMPUTE_ZONE
You are now authenticated. Verify the results by using the following
kubectl
command:kubectl cluster-info
Authenticating services
Sometimes you might need to authenticate to a GKE cluster's API server from a service without user interaction (for example, a CI/CD pipeline script). How you achieve this depends on the environment where your service is running.
Service within the same GKE cluster
If your service is running in a Pod inside the GKE cluster you wish to connect to, use a Kubernetes service account to authenticate.
Create a Kubernetes service account and attach it to your Pod. If your Pod already has a Kubernetes service account, you may skip this step.
In our example, we use a Kubernetes service account named
cicd
in thecicd-ns
namespace.Grant the Kubernetes service account the correct permissions by using Kubernetes RBAC.
In our example, we grant the
edit
role in aprod
namespace; however, in practice, you should grant a role that fits your needs.kubectl create rolebinding cicd \ --clusterrole=edit \ --serviceaccount=cicd-ns:cicd \ --namespace=prod
At runtime, when your service invokes
kubectl
, it will automatically receive the credentials you configured.
Service within Google Cloud
If your service runs inside Google Cloud (for example, a Compute Engine VM or another GKE cluster), you should authenticate to the API server using the Google service account credentials available in the environment.
Assign a Google service account to your Compute Engine environment. If your service is running inside a Compute Engine VM, assign a Google service account to the instance. If your service is running inside a GKE cluster, use Workload Identity to configure your Pod to run as a Google service account.
In our example, we use
ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
as the Google service account.Grant the Google service account access to the desired cluster.
In our example, we grant the
roles/container.developer
IAM role, which provides access to Kubernetes API objects inside clusters:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/container.developer
Retrieve the cluster credentials:
gcloud container clusters get-credentials CLUSTER_NAME \ --zone=COMPUTE_ZONE
Your service will automatically be authenticated using the Google service account set on the environment.
Service in other environments
If your service is authenticating from an environment outside
Google Cloud, it will not have access to managed Google service account
credentials. To retrieve cluster credentials, you will need to create a Google
service account, download its key, and use the key at runtime from your service
to retrieve cluster credentials with the gcloud
tool.
Create a Google service account for your service. If you already have a Google service account, you may skip this step.
In our example, we create a service account named
ci-cd-pipeline
:gcloud iam service-accounts create ci-cd-pipeline
Grant the Google service account access to your cluster.
In our example, we use
ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
as the Google service account, and we grant theroles/container.developer
IAM role, which provides access to Kubernetes API objects inside clusters:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/container.developer
We granted access by using IAM. You can also grant this access using Kubernetes RBAC for more fine-grained control.
Create and download a key for your Google service account. Make it available to your service at runtime:
gcloud iam service-accounts keys create gsa-key.json \ --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
At runtime, in the environment running your service, authenticate to the
gcloud
tool by using your Google service account key:gcloud auth activate-service-account ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \ --key-file=gsa-key.json
This requires the
gcloud
tool to be installed in your environment. To learn how to install thegcloud
tool, see Installing Cloud SDK. If you cannot install thegcloud
tool in your environment, see the Environments without gcloud section.Use the
gcloud
tool to retrieve the cluster credentials:gcloud config set project PROJECT_ID gcloud container clusters get-credentials CLUSTER_NAME \ --zone=COMPUTE_ZONE
Environments without gcloud
Using the gcloud
tool to retrieve cluster credentials is recommended
because this method is resilient to cluster events like a control plane IP rotation
or credential rotation.
However, if you cannot install the gcloud
tool in your environment,
you can still create a static kubeconfig file to authenticate to the cluster:
Create a Google service account for your service. If you already have a Google service account, you may skip this step.
In our example, we create a service account named
ci-cd-pipeline
:gcloud iam service-accounts create ci-cd-pipeline
Grant the Google service account access to your cluster.
In our example, we use
ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
as the Google service account, and we grant theroles/container.developer
IAM role, which provides access to Kubernetes API objects inside clusters:gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com --role=roles/container.developer
We granted access by using IAM. You can also grant this access using Kubernetes RBAC for more fine-grained control.
Create and download a key for your Google service account.
In our example, the key file is named
gsa-key.json
:gcloud iam service-accounts keys create gsa-key.json \ --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
Obtain the
endpoint
andclusterCaCertificate
values for your cluster:gcloud container clusters describe CLUSTER_NAME \ --zone=COMPUTE_ZONE \ --format="value(endpoint)" gcloud container clusters describe CLUSTER_NAME \ --zone=COMPUTE_ZONE \ --format="value(masterAuth.clusterCaCertificate)"
Create a
kubeconfig.yaml
file containing the following:apiVersion: v1 kind: Config clusters: - name: CLUSTER_NAME cluster: server: https://endpoint certificate-authority-data: masterAuth.clusterCaCertificate users: - name: ci-cd-pipeline-gsa user: auth-provider: name: gcp contexts: - context: cluster: CLUSTER_NAME user: ci-cd-pipeline-gsa name: CLUSTER_NAME-ci-cd current-context: CLUSTER_NAME-ci-cd
Replace the following:
- CLUSTER_NAME: the name of your cluster.
- endpoint: the value you obtained for
endpoint
from the previous step. - masterAuth.clusterCaCertificate: the value you obtained for
clusterCaCertificate
from the previous step (you don't need to decode the base64-encoded certificate).
Deploy
kubeconfig.yaml
andgsa-key.json
alongside your service in your environment. At runtime, in the environment running your service, set these environment variables:export KUBECONFIG=path/to/kubeconfig.yaml export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
Your service can now invoke
kubectl
and will be authenticated as the Google service account.
Legacy authentication methods
Prior to GKE's integration with OAuth, a one-time generated x509 certificate or static password were the only available authentication methods, but are now not recommended and should be disabled. These methods present a wider surface of attack for cluster compromise and have been disabled by default since GKE version 1.12. If you are using legacy authentication methods, we recommend that you turn them off. Authentication with a static password is deprecated and has been removed since GKE version 1.19.
If enabled, the client certificate and static password can be retrieved by a
user with thecontainer.clusters.getCredentials
permission. Note that the
roles/container.admin
, roles/owner
androles/editor
roles all have this
permission, so use those roles wisely. Read more about IAM roles in GKE.
Disabling authentication with a static password
A static password is a username and password combination that the API server validates. In GKE, this authentication method is referred to as basic authentication.
To update an existing cluster and remove the static password:
gcloud container clusters update CLUSTER_NAME --no-enable-basic-auth
Disabling authentication with a client certificate
With certificate authentication, a client presents a certificate that the API server verifies with the specified certificate authority. In GKE, client certificates are signed by the cluster root Certificate Authority (CA).
Client certificate authentication has implications on authorization to the Kubernetes API server. If legacy Attribute Based Access Control (ABAC) authorization is enabled on the cluster, by default, client certificates can authenticate and perform any action on the API server. On the other hand, with Role Based Access Control (RBAC) enabled, client certificates must be granted specific authorization to Kubernetes resources.
To create a cluster without generating a client certificate, use the
--no-issue-client-certificate
flag:
gcloud container clusters create CLUSTER_NAME --no-issue-client-certificate
Currently, there is no way to remove a client certificate from an existing cluster. To stop using client certificate authentication on an existing cluster, ensure you have RBAC enabled on the cluster, and that the client certificate does not have any authorization on the cluster.
What's next
- Learn about Google Cloud Authentication.
- Learn about Access Control in GKE.
- Learn about Google service accounts.
- Learn about Workload Identity.
- Learn about Hardening your cluster's security