Configuring role-based access control

This page provides an overview for the role-based access control (RBAC) system provided by Kubernetes, and how you can use Kubernetes RBAC in Google Kubernetes Engine (GKE).

Overview

Kubernetes includes a built-in role-based access control (RBAC) mechanism that enables you to configure fine-grained and specific sets of permissions that define how a given Google Cloud user, or group of users, can interact with any Kubernetes object in your cluster, or in a specific Namespace of your cluster.

Kubernetes RBAC is enabled by default.

Before you begin

Before you start, make sure you have performed the following tasks:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.

Set up default gcloud settings using one of the following methods:

• Using gcloud init, if you want to be walked through setting defaults.
• Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

1. Run gcloud init and follow the directions:

   gcloud init

   If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

   gcloud init --console-only

2. Follow the instructions to authorize gcloud to use your Google Cloud account.
3. Create a new configuration or select an existing one.
4. Choose a Google Cloud project.
5. Choose a default Compute Engine zone for zonal clusters or a region for regional or Autopilot clusters.

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Using gcloud config

• 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 Autopilot or regional clusters, set your default compute region:

  gcloud config set compute/region COMPUTE_REGION

• Update gcloud to the latest version:

  gcloud components update

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region flags.

Interaction with Identity and Access Management

You can use both Identity and Access Management (IAM) and Kubernetes RBAC to control access to your GKE cluster:

• IAM is not specific to Kubernetes; it provides identity management for multiple Google Cloud products, and operates primarily at the level of the Google Cloud project.

• Kubernetes RBAC is a core component of Kubernetes and lets you create and grant roles (sets of permissions) for any object or type of object within the cluster.

In GKE, IAM and Kubernetes RBAC are integrated to authorize users to perform actions if they have sufficient permissions according to either tool. This is an important part of bootstrapping a GKE cluster, since by default Google Cloud users do not have any Kubernetes RBAC RoleBindings.

To authorize users using Google Cloud accounts, the client must be correctly configured to authenticate using those accounts first. For example, if you are using kubectl, you must configure the kubectl command to authenticate to Google Cloud before running any commands that require authorization.

Note: Many failures that appear to be due to authorization are actually caused because the cluster is unable to authenticate the client. For example, there are special requirements for authenticating from Compute Engine instances, which are described in the documentation on kubectl authentication.

For almost all cases, Kubernetes RBAC can be used instead of IAM. GKE users require at minimum, the container.clusters.get IAM permission in the project that contains the cluster. This permission is included in the container.clusterViewer role, and in other more highly privileged roles. The container.clusters.get permission is required for users to authenticate to the clusters in the project, but does not authorize them to perform any actions inside those clusters. Authorization may then be provided by either IAM or Kubernetes RBAC.

Google Groups for RBAC

Previously, you could only grant roles to Google Cloud user accounts or IAM service accounts. Google Groups for RBAC enables you to grant roles to the members of a group in Google Groups for Business. With this mechanism, the users and groups themselves are maintained by your Google Workspace administrators, completely outside of Kubernetes or Cloud Console, so your cluster administrators do not need detailed information about your users. Another benefit is integration with your existing user account management practices, such as revoking access when someone leaves your organization.

To use this feature, complete the following tasks:

• Meet the requirements.
• Configure your Google Groups.
• Create a cluster with the feature enabled.
• Associate the Google Groups with sets of cluster permissions.

Requirements

To use Google Groups for RBAC, you must have access to Google Workspace or any edition of Cloud Identity.

Google Groups for RBAC is only available on Standard GKE clusters.

Configure Google Groups for RBAC

Configuring your cluster to use this feature, as well as the syntax for referencing a Google Group in Kubernetes RBAC is discussed later in this topic. First, you need to set up your Google Groups following the steps below:

