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.

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, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined 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, thesenode service accounts must have theKubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) role on your project. By default, GKE uses theCompute Engine default service account, which is automatically created in your project, as the node service account.

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

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_idrole="roles/container.defaultNodeServiceAccount"member="serviceAccount:${google_service_account.default.email}"}

You can also use this service account for resources in other projects. For instructions, seeEnabling 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 nodepool. To let a principal (such as a platform administrator) use a custom serviceaccount to create GKE resources, grant theService Account User(roles/iam.serviceAccountUser) role on the custom service account to thatprincipal. To grant this role, select one of the following options:

gcloudiamservice-accountsadd-iam-policy-binding\SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com\--member=PRINCIPAL\--role=roles/iam.serviceAccountUser

apiVersion:iam.cnrm.cloud.google.com/v1beta1kind:IAMPolicyMembermetadata:name:policy-service-account-userspec:member:serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.comrole:roles/iam.serviceAccountUserresourceRef:kind:Projectname:[PROJECT_ID]

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

After you grant the role on the service account, those principals can use thatservice account to create clusters and node pools. For more information, seethe 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, serviceagents in the cluster project need additional permissions on the serviceaccount. For more information, seeNode service accounts and project service agents.

To grant the required roles on node service accounts that aren't in your clusterproject, 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 serviceagents in your cluster project, select one of the following options:

   Console

   1. In the Google Cloud console, go to theService accounts page.

      Go to Service accounts

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

   3. Clickperson_addManage access.TheManage Access pane opens.

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

      1. In theManage Access pane, clickperson_addAdd principal.TheGrant access pane opens.

      2. In theNew principals field, specify the email address of theCompute Engine service agent in your cluster project:

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

         ReplaceCLUSTER_PROJECT_NUMBER with theproject number of your cluster project.

      3. In theSelect a role menu, select theService Account TokenCreator role.

      4. ClickSave. TheGrant access pane closes.

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

      1. In theManage Access pane, clickperson_addAdd principal.TheGrant access pane opens.

      2. In theNew principals field, specify the email address of theGKE service agent in your cluster project:

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

      3. In theSelect a role menu, select theService Account Userrole.

      4. ClickSave. TheGrant access pane closes.

   6. Close theManage Access pane.

   gcloud

   1. Get the project number of your cluster project:

      gcloudprojectsdescribeCLUSTER_PROJECT_ID\--format='value(projectNumber)'

      ReplaceCLUSTER_PROJECT_ID with the projectID of your cluster project.

      The output is similar to123456789.

   2. Grant theroles/iam.serviceAccountTokenCreator role on the customservice account to the Compute Engine service agent in yourcluster project:

      gcloudiamservice-accountsadd-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 serviceaccount.
      • SERVICE_ACCOUNT_PROJECT_ID: the projectID of the project that contains your custom service account.
      • CLUSTER_PROJECT_NUMBER: the projectnumber of your cluster project.

   3. Grant theroles/iam.serviceAccountUser role on the customservice account to the GKE service agent in yourcluster project:

      gcloudiamservice-accountsadd-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 nodeservice account access to those repositories. Even if you use the defaultCompute Engine service account, you might need to give the serviceaccount access to your repository if the repository is in another project.

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

gcloudartifactsrepositoriesadd-iam-policy-bindingREPOSITORY_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