This page guides you through authenticating securely to the Kubernetes API serverfrom GKE clusters. You can secure your cluster by ensuringthat only authorized users and applications access your Kubernetes resources.You'll learn about available authentication methods, the recommended authentication method,and how to authenticate users, applications, and legacy systems.

For information on authenticating Kubernetes workloads toGoogle Cloud APIs, refer toWorkload Identity Federation for GKE.

This page is for Security specialists and Operators who mustauthenticate securely to the Kubernetes API server from GKE clusters.This page provides essential information on available authentication methods and how to implement them. To learn more aboutcommon roles and example tasks that we reference in Google Cloud content, seeCommon GKE user roles and tasks.

Before reading this page, ensure that you're familiar with the following concepts:

• General overview of authentication in Google Cloud
• General overview of IAM and role-based access control (RBAC) in GKE
• General overview of Kubernetes methods for authentication

Before you begin

Before you start, make sure that you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task,install and theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

Authenticate users

GKE manages end-user authentication for you through theGoogle Cloud CLI. The gcloud CLI authenticates users toGoogle Cloud, sets up the Kubernetes configuration, gets an OAuth accesstoken for the cluster, and keeps the access token up-to-date.

All GKE clusters are configured to accept Google Clouduser and service account identities, by validating the credentials presented bykubectl and retrieving the email address associated with the user or serviceaccount identity. As a result, the credentials for those accounts must includetheuserinfo.email OAuth scope to successfully authenticate.

When you usegcloud toset up your environment'skubeconfig for anew or existing cluster,gcloudgiveskubectl the same credentials used bygcloud itself. For example, ifyou usegcloud auth login, your personal credentials are provided tokubectl, including theuserinfo.email scope. This allows theGKE cluster to authenticate thekubectl client.

Alternatively, you may choose to configurekubectl to use the credentials of aGoogle Cloud service account, while running on a Compute Engineinstance. However, by default, theuserinfo.email scope isnot included incredentials created by Compute Engine instances. Therefore, youmust addthis scope explicitly, such as by using the--scopes flag when theCompute Engine instance is created.

You can authorize actions in your cluster usingIdentity and Access Management (IAM) or Kubernetes Role Based Access Control (RBAC).

Authenticate with OAuth

To authenticate to your cluster using the OAuth method, perform the following:

1. Sign in to the gcloud CLI using your credentials. This opensa web browser to complete the authentication process to Google Cloud:

   gcloudauthlogin

   Caution: Don't perform this on a Compute Engine VM where all users haveaccess toroot. Use a service account for authentication. For details, seetheApplications within Google Cloud section.

2. Retrieve the Kubernetes credentials for a specific cluster:

   gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

   Replace the following:

   • CLUSTER_NAME: the name of the cluster.
   • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

3. Verify that you are authenticated:

   kubectlcluster-info

Once users or Google Cloud service accounts are authenticated, they mustalso beauthorized to perform any action on a GKE cluster.For more information on how to configure authorization, seerole-based access control.

Authenticate applications

You can also authenticate to the API server from an application in a Podwithout user interaction, such as from a script in your CI/CD pipeline. How youachieve this depends on the environment where your application is running.

Application in the same cluster

If your application is running in the same GKE cluster,use a Kubernetes service account to authenticate.

1. Create aKubernetes service account and attach it to your Pod. If your Pod already has a Kubernetes serviceaccount, or if you want to use the namespace's default service account,skip this step.

2. Use Kubernetes RBAC to grant the Kubernetes service account the permissionsthat your application requires.

   The following example grantsview permissions to resources in theprodnamespace to a service account namedcicd in thecicd-ns namespace:

   kubectlcreaterolebindingcicd-secret-viewer\--namespace=prod\--clusterrole=view\--serviceaccount=cicd-ns:cicd

3. At runtime, when your application sends a Kubernetes API request, the APIserver authenticates the service account credentials.

Applications within Google Cloud

If your application runs inside Google Cloud but outside the targetcluster (for example, a Compute Engine VM or another GKEcluster), you should authenticate to the API server using the IAMservice account credentials available in the environment.

1. Assign an IAM service account to your environment. If yourapplication is running inside a Compute Engine VM,assign an IAM service accountto the instance. If your application is running in a differentGKE cluster, useWorkload Identity Federation for GKE toconfigure your Pod to run as an IAM service account.

   The examples that follow useci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.comas the IAM service account.

2. Grant the IAM service account access to the cluster.

   The following example grants theroles/container.developerIAM role, which provides access to Kubernetes API objectsinside clusters:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com\--role=roles/container.developer

   Alternatively, you can use RBAC to grant the IAM serviceaccount access to the cluster. Run thekubectl create rolebinding commandfromApplications in the same cluster and use--user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.cominstead of the--service-account flag.

3. Retrieve the cluster credentials:

   gcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

   Your application is automatically authenticated using the IAMservice account set on the environment.

Applications in other environments

If your application is authenticating from an environment outsideGoogle Cloud, it cannot access managed IAM service accountcredentials. To retrieve cluster credentials, you can create an IAMservice account, download its key, and use the key at runtime from your serviceto retrieve cluster credentials with the gcloud CLI.

