Create IAM allow policies

Autopilot Standard

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

Every Google Cloud, GKE, and Kubernetes API call requires that the account making the request has the necessary permissions. By default, no one except you can access your project or its resources. You can use IAM to manage who can access your project and what they are allowed to do. IAM permissions work alongside Kubernetes RBAC, which provides granular access controls for specific objects inside a cluster or namespace. IAM has a stronger focus on permissions at the project and organization level, though it does provide several predefined roles specific to GKE.

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

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

This page is for Security specialists and Operators who use IAM allow policies to manage authorization in GKE clusters. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE user roles and tasks.

Before reading this page, ensure that you're familiar with the following concepts:

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.
Note: For existing gcloud CLI installations, make sure to set the compute/region property. If you use primarily zonal clusters, set the compute/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.

Use IAM with Kubernetes RBAC

Kubernetes has a built-in access control mechanism, role-based access control (RBAC). RBAC controls access on a cluster and namespace level, while IAM works on the project level.

IAM and RBAC can work together. An entity must have sufficient RBAC and IAM permissions to work with resources in your cluster.

Understand IAM roles

The following sections describe the types of IAM roles that you can use to control access to your Google Cloud resources. For more information about each of these types of roles and when to use them, see Choose which type of role to use.

Predefined GKE roles

IAM provides predefined roles that grant access to specific Google Cloud resources and prevent unauthorized access to other resources.

IAM offers the following predefined roles for GKE.

For more information about the individual permissions in each predefined role, see Google Kubernetes Engine roles and permissions. You can also view the permissions in each IAM role using the gcloud CLI or the Google Cloud console. For instructions, refer to View permissions granted by IAM roles.

Basic IAM roles

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

To learn more about basic roles, refer to Basic roles in the IAM documentation.

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.

Choose roles and permissions for your principals

The principals in your Google Cloud environment, such as users and workloads, might need access to various Google Cloud resources to perform specific tasks. For example, consider a Kubernetes workload that uses Workload Identity Federation for GKE to store data in a Cloud Storage bucket. To give the workload the permissions that it needs, you grant a role that contains those permissions to the principal identifier for that workload.

The permissions that a principal needs depends on the following factors:

The resources that the principal needs to access, such as Cloud Storage buckets.
The task that the principal needs to perform, such as writing to a bucket or reading metadata.

You can give permissions to a principal by using a predefined role that contains those permissions, or by creating a custom role. Unless you require a custom role, we recommend that you use a predefined role. For more information about identifying the permissions that your principals need and giving those permissions to the principals, see Find the right predefined role.

View permissions granted by IAM roles

You can view the permissions granted by each role using the gcloud CLI or the Google Cloud console.

gcloud

To view the permissions granted by a specific role, run the following command:

gcloud iam roles describe roles/ROLE

Replace ROLE with any IAM role. GKE roles are prefixed with roles/container, such as gcloud iam roles describe roles/container.admin.

Console

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

Go to the Roles section of the IAM & Admin page on the Google Cloud console.

Go to IAM & Admin
To see the roles for GKE, in the Filter table field, enter Kubernetes Engine.
Select the role you want to view. The description of the role and a list of assigned permissions displays.

Manage IAM roles

To learn how to manage IAM roles and permissions for human users, refer to Granting, changing, and revoking access to project members in the IAM documentation.

For service accounts, refer to Granting roles to service accounts.

Examples of IAM use cases

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

A new employee has joined a company. They need to be added to the Google Cloud project, but they only need to view the project's clusters and other Google Cloud resources. The project owner assigns them the project-level Compute Viewer role. This role provides read-only access to get and list nodes, which are Compute Engine resources.
The employee is working in operations, and they need to update a cluster using gcloud or the Google Cloud console. This operation requires the container.clusters.update permission, so the project owner assigns them the Kubernetes Engine Cluster Admin role. The employee now has the permissions granted by both the Kubernetes Engine Cluster Admin and Compute 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 Compute Viewer role, which is not sufficient for listing Pods. The employee needs the Kubernetes Engine Viewer role.
The employee needs to create a new cluster. The project owner grants the the Service Account User role on the PROJECT_NUMBER[email protected] service account to the employee so that the employee's account can access Compute Engine's default service account. GKE attaches this service account to nodes by default so that system workloads can send data like logs and metrics to Google Cloud.