Role-based access control

This page provides an overview for role-based access control in Google Kubernetes Engine.


Kubernetes role-based access control (RBAC) system lets you exercise fine-grained control over how users access the API resources running on your cluster. You can use RBAC to dynamically configure permissions for your cluster's users and define the kinds of resources with which they can interact.

You can create RBAC permissions that apply to your entire cluster, or to specific namespaces within your cluster. Cluster-wide permissions are useful for limiting certain users' access to specific API resources (such as security policies or Secrets). Namespace-specific permissions are useful if, for example, you have multiple groups of users operating within their own respective namespaces. RBAC can help you ensure that users only have access to cluster resources within their own namespace.

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

Interaction with Identity and Access Management

GKE also uses Cloud Identity and Access Management (IAM) to control access to your cluster. However, Cloud IAM works on a per-project basis—that is, users require project-level permissions to access any cluster in a given GCP project.

RBAC permissions provide finer-grained control over access to resources within each cluster. As such, Cloud IAM and RBAC can work in concert, and a user must have sufficient permissions at either level to work with resources in your cluster.

Prerequisites for using Role-Based Access Control

You must grant your user the ability to create roles in Kubernetes by running the following command. [USER_ACCOUNT] is the user's email address:

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

Setting up Role-Based Access Control

You define your RBAC permissions by creating objects from the API group in your cluster. You can create the objects using the kubectl command-line interface, or programmatically.

You'll need to create two kinds of objects:

  1. A Role or ClusterRole object that defines what resource types and operations are allowed for a set of users.
  2. A RoleBinding or ClusterRoleBinding that associates the Role (or ClusterRole) with one or more specific users.

RBAC permissions are purely additive--there are no "deny" rules. When structuring your RBAC permissions, you should think in terms of "granting" users access to cluster resources.

Defining Permissions in a Role

You define permissions within a Kubernetes Role or ClusterRole API object. A Role grants access to resources within a single namespace, while a ClusterRole grants access to resources in the entire cluster.

Within your Role (or ClusterRole) object, you define the permissions as a set of rules. The rules determine the namespace, resource type, and allowable operations for that role. For example, you can create a Role that grants read access (operations such as get, watch, and list) for all Pod resources in a given namespace.

Role vs. ClusterRole

Because ClusterRole permissions apply across the entire cluster, you can use them to control access to different kinds of resources than you can with a Role. 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 Permissions to Users with RoleBinding

Once you've created the Role (or ClusterRole), you must create a RoleBinding (or ClusterRoleBinding) object to grant the permissions in the Role (or ClusterRole) to a set of users. The users can be individual users, or Kubernetes service accounts.

The RoleBinding (or ClusterRoleBinding) contains a list of the users, and a reference to the Role (or ClusterRole) being granted to those users.

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.


The following sections describe caveats related to Kubernetes' RBAC support.

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 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 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

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine Documentation