1. Create an IAM service account for your application. If youalready have an IAM service account, skip this step.

   The following command creates an IAM service account namedci-cd-pipeline:

   gcloudiamservice-accountscreateci-cd-pipeline

2. Grant the IAM service account access to your cluster.

   The following command grants theroles/container.developerIAM role to theci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.comIAM service account:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com\--role=roles/container.developer

   You can also use RBAC to grant the IAM service account accessto the cluster. Run thekubectl create rolebinding command fromApplications in the same cluster and use--user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.cominstead of the--service-account flag.

3. Create and download a key for your IAM service account. Makeit available to your application at runtime:

   gcloudiamservice-accountskeyscreategsa-key.json\--iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com

4. At runtime, in the environment running your application, authenticate to thegcloud CLI by using your IAM service account key:

   gcloudauthactivate-service-accountci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com\--key-file=gsa-key.json

5. Use the gcloud CLI to retrieve the cluster credentials:

   gcloudconfigsetprojectPROJECT_IDgcloudcontainerclustersget-credentialsCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION

Environments without gcloud

Using the gcloud CLI to retrieve cluster credentials is recommendedbecause this method is resilient to cluster events like a control planeIP rotationorcredential rotation.However, if you cannot install the gcloud CLI in your environment,you can still create a static kubeconfig file to authenticate to the cluster:

1. Create an IAM service account for your application. If youalready have an IAM service account, skip this step.

   The following command creates an IAM service account namedci-cd-pipeline:

   gcloudiamservice-accountscreateci-cd-pipeline

2. Grant the IAM service account access to your cluster.

   The following command grants theroles/container.developerIAM role to theci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.comIAM service account:

   gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com\--role=roles/container.developer

   You can also create acustom IAM role forfine-grained control over the permissions that you grant.

3. Create and download a key for your IAM service account.

   In the following example, the key file is namedgsa-key.json:

   gcloudiamservice-accountskeyscreategsa-key.json\--iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com

4. If you're using the DNS-based endpoint for control plane access, get theendpoint value for your cluster:

   gcloudcontainerclustersdescribeCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--format="value(endpoint)"

   If you're using the IP-based endpoint for control plane access, get theendpoint value from the preceding command, and get theclusterCaCertificate value for your cluster:

   gcloudcontainerclustersdescribeCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--format="value(masterAuth.clusterCaCertificate)"

5. Create akubeconfig.yaml file. Use the following format if you're usingthe DNS-based endpoint for control plane access:

   apiVersion:v1kind:Configclusters:-name:CLUSTER_NAMEcluster:server:https://endpointusers:-name:ci-cd-pipeline-gsauser:exec:apiVersion:client.authentication.k8s.io/v1beta1args:---use_application_default_credentialscommand:gke-gcloud-auth-plugininstallHint:Install gke-gcloud-auth-plugin for kubectl by followinghttps://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_pluginprovideClusterInfo:truecontexts:-context:cluster:CLUSTER_NAMEuser:ci-cd-pipeline-gsaname:CLUSTER_NAME-ci-cdcurrent-context:CLUSTER_NAME-ci-cd

   Replace the following:

   • CLUSTER_NAME: the name of your cluster.
   • endpoint: the value you obtained forendpointfrom the previous step.

   If you're using IP-based endpoints for control plane access, add the valueyou obtained forclusterCaCertificate from the preceding step in thecluster parameter of thekubeconfig.yaml file:

   apiVersion:v1kind:Configclusters:-name:CLUSTER_NAMEcluster:server:https://endpointcertificate-authority-data:masterAuth.clusterCaCertificateusers:...

   You don't need to decode the base64-encoded certificate.

6. Deploykubeconfig.yaml andgsa-key.json alongside your application inyour environment. At runtime, in the environment running your application,set these environment variables:

   exportKUBECONFIG=path/to/kubeconfig.yamlexportGOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json

7. Your application can now send requests to the Kubernetes API and will beauthenticated as the IAM service account.

Update legacy authentication methods

If enabled, a user with thecontainer.clusters.getCredentials permission canretrieve the client certificate and static password. Theroles/container.admin,roles/owner, androles/editor roles all have this permission, so use thoseroles wisely. Read more aboutIAM roles in GKE.

Disable authentication with a static password

A static password is a username and password combination that the API servervalidates. In GKE, this authentication method is referred toas basic authentication.

gcloudcontainerclustersupdateCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION\--no-enable-basic-auth

With certificate authentication, a client presents a certificate that the APIserver verifies with the specified certificate authority. In GKE,thecluster root Certificate Authority (CA)signs client certificates.

Client certificate authentication has implications on authorization to theKubernetes API server. If legacyAttribute Based Access Control (ABAC) authorization is enabled on the cluster, by default, client certificates canauthenticate and perform any action on the API server. On the other hand, withRole Based Access Control (RBAC) enabled, client certificates must be grantedspecific authorization to Kubernetes resources.

gcloudcontainerclusterscreateCLUSTER_NAME\--location=CONTROL_PLANE_LOCATION--no-issue-client-certificate

What's next

• Learn aboutGoogle Cloud Authentication.
• Learn aboutAccess Control in GKE.
• Learn aboutGoogle service accounts.
• Learn aboutWorkload Identity Federation for GKE.
• Learn aboutHardening your cluster's security