1. Create a Google Group in your domain, named gke-security-groups@YOUR_DOMAIN. The group must be named exactly gke-security-groups. Make sure the gke-security-groups group has the "View Members" permission for "Group Members". See this article for an example of how to set this in the Google Workspace Admin Console.

   You may also refer to the Groups Help Center for more information on managing Groups in Google Workspace.

2. Create groups, if they do not already exist, that represent groups of users or groups who should have different permissions on your clusters. Each group must have the "View Members" permission for "Group Members".

3. Add these groups (not users) to the membership of gke-security-groups@YOUR_DOMAIN.

To check whether a given user has permission to create, modify, or view a resource in the cluster based on group membership, GKE checks both whether the user is a member of a group with access, and whether that group is a direct member of your domain's gke-security-groups group.

Information about Google Group membership is cached for a short time. It may take a few minutes for changes in group memberships to propagate to all of your clusters. In addition to latency from groups changes, standard caching of user credentials on the cluster is about one hour.

Caution: After you create or update a cluster to use a Google Group, deleting the Google Group will cause any roles and role bindings that reference that group to become invalid, leading to access issues for your cluster. You can fix this by disabling and re-enabling the cluster's security group to use a valid Google Group.

Configuring your cluster to use Google Groups for RBAC

After your Google Groups administrator sets up your groups, you can create a new cluster or update an existing cluster to enable the Google Groups for RBAC feature. This can be done by using the gcloud tool or the Google Cloud Console.

Google Groups for RBAC is only available on Standard GKE clusters.

gcloud

Creating a new cluster

To create a new cluster and enable the Google Groups for RBAC feature, run the following gcloud command, substituting the YOUR_DOMAIN value with your own domain name:

gcloud container clusters create CLUSTER_NAME \
  --security-group="gke-security-groups@YOUR_DOMAIN"

Updating an existing cluster

To update an existing cluster to enable the Google Groups for RBAC feature, run the following gcloud command, substituting the YOUR_DOMAIN value with your own domain name:

gcloud container clusters update CLUSTER_NAME \
  --security-group="gke-security-groups@YOUR_DOMAIN"

Console

Creating a new cluster

To create a new cluster and enable the Google Groups for RBAC feature, perform the following steps in Google Cloud Console:

1. Go to the Google Kubernetes Engine page in Cloud Console.

   Go to Google Kubernetes Engine

2. Click Create.

3. Choose the Standard cluster template.

4. From the navigation pane, under Clusters, click Security.

5. Select the Enable Google Groups for RBAC checkbox.

6. Populate Security Group with gke-security-groups@YOUR_DOMAIN.

7. Click Create.

Updating an existing cluster

To update an existing cluster to enable the Google Groups for RBAC feature, perform the following steps in Google Cloud Console:

1. Go to the Google Kubernetes Engine page in Cloud Console.

   Go to Google Kubernetes Engine

2. Beside the cluster you want to edit, click Actions, then click Edit.

3. Under the Details tab, for the Google Groups for RBAC field, click Edit Google Groups for RBAC.

4. Select the Enable Google Groups for RBAC checkbox.

5. Enter your security group name.

6. Click Save changes.

Now you are ready to create RoleBindings and ClusterRoleBindings that reference your Google Groups.

Defining and assigning permissions

You can define RBAC rules in ClusterRole and Role objects, and then assign those rules with ClusterRoleBinding and RoleBinding objects as follows:

• ClusterRole: a cluster-level grouping of resources and allowed operations that you can assign to a user or a group using a RoleBinding or a ClusterRoleBinding.
• Role: a namespaced grouping of resources and allowed operations that you can assign to a user or a group of users using a RoleBinding.
• ClusterRoleBinding: assign a ClusterRole to a user or a group for all namespaces in the cluster.
• RoleBinding: assign a Role or a ClusterRole to a user or a group within a specific namespace.

When you use a RoleBinding to assign a ClusterRole to a user or group, those users and groups can only access resources in the namespace you specify in the RoleBinding. If you want the users or groups to access resource across all namespaces, use a ClusterRoleBinding instead.

Note: RBAC roles are additive. There are no deny rules. When structuring your RBAC roles, think of each role as granting access to resources.

Defining Permissions using Roles or ClusterRoles

You define permissions within a Role or ClusterRole object. A Role defines access to resources within a single Namespace, while a ClusterRole defines access to resources in the entire cluster.

Roles and ClusterRoles have the same syntax. Each has a rules section, where you define the resources the rule applies to and allowed operations for the Role. For example, the following Role grants read access (get, watch, and list) to all pods in the accounting Namespace:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: accounting
  name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

Refer to the Role and ClusterRole API documentation for a full list of allowed fields.

Note: You cannot create a Role that defines permissions unless you already have the permissions defined in the Role. If you have been granted the cluster-admin IAM role, this is sufficient.

Role vs. ClusterRole

Because permissions granted by a ClusterRole apply across the entire cluster, you can use ClusterRoles to control access to different kinds of resources than you can with Roles. These include:

• Cluster-scoped resources such as nodes
• Non-resource REST Endpoints such as /healthz
• Namespaced resources across all Namespaces (for example, all Pods across the entire cluster, regardless of Namespace)

Assigning Roles using RoleBindings or ClusterRoleBindings

After creating a Role or ClusterRole, you assign it to a user or group of users by creating a RoleBinding or ClusterRoleBinding. Users and groups are called subjects, and can be any of the following:

Subject type	Value for kind	Value for name
Google Cloud user account	User	Google Cloud registered email address
Kubernetes service account	ServiceAccount	The name of a Kubernetes ServiceAccount object in the cluster
IAM service account	User	Automatically generated IAM service account email address
Google Group address on a verified domain	Group	Email address of a Google Group that is itself a member of the Google Group gke-security-groups@YOUR_DOMAIN

The following RoleBinding grants the pod-reader Role to a user, a Kubernetes service account, an IAM service account, and a Google Group:

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: pod-reader-binding
  namespace: accounting
subjects:
# Google Cloud user account
- kind: User
  name: [e-mail]
# Kubernetes service account
- kind: ServiceAccount
  name: johndoe
# IAM service account
- kind: User
  name: [e-mail]
# Google Group
- kind: Group
  name: [e-mail]
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

API Usage and Examples

For complete information on using the Kubernetes API to create the necessary Role, ClusterRole, RoleBinding, and ClusterRoleBinding objects for RBAC, see Using Role-Based Access Control Authorization in the Kubernetes documentation.

Troubleshooting and debugging

To debug issues with RBAC, use the Admin activity audit log, which is enabled on all clusters by default. If access to a resource or operation is denied due to lack of sufficient permissions, the API server logs an RBAC DENY error, along with additional information such as the user's implicit and explicit group membership. If you are using Google Groups for RBAC, google groups appears in the log message.

Debugging issues with Google Groups integration

The following instructions enable you to view logs to validate if your clusters have been successfully configured to use Google Groups in RBAC rolebindings.

Prerequisites

Before you begin examining the logs, make sure:

• You have not interacted with the cluster you want to test (for example, ran any kubectl commands) for at least one hour. Authentication is cached for one hour and you need to make sure the request gets logged when it happens.
• You are a member of at least one of the groups included in gke-security-groups. This ensures some Google Groups information is populated in the logs.

Configuring logs

To use logs for debugging Google Groups with RBAC:

1. Enable data access logging for your Google Cloud project. To enable the logging:

   1. Go to the Audit Logs page in Cloud Console.

      Go to Audit Logs

   2. In the table, select Kubernetes Engine API.

   3. In the Log Type menu, select:

      • Admin Read
      • Data Read
      • Data Write

   4. Click Save.

   For more information about enabling Audit Logging, see Configuring Data Access logs with the Cloud Console in the Cloud management tools documentation.

   Important: Enabling Audit Logging incurs charges. If you only enabled Audit Logging for testing purposes, you should disable it after you've completed testing to avoid charges.

