Configure GKE node service accounts

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 then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the gcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.

Required roles

To get the permissions that you need to manage IAM service accounts and roles, ask your administrator to grant you the following IAM roles:

• Security Admin ( roles/iam.securityAdmin ) on the cluster project
• Configure service accounts in a separate project: Security Admin ( roles/iam.securityAdmin ) on the service account project

For more information about granting roles, see Manage access to projects, folders, and organizations .

You might also be able to get the required permissions through custom roles or other predefined roles .

Grant the minimum required role for GKE

GKE uses IAM service accounts that are attached to your nodes to run system tasks like logging and monitoring. At a minimum, these node service accounts must have the Kubernetes Engine Default Node Service Account ( roles/container.defaultNodeServiceAccount ) role on your project. By default, GKE uses the Compute Engine default service account , which is automatically created in your project, as the node service account.

If your organization enforces the iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint , the default Compute Engine service account in your project might not automatically get the required permissions for GKE.

The following sections show you how to grant the roles/container.defaultNodeServiceAccount role to the default Compute Engine service account or to a new custom service account that you create.

Configure the default Compute Engine service account

To grant the roles/container.defaultNodeServiceAccount role to the Compute Engine default service account, complete the following steps:

Configure a custom node service account

To create a custom service account and grant it the required role for GKE, complete the following steps:

  resource 
  
 "google_service_account" 
  
 "default" 
  
 { 
  
 account_id 
  
 = 
  
 "gke-node-service-account" 
  
 display_name 
  
 = 
  
 "GKE node service account" 
 } 
 data 
  
 "google_project" 
  
 "project" 
  
 { 
 } 
 resource 
  
 "google_project_iam_member" 
  
 "default" 
  
 { 
  
 project 
  
 = 
  
 data.google_project.project.project_id 
  
 role 
  
 = 
  
 "roles/container.defaultNodeServiceAccount" 
  
 member 
  
 = 
  
 "serviceAccount:${google_service_account.default.email}" 
 } 
 

You can also use this service account for resources in other projects. For instructions, see Enabling service account impersonation across projects .

Allow principals to attach custom service accounts

You can attach a custom service account when you create a cluster or a node pool. To let a principal (such as a platform administrator) use a custom service account to create GKE resources, grant the Service Account User ( roles/iam.serviceAccountUser ) role on the custom service account to that principal. To grant this role, select one of the following options:

 gcloud  
iam  
service-accounts  
add-iam-policy-binding  
 \ 
  
 SA_NAME 
@ SERVICE_ACCOUNT_PROJECT_ID 
.iam.gserviceaccount.com  
 \ 
  
--member = 
 PRINCIPAL 
  
 \ 
  
--role = 
roles/iam.serviceAccountUser 

  apiVersion 
 : 
  
 iam.cnrm.cloud.google.com/v1beta1 
 kind 
 : 
  
 IAMPolicyMember 
 metadata 
 : 
  
 name 
 : 
  
 policy-service-account-user 
 spec 
 : 
  
 member 
 : 
  
 serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com 
  
 role 
 : 
  
 roles/iam.serviceAccountUser 
  
 resourceRef 
 : 
  
 kind 
 : 
  
 Project 
  
 name 
 : 
  
 [ 
 PROJECT_ID 
 ] 
 

kubectl apply -f policy-service-account-user.yaml

After you grant the role on the service account, those principals can use that service account to create clusters and node pools. For more information, see the following documents:

• Create an Autopilot cluster
• Creating a regional cluster
• Add a node pool to a Standard cluster

Configure service account usage across projects

If your node service account isn't in the same project as your cluster, service agents in the cluster project need additional permissions on the service account. For more information, see Node service accounts and project service agents .

To grant the required roles on node service accounts that aren't in your cluster project, follow these steps:

1. To enable cross-project service account attachment, update your organization policies .

