Access scopes in GKE

This page describes the default access scopes granted to nodes in Google Kubernetes Engine (GKE) clusters. By reading this page, you learn about the default access scopes that are granted to clusters, and how you can configure custom access scopes, if required.

This page is for Security specialists and Operators who create and manage clusters, and must understand the default access that is granted to clusters and how to modify that access if needed. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE user roles and tasks .

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 . You can't modify the access scopes on existing node pools. Instead, create a new node pool with the new scopes and migrate workloads to that node pool.

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

Standard clusters

Configure a custom service account for workloads

IAM is the access control system for granting authorized roles to users and service accounts within your Google Cloud 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' 
 ` 
 

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

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 .

Create 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