2. Run a command using kubectl in the cluster. This can be as simple as kubectl create ns helloworld.

3. Enter a custom query in the Logs Viewer page. To run the query:

   1. Go to the Logs Viewer page in Cloud Console.

      Go to Logs Viewer

   2. Click the arrow in the Query preview box at the top of the page.

   3. In the dropdown box that appears, copy and paste the following query:

      resource.type="k8s_cluster"
      resource.labels.location="CLUSTER_LOCATION"
      resource.labels.cluster_name="CLUSTER_NAME"
      protoPayload.resourceName="authorization.k8s.io/v1beta1/subjectaccessreviews"
      protoPayload.response.spec.user="EMAIL_ADDRESS"
      

      Replace the following:

      • CLUSTER_LOCATION: your cluster's region or zone.
      • CLUSTER_NAME: the name of your cluster.
      • EMAIL_ADDRESS: the registered email address of your Google account.

   4. Select Run Query. You should see at least one result. If you do not, try increasing the time range.

   5. Select the cluster you want to examine.

   6. Click Expand nested fields.

   7. The field protoPayload.request.spec.group contains the groups where:

      • The groups are members of gke-security-group.
      • You are a member of the group.

      This list should match the set of groups you are a member of. If no groups are present, there might be an issue with how the groups are set up.

4. Restore data access logging to previous settings to avoid further charges (if desired).

Limitations

The following sections describe interactions that might not seem obvious when working with Kubernetes RBAC.

Default discovery roles

Clusters are created with a set of default ClusterRoles and ClusterRoleBindings. Requests made with valid credentials are placed in the system:authenticated group, whereas all other requests fall into system:unauthenticated. Prior to Kubernetes version 1.14, both system:authenticated and system:unauthenticated grant the system:basic-user and system:discovery ClusterRoles by default.

The system:basic-user ClusterRole lets users to make SelfSubjectAccessReviews to test their permissions in the cluster. The system:discovery role lets users to read discovery APIs, which can reveal information about CustomResourceDefinitions added to the cluster.

As of Kubernetes 1.14, anonymous users (system:unauthenticated) will receive the system:public-info-viewer ClusterRole instead, which grants read-only access to /healthz and /version APIs.

To see the API endpoints allowed by the system:discovery ClusterRole, run the following command:

kubectl get clusterroles system:discovery -o yaml

Forbidden error for service accounts on Google Cloud VM instances

The following error can occur when the VM instance does not have the userinfo-email scope:

Error from server (Forbidden): error when creating ... "role-name" is forbidden: attempt to grant extra privileges:...

For example, suppose the VM has cloud-platform scope but does not have userinfo-email scope. When the VM gets an access token, Google Cloud associates that token with the cloud-platform scope. When the Kubernetes API server asks Google Cloud for the identity associated with the access token, it receives the service account's unique ID, not the service account's email.

To authenticate successfully, either create a new VM with the userinfo-email scope or create a new role binding that uses the unique ID.

To create a new VM instance with the userinfo-email scope, run the following command:

gcloud compute instances create INSTANCE_NAME \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --scopes userinfo-email

To create a new role binding that uses the service account's unique ID for an existing VM, perform the following steps:

1. Identify the service account's unique ID:

   gcloud iam service-accounts describe SERVICE_ACCOUNT_EMAIL
   

   For example, the following output displays the uniqueId for the [e-mail] service account:

   displayName: Some Domain IAM service account
   email: [e-mail]
   etag: BwWWja0YfJA
   name: projects/project-name/serviceAccounts/[e-mail]
   oauth2ClientId: '123456789012345678901'
   projectId: project-name
   uniqueId: '123456789012345678901'
   

2. Create a role binding using the uniqueId of the service account:

   kubectl create clusterrolebinding CLUSTERROLEBINDING_NAME \
     --clusterrole cluster-admin \
     --user UNIQUE_ID
   

What's next

• Learn how to create IAM policies.