2. To grant the required roles on the custom service account to the service agents in your cluster project, select one of the following options:

   Console

   1. In the Google Cloud console, go to the Service accountspage.

      Go to Service accounts

   2. Select the checkbox for the custom service account that you created to use with GKE nodes.

   3. Click person_add Manage access. The Manage Accesspane opens.

   4. Grant the Service Account Token Creator role to the Compute Engine service agent in your cluster project:

      1. In the Manage Accesspane, click person_add Add principal. The Grant accesspane opens.

      2. In the New principalsfield, specify the email address of the Compute Engine service agent in your cluster project:

          service- CLUSTER_PROJECT_NUMBER 
         @compute-system.iam.gserviceaccount.com 
         

         Replace CLUSTER_PROJECT_NUMBER with the project number of your cluster project.

      3. In the Select a rolemenu, select the Service Account Token Creatorrole.

      4. Click Save. The Grant accesspane closes.

   5. Grant the Service Account User role to the GKE service agent in your cluster project:

      1. In the Manage Accesspane, click person_add Add principal. The Grant accesspane opens.

      2. In the New principalsfield, specify the email address of the GKE service agent in your cluster project:

          service- CLUSTER_PROJECT_NUMBER 
         @container-engine-robot.iam.gserviceaccount.com 
         

      3. In the Select a rolemenu, select the Service Account Userrole.

      4. Click Save. The Grant accesspane closes.

   6. Close the Manage Accesspane.

   gcloud

   1. Get the project number of your cluster project:

       gcloud  
      projects  
      describe  
       CLUSTER_PROJECT_ID 
        
       \ 
        
      --format = 
       'value(projectNumber)' 
       
      

      Replace CLUSTER_PROJECT_ID with the project ID of your cluster project.

      The output is similar to 123456789 .

   2. Grant the roles/iam.serviceAccountTokenCreator role on the custom service account to the Compute Engine service agent in your cluster project:

       gcloud  
      iam  
      service-accounts  
      add-iam-policy-binding  
       \ 
        
       SA_NAME 
      @ SERVICE_ACCOUNT_PROJECT_ID 
      .iam.gserviceaccount.com  
       \ 
        
      --member = 
      service- CLUSTER_PROJECT_NUMBER 
      @compute-system.iam.gserviceaccount.com  
       \ 
        
      --role = 
      roles/iam.serviceAccountTokenCreator 
      

      Replace the following:

      • SA_NAME : the name of the custom service account.
      • SERVICE_ACCOUNT_PROJECT_ID : the project ID of the project that contains your custom service account.
      • CLUSTER_PROJECT_NUMBER : the project number of your cluster project.

   3. Grant the roles/iam.serviceAccountUser role on the custom service account to the GKE service agent in your cluster project:

       gcloud  
      iam  
      service-accounts  
      add-iam-policy-binding  
       \ 
        
       SA_NAME 
      @ SERVICE_ACCOUNT_PROJECT_ID 
      .iam.gserviceaccount.com  
       \ 
        
      --member = 
      service- CLUSTER_PROJECT_NUMBER 
      @container-engine-robot.iam.gserviceaccount.com  
       \ 
        
      --role = 
      roles/iam.serviceAccountUser 
      

Allow image pulls from private repositories

If you have images in private Artifact Registry repositories, you must give your node service account access to those repositories. Even if you use the default Compute Engine service account, you might need to give the service account access to your repository if the repository is in another project.

To pull private images from Artifact Registry, grant the Artifact Registry Reader role ( roles/artifactregistry.reader ) on the repository to your node service account.

 gcloud  
artifacts  
repositories  
add-iam-policy-binding  
 REPOSITORY_NAME 
  
 \ 
  
--member = 
serviceAccount: SERVICE_ACCOUNT_EMAIL 
  
 \ 
  
--project = 
 REPOSITORY_PROJECT_ID 
  
 \ 
  
--role = 
roles/artifactregistry.reader 

What's next

• Create an Autopilot cluster
• Create a regional cluster
• Add a node pool to a Standard cluster