Access scopes in GKE

This page describes the default access scopes granted to nodes in Google Kubernetes Engine (GKE) clusters.

What are access scopes?

Access scopes are the legacy method of granting permissions for your nodes, and for workloads running on your nodes if the workloads use application default credentials (ADC). Access scopes define the OAuth scopes used in API calls from client libraries or the gcloud CLI.

We recommend that you don't specify your own access scopes. Instead, you should use IAM permissions or Kubernetes role-based access control (RBAC) to grant access to specific IAM service accounts or Kubernetes service accounts.

Default access scopes

When you create a new GKE cluster, Google Cloud assigns a default set of access scopes to nodes based on the service account used by the nodes. These access scopes enable specific functionality for GKE. You can also set access scopes manually using the --scopes flag when you create Standard clusters. Autopilot clusters, or node pools.

The following sections describe the default access scopes that GKE adds to nodes based on whether you specify a custom service account, and whether you manually specify access scopes.

Autopilot clusters

Service account	Did you manually specify access scopes?	Access scopes that GKE adds
Compute Engine default service account	No	https://www.googleapis.com/auth/devstorage.read_only https://www.googleapis.com/auth/service.management.readonly https://www.googleapis.com/auth/servicecontrol https://www.googleapis.com/auth/trace.append https://www.googleapis.com/auth/logging.write: added if Cloud Logging is enabled https://www.googleapis.com/auth/monitoring: added if Cloud Monitoring is enabled
	Yes	Manually specified scopes
Custom service account	No	https://www.googleapis.com/auth/cloud-platform
	Yes	Manually specified scopes

Standard clusters

Service account	Manually-specified access scopes?	GKE access scopes
Compute Engine default service account	No	https://www.googleapis.com/auth/devstorage.read_only https://www.googleapis.com/auth/service.management.readonly https://www.googleapis.com/auth/servicecontrol https://www.googleapis.com/auth/trace.append https://www.googleapis.com/auth/logging.write: added if Cloud Logging is enabled https://www.googleapis.com/auth/monitoring: added if Cloud Monitoring is enabled
	Yes	Manually specified scopes https://www.googleapis.com/auth/monitoring.write https://www.googleapis.com/auth/logging.write: added if Cloud Logging is enabled https://www.googleapis.com/auth/monitoring: added if Cloud Monitoring is enabled
Custom service account	No	https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform
	Yes	Manually specified scopes https://www.googleapis.com/auth/monitoring.write https://www.googleapis.com/auth/logging.write: added if Cloud Logging is enabled https://www.googleapis.com/auth/monitoring: added if Cloud Monitoring is enabled

Configuring a custom service account for workloads

IAM is the access control system for granting authorized roles to users and service accounts within your GCP project. A service account is a special Google account that performs tasks, such as deploying applications, on your behalf. You use IAM to create a service account, then use IAM policy bindings to secure the account.

If your workloads require access to Compute Engine, grant the service account the Compute Engine Admin role. If your workloads need to pull private images from Artifact Registry, see Configuring access control for Artifact Registry repositories.

Create a service account

To create a custom service account named kubernetes-engine-node-sa, run the following commands:

export NODE_SA_NAME=kubernetes-engine-node-sa
gcloud iam service-accounts create $NODE_SA_NAME \
  --display-name "GKE Node Service Account"
export NODE_SA_EMAIL=`gcloud iam service-accounts list --format='value(email)' \
  --filter='displayName:GKE Node Service Account'`

Note: These commands export two variables, $NODE_SA_NAME and $NODE_SA_EMAIL, that are used in commands documented later on this page.

Grant minimal roles

To configure the service account with the minimal necessary roles and permissions for your GKE node to function, run the following commands, where $PROJECT is your project ID:

export PROJECT=`gcloud config get-value project`
gcloud projects add-iam-policy-binding $PROJECT \
  --member serviceAccount:$NODE_SA_EMAIL \
  --role roles/monitoring.metricWriter
gcloud projects add-iam-policy-binding $PROJECT \
  --member serviceAccount:$NODE_SA_EMAIL \
  --role roles/monitoring.viewer
gcloud projects add-iam-policy-binding $PROJECT \
  --member serviceAccount:$NODE_SA_EMAIL \
  --role roles/logging.logWriter

Grant additional roles

Caution: The compute.admin role should not be granted to this service account unless necessary. Granting this role allows workloads to create, delete, read metadata on, and ssh into nodes, among other operations.

To grant the service account the Compute Engine Admin role, run the following command:

gcloud projects add-iam-policy-binding $PROJECT \
  --member serviceAccount:$NODE_SA_EMAIL \
  --role roles/compute.admin

To learn how to grant service accounts access to private images stored in Artifact Registry, see Granting access to Google Kubernetes Engine clusters.

Creating a cluster or node pool with the custom service account

To create a cluster that uses the custom service account, run the following command:

gcloud container clusters create --service-account=$NODE_SA_EMAIL

To create a node pool in an existing cluster:

gcloud container node-pools create --service-account=$NODE_SA_EMAIL

Note: You can also find the service account's email address by running the following command:

gcloud iam service-accounts list --format='value(email)' \
      --filter='displayName:Node Service Account'