Creating Cloud IAM policies

This page explains how to create Cloud Identity and Access Management (Cloud IAM) policies for authorization in Google Kubernetes Engine.


Every Google Cloud Platform (GCP), GKE, and Kubernetes API call requires that the account making the request has the necessary permissions. By default, no one except you or others granted permission by folder- and organization-level policies can access your project or its resources without being authenticated and authorized. You can use Cloud IAM to manage who can access your project and what they are allowed to do.

To grant users and service accounts access to your GCP project, you need to add them as project team members. Then, you need to assign roles. Roles define which GCP resources an account can access and which operations they can perform.

In GKE, you use Cloud IAM to manage which users and service accounts can access, and perform operations in, your clusters.

Before you begin

To prepare for this task, perform the following steps:

  • Ensure that you have enabled the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • Ensure that you have installed the Cloud SDK.
  • Set your default project ID:
    gcloud config set project [PROJECT_ID]
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone [COMPUTE_ZONE]
  • If you are working with regional clusters, set your default compute region:
    gcloud config set compute/region [COMPUTE_REGION]
  • Update gcloud to the latest version:
    gcloud components update

Interaction with role-based access control

Kubernetes' native role-based access control system also manages access to your cluster. RBAC controls access on a cluster- and namespace-level, while Cloud IAM works on the project-level.

Cloud IAM and RBAC can work in concert, and an entity must have sufficient permissions at either level to work with resources in your cluster.

Cloud IAM Roles

The following sections describe the Cloud IAM Roles available in GCP.

Predefined GKE Roles

Cloud IAM provides predefined Roles that grant access to specific GCP resources and prevent unauthorized access to other resources.

Cloud IAM offers the following predefined Roles for GKE:

Role Title Role Name Capabilities Target Users
GKE Admin roles/container.admin Full access to clusters and their Kubernetes resources.
  • Project owners/administrators
  • On-call engineers
  • System administrators
GKE Developer roles/container.developer Full access to Kubernetes resources running in clusters.
  • Developers
  • Release engineers
GKE Viewer roles/container.viewer Read-only access to clusters and their Kubernetes resources.
  • Users who only need visibility into clusters and their resources
GKE Cluster Admin roles/container.clusterAdmin
    When paired with Service Account User, grants permission to create, delete, update, and view clusters only. No access to Kubernetes resources.
  • Users who need to only manage clusters, and don't need to access cluster workloads.
GKE Cluster Viewer roles/container.clusterViewer Permission to get and list clusters. No access to Kubernetes resources.
  • Users who need read-only access to clusters.
  • Suitable for retrieving cluster information to configure kubectl.

To learn about permissions granted by each GKE Role, refer to Permissions granted by Cloud IAM Roles.

Primitive Cloud IAM Roles

Primitive Cloud IAM Roles grant users global, project-level access to all GCP resources. To keep your project and clusters secure, you should use predefined Roles whenever possible.

To learn more about primitive Roles, refer to Primitive Roles in the Cloud IAM documentation.

Service Account User Role

Service Account User grants users permission to complete certain tasks using a GCP service account. In GKE, users needing to create, or update clusters might require this Role. You pair the Service Account User Role with other Roles depending on the level of access an entity requires.

For example, if a user with the Cluster Admin Role needs to create a cluster, they need to access the cluster nodes' service account. Granting the user the Service Account User Role on that service account's Cloud IAM policy ensures that they have permission to use the service account:

gcloud iam service-accounts add-iam-policy-binding \
  --member=user:[USER] \
Role Title Role Name Capabilities Permissions
Service Account User roles/iam.serviceAccountUser Access to project-level or service-specific service accounts.
  • iam.serviceAccounts.actAs
  • iam.serviceAccounts.get
  • iam.serviceAccounts.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

Host Service Agent User Role

The Host Service Agent User Role is only used in Shared VPC clusters.

Role Title Role Name Capabilities Permissions
Host Service Agent User roles/container.hostServiceAgentUser Used with Shared VPC. Grants permission to manage network resources in the host project. This Role is granted to the GKE Service Account of a service project. The Role allows the GKE Service Account of a service project to use the GKE Service Account of its host project. This Role is not granted to users.
  • container.hostServiceAgent.use
  • compute.firewalls.get

Custom Roles

If predefined Roles don't meet your needs, you can create Custom Roles with permissions that you define.

To learn how to create and assign Custom Roles, refer to Creating and Managing Custom Roles.

Permissions granted by Cloud IAM Roles

You can view the permissions granted by each Role using the gcloud command-line tool or GCP Console.


To view the permissions granted by a specific Role, run the following command. [ROLE] is any Cloud IAM Role. GKE Roles are prefixed with roles/container.:

gcloud iam roles describe roles/[ROLE]

For example:

gcloud iam roles describe roles/container.admin


To view the permissions granted by a specific Role, perform the following steps:

  1. Visit the Roles section of GCP Console's IAM menu.

    Visit the IAM menu

  2. From the Filter table field, enter "GKE"

  3. Select the desired Role.

Managing Cloud IAM policies

To learn how to manage Cloud IAM Roles and permissions for users, refer to Granting, Changing, and Revoking Access to Project Members in the Cloud IAM documentation.

For service accounts, refer to Granting Roles to Service Accounts.


Here are a few examples of how Cloud IAM works with GKE:

  • A new employee has joined a company. They need to be added to the GCP project, but they only need to view the project's clusters and other GCP resources. The project owner assigns them the project-level Viewer Role, which contains the compute.projects.get permission required to view projects and their resources.
  • The employee is working in operations, and they need to update a cluster using gcloud or Google Cloud Platform Console. This operation requires the container.clusters.update permission, so the project owner assigns them the Cluster Admin Role. The employee now has Cluster Admin and Viewer Roles.
  • The employee needs to investigate why a Deployment is having issues. They need to run kubectl get pods to see Pods running in the cluster. The employee already has the Viewer Role, which grants this permission.
  • The employee needs to create a new cluster. The project owner grants the employee the Service Account User Role, so that the employee's account can access GKE's default service account.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine