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.

Overview

Kubernetes includes a built-in role-based access control (RBAC) mechanism that allows 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

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

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

Interaction with Identity and Access Management

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

• Cloud 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 allows you to create and grant roles (sets of permissions) for any object or type of object within the cluster.

In GKE, Cloud 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.

In order 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.

Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older

In GKE clusters using GKE v1.11.x and older, there is a limitation that Cloud IAM cannot grant the ability to create a Kubernetes RBAC Role or ClusterRole. However, the Kubernetes Engine Admin Cloud IAM role does grant users with the ability to create a Kubernetes RBAC RoleBinding or ClusterRoleBinding for any user, including themselves, which can be used to bind Google Cloud users to predefined RBAC Roles.

In particular, the cluster-admin predefined RBAC role grants users full permissions in the cluster. Therefore, to bootstrap a user to allow them to create RBAC Roles and ClusterRoles, issue the following command, replacing [USER_ACCOUNT] with the target user's Google Cloud login email address.

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

Note: The [USER_ACCOUNT] is case sensitive. To avoid errors, enter the target user's email address in lowercase.

Google Groups for GKE

Beta

This product or feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

Previously, you could only grant roles to Google Cloud user accounts or Cloud IAM service accounts. Google Groups for GKE (Beta) allows you to grant roles to the members of a G Suite Google Group. With this mechanism, the users and groups themselves are maintained by your G Suite 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, you configure your G Suite Google Groups, create a cluster with the feature enabled, then associate those Google Groups with sets of cluster permissions.

Configure Google Groups for use with RBAC

Configuring your cluster to use this feature, as well as the syntax for referencing a G Suite 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 G Suite Google Group in your domain, named gke-security-groups@[yourdomain.com]. The group must be named exactly gke-security-groups.
2. Create groups, if they do not already exist, that represent groups of users or groups who should have different permissions on your clusters.
3. Add these groups (not users) to the membership of gke-security-groups@[yourdomain.com].

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 member of your domain's gke-security-groups group.

Information about G Suite 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.

Configuring your cluster to use Google Groups for GKE

Note: You must create a new cluster to enable this feature.

After your G Suite Google Groups administrator sets up your groups, create a new cluster using the gcloud command, and add the following option, substituting your own domain name: --security-group="gke-security-groups@[yourdomain.com]". The following is an example cluster-creation command:

gcloud beta container clusters create my-cluster \
  --security-group="gke-security-groups@[yourdomain.com]"

Now you are ready to create Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings that reference your G Suite Google Groups.

Defining and assigning permissions

You define your RBAC permissions by creating the following kinds of Kubernetes objects:

• ClusterRole or Role: defines a set of resource types and operations that can be assigned to a user or group of users in a cluster (ClusterRole), or a Namespace (Role), but does not specify the user or group of users.
• ClusterRoleBinding or RoleBinding: assigns a ClusterRole or Role to a user or group of users. A ClusterRoleBinding works with a ClusterRole, and a RoleBinding works with either a ClusterRole or a Role.

RBAC roles are purely additive--there are no "deny" rules. When structuring your RBAC roles, you should think in terms of "granting" users access to cluster 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 relevant Namespace, resource type, and allowable operations for the Role. For example, the following Role grants read access (get, watch, and list) for all Pods in the accounting Namespace:

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

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 Cloud 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 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
Cloud IAM service account	User	Automatically generated Cloud IAM service account email address
G Suite Google Group address (Beta) on a verified domain	Group	Email address of a Google Group that is itself a member of the Google Group gke-security-groups@[yourdomain.com]

The following RoleBinding grants the pod-reader Role to a user, a Kubernetes service account, a Cloud 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
# Cloud IAM service account
- kind: User
  name: [e-mail]
# G Suite 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.

Caveats

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

Default discovery roles

Note: GKE version 1.14 is not yet available. This information is provided so that you can plan for a change in behavior.

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 allows users to make SelfSubjectAccessReviews to test their permissions in the cluster. The system:discovery role allows 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:basic-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

This error can occur when the VM instance does not have the userinfo-email scope. 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 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]
   

2. Create a role binding using the unique ID:

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

What's next

• Learn how to create Cloud Identity and Access Management policies.