This page explains how to create Identity and Access Management (IAM) allow policies for authorization in Google Kubernetes Engine (GKE).
Overview
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.
Before you begin
Before you start, make sure 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
gcloud components update
.
Interaction 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.
IAM roles
The following sections describe the IAM roles available in Google Cloud.
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.
Role | Title | Description | Lowest resource |
---|---|---|---|
roles/ |
Kubernetes Engine Admin |
Provides access to full management of clusters and their Kubernetes API objects.
To set a service account on nodes, you must also have the Service Account User role
( |
|
roles/ |
Kubernetes Engine KMS Crypto Key User | Allow the Kubernetes Engine service agent in the cluster project to call KMS with user provided crypto keys to sign payloads. | |
roles/ |
Kubernetes Engine Cluster Admin |
Provides access to management of clusters.
To set a service account on nodes, you must also have the Service Account User role
( |
|
roles/ |
Kubernetes Engine Cluster Viewer |
Provides access to get and list GKE clusters. |
|
roles/ |
Kubernetes Engine Default Node Service Account | Least privilege role to use as the default service account for GKE Nodes. | |
roles/ |
Kubernetes Engine Developer |
Provides access to Kubernetes API objects inside clusters. |
|
roles/ |
Kubernetes Engine Host Service Agent User |
Allows the Kubernetes Engine service account in the host project to configure shared network resources for cluster management. Also gives access to inspect the firewall rules in the host project. |
|
roles/ |
Kubernetes Engine Viewer |
Provides read-only access to resources within GKE clusters, such as nodes, pods, and GKE API objects. |
|
For a full list of the individual permissions in each role, refer to Google Kubernetes Engine roles. 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.
Service Account User role
Service Account User grants a Google Cloud user account the permission to perform actions as though a service account were performing them.
Granting the
iam.serviceAccountUser
role to a user for a project gives the user all of the roles granted to all service accounts in the project, including service accounts that may be created in the future.Granting the
iam.serviceAccountUser
role to a user for a specific service account gives a user all of the roles granted to that service account.
This role includes the following permissions:
iam.serviceAccounts.actAs
iam.serviceAccounts.get
iam.serviceAccounts.list
resourcemanager.projects.get
resourcemanager.projects.list
For more information about the ServiceAccountUser role, see ServiceAccountUser in the IAM documentation.
The following command shows the syntax for granting the Service Account User role:
gcloud iam service-accounts add-iam-policy-binding \
SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member=user:USER \
--role=roles/iam.serviceAccountUser
Replace the following:
SA_NAME
: the name of the service account.PROJECT_ID
: the ID of your Google Cloud project.USER
: the email address for the user.
Host Service Agent User role
The Host Service Agent User role is only used in Shared VPC clusters. This role includes the following permissions:
compute.firewalls.get
container.hostServiceAgent.*
dns.networks.bindDNSResponsePolicy
dns.networks.bindPrivateDNSPolicy
dns.networks.bindPrivateDNSZone
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.
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.
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.
Managing 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
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 thecontainer.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
employee the Service Account User role for the
PROJECT_NUMBER-compute@developer.gserviceaccount.com
service account, so that the employee's account can access Compute Engine's default service account. This service account has the Editor role, which provides a broad set of permission.
What's next
- Read the access control overview
- Learn about managing access to Google Cloud resources
- Learn more about allow policies
- Learn about deny policies