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).
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 Google Cloud CLI.
- Set up default Google Cloud CLI settings for your project by using one of the following methods:
gcloud init, if you want to be walked through setting project defaults.
gcloud config, to individually set your project ID, zone, and region.
gcloud initand follow the directions:
If you are using SSH on a remote server, use the
--console-onlyflag to prevent the command from launching a browser:
gcloud init --console-only
- Follow the instructions to authorize the gcloud CLI to use your Google Cloud account.
- Create a new configuration or select an existing one.
- Choose a Google Cloud project.
- Choose a default Compute Engine zone.
- Choose a default Compute Engine region.
- Set your default project ID:
gcloud config set project PROJECT_ID
- Set your default Compute Engine region (for example,
gcloud config set compute/region COMPUTE_REGION
- Set your default Compute Engine zone (for example,
gcloud config set compute/zone COMPUTE_ZONE
gcloudto the latest version:
gcloud components update
By setting default locations, you can avoid errors in gcloud CLI like the
One of [--zone, --region] must be supplied: Please specify location.
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
kubectl command to authenticate to Google Cloud
before running any commands that require authorization.
In almost all cases, Kubernetes RBAC can be used instead of IAM.
GKE users require at minimum, the
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.
Define and assign permissions
You can define RBAC rules in
Role objects, and then assign
those rules with
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
- Role: a namespaced grouping of resources and allowed operations that you
can assign to a user or a group of users using a
- ClusterRoleBinding: assign a
ClusterRoleto a user or a group for all namespaces in the cluster.
- RoleBinding: assign a
ClusterRoleto 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
Define 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 (
list) to all pods in the
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"]
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
- Namespaced resources across all Namespaces (for example, all Pods across the entire cluster, regardless of Namespace)
Assign 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
|Google Cloud user account||
||Google Cloud registered email address|
|Kubernetes service account||
||The name of a Kubernetes ServiceAccount object in the cluster|
|IAM service account||
||Automatically generated IAM service account email address|
|Google Group address on a verified domain||
||Email address of a Google Workspace Group that is a member of the
The following RoleBinding grants the
pod-reader Role to a user, a
Kubernetes service account, an IAM service account, and a Google
kind: RoleBinding apiVersion: rbac.authorization.k8s.io/v1 metadata: name: pod-reader-binding namespace: accounting subjects: # Google Cloud user account - kind: User name: firstname.lastname@example.org # Kubernetes service account - kind: ServiceAccount name: johndoe # IAM service account - kind: User name: email@example.com # Google Group - kind: Group name: firstname.lastname@example.org 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
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
error, along with additional information such as the user's implicit and
explicit group membership. If you are using Google Groups for RBAC,
appears in the log message.
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
group, whereas all other requests fall into
system:basic-user ClusterRole lets users make
SelfSubjectAccessReviews to test their permissions in the cluster. The
system:discovery role lets users read discovery APIs, which can reveal
added to the cluster.
Anonymous users (
system:unauthenticated) receive the
system:public-info-viewer ClusterRole instead, which grants read-only access
To see the API endpoints allowed by the
system:discovery ClusterRole, run the
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
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
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
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:
Identify the service account's unique ID:
gcloud iam service-accounts describe SERVICE_ACCOUNT_EMAIL
For example, the following output displays the
displayName: Some Domain IAM service account email: email@example.com etag: BwWWja0YfJA name: projects/project-name/serviceAccountsfirstname.lastname@example.org oauth2ClientId: '123456789012345678901' projectId: project-name uniqueId: '123456789012345678901'
Create a role binding using the
uniqueIdof the service account:
kubectl create clusterrolebinding CLUSTERROLEBINDING_NAME \ --clusterrole cluster-admin \ --user UNIQUE_ID