Skip to main content
RoleBindings grant the permissions defined in a Role or ClusterRole to subjects (users, groups, or service accounts) within a specific namespace. They connect Roles to identities that need those permissions.

​
Key Concepts

RoleBinding

A namespace-scoped binding that grants Role or ClusterRole permissions to subjects within a namespace.

Role Reference

The Role or ClusterRole whose permissions are being granted by this binding.

Subjects

The users, groups, or service accounts receiving the permissions.

System Binding

Built-in bindings managed by Kubernetes (prefixed with system: or kubeadm:).
RoleBindings are namespace-scoped resources. They can reference either a Role (same namespace) or a ClusterRole, but permissions are always limited to the RoleBinding’s namespace.

​
Required Permissions

ActionPermission
View RoleBindingsiam:project:infrastructure:kubernetes:read
Create RoleBindingiam:project:infrastructure:kubernetes:write
Edit RoleBindingiam:project:infrastructure:kubernetes:write
Delete RoleBindingiam:project:infrastructure:kubernetes:delete

​
Binding Types

TypeDescription
SystemBuilt-in Kubernetes bindings (cannot be deleted)
CustomUser-created bindings
System bindings (names starting with system: or kubeadm:) are managed by Kubernetes and should not be modified or deleted.

​
Subject Types

TypeDescription
UserA human user authenticated to the cluster
GroupA collection of users (e.g., system:authenticated)
ServiceAccountA Kubernetes service account for pods

​
How to View RoleBindings

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

Select Namespace

Choose a namespace to view RoleBindings in that namespace.
3

Filter and Search

Use the search box to find bindings by name or role name. Filter by binding type (System, Custom).

​
How to View RoleBinding Details

1

Find the RoleBinding

Locate the RoleBinding in the list.
2

Click Binding Name

Click on the binding name to open the detail drawer.
3

Review Details

View binding information including:
  • Overview: Name, namespace, type (system/custom), age
  • Role Reference: The Role or ClusterRole being bound (kind and name)
  • Subjects: List of users, groups, and service accounts
  • Labels & Annotations: Metadata attached to the binding

​
How to Create a RoleBinding

1

Click Create Binding

Click the Create Binding button in the page header.
2

Write YAML

Enter the RoleBinding manifest in YAML format. Key fields:
  • metadata.namespace - Target namespace
  • roleRef - Reference to the Role or ClusterRole to bind
  • subjects - List of users, groups, or service accounts
3

Create

Click Create to apply the manifest.

​
How to Edit a RoleBinding

1

Open Actions Menu

Click the actions menu (three dots) on the binding row.
2

Click Edit YAML

Select Edit YAML to open the YAML editor.
3

Modify Subjects

Edit the binding. You can add or remove subjects, but the roleRef is immutable.
4

Save

Click Update to apply changes.
The roleRef field is immutable after creation. To change the referenced role, delete and recreate the RoleBinding.

​
How to Delete a RoleBinding

1

Open Actions Menu

Click the actions menu on the binding row.
2

Click Delete

Select Delete from the menu (disabled for system bindings).
3

Confirm

Confirm the deletion. Subjects will immediately lose the permissions granted by this binding within the namespace.
Deleting a RoleBinding immediately revokes permissions from all subjects within that namespace. They will lose access to resources granted by the bound Role or ClusterRole.

​
Example RoleBindings

​
Bind Role to User

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: developer-pods
  namespace: development
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: pod-reader
subjects:
  - kind: User
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io

​
Bind ClusterRole to Namespace

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: admin-binding
  namespace: production
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: admin
subjects:
  - kind: User
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io

​
Grant Permissions to ServiceAccount

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: app-config-reader
  namespace: app-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: configmap-reader
subjects:
  - kind: ServiceAccount
    name: app-service-account
    namespace: app-namespace

​
Multiple Subjects

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: team-binding
  namespace: team-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: edit
subjects:
  - kind: User
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io
  - kind: User
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io
  - kind: Group
    name: dev-team
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: ci-runner
    namespace: ci-cd

​
Subject Reference Format

FieldDescription
kindType of subject: User, Group, or ServiceAccount
nameName of the user, group, or service account
namespaceRequired for ServiceAccounts, empty for Users/Groups
apiGrouprbac.authorization.k8s.io for Users/Groups, empty for ServiceAccounts

​
RoleBinding vs ClusterRoleBinding

AspectRoleBindingClusterRoleBinding
ScopeSingle namespaceCluster-wide
Can referenceRole or ClusterRoleClusterRole only
Permissions apply toResources in binding’s namespaceAll namespaces
Use caseTeam/app specific accessCluster-wide access
Use RoleBindings with ClusterRoles to reuse permission sets across namespaces without granting cluster-wide access. The permissions are limited to the RoleBinding’s namespace.

​
Troubleshooting

  • Verify a RoleBinding exists in the correct namespace
  • Check the subject name matches exactly (case-sensitive)
  • Verify the referenced Role or ClusterRole has the needed permissions
  • Use kubectl auth can-i --as=<user> -n <namespace> to test permissions
  • Check for typos in user/group names
  • Verify the namespace is specified in the subject
  • Check the ServiceAccount exists in that namespace
  • Ensure pods are using the correct ServiceAccount
  • Verify the RoleBinding is in the same namespace as the pod
  • System bindings cannot be deleted
  • Verify you have delete permission
  • Check for finalizers blocking deletion
  • RBAC changes are immediate
  • Clear any client-side caching
  • Verify the binding was actually updated
  • Check if there are conflicting bindings
  • roleRef is immutable after creation
  • Delete the binding and create a new one
  • This is by design to prevent privilege escalation
  • Verify the RoleBinding references the ClusterRole correctly
  • Check the RoleBinding is in the target namespace
  • Ensure the ClusterRole has the necessary rules
  • ClusterRole permissions are limited to the RoleBinding’s namespace

​
FAQ

RoleBinding grants permissions only within a single namespace. It can reference either a Role or ClusterRole.ClusterRoleBinding grants permissions cluster-wide across all namespaces and can only reference ClusterRoles.
Yes. A RoleBinding can reference a ClusterRole, but permissions are limited to the RoleBinding’s namespace. This is useful for reusing common roles across namespaces without granting cluster-wide access.
The roleRef is immutable to prevent privilege escalation. If you could change it, you could escalate permissions without delete access. To change the role, delete and recreate the binding.
You have two options:
  1. Create separate RoleBindings in each namespace referencing the same Role (requires Role in each namespace)
  2. Create a ClusterRole and bind it with RoleBindings in each namespace (recommended)
The second approach is easier to maintain since you only update the ClusterRole.
Yes. You can have multiple RoleBindings referencing the same Role or ClusterRole, each with different subjects. Permissions are additive.
The user immediately loses the permissions granted by that binding in that namespace. If they have other bindings (in this or other namespaces), those permissions remain. RBAC changes take effect instantly.
Yes. You can grant permissions to a ServiceAccount from any namespace. Specify both the name and namespace in the subject. The ServiceAccount will have permissions in the RoleBinding’s namespace.
The RoleBinding is created but grants no permissions. Subjects will not have access to any resources until the referenced Role is created. Kubernetes does not validate that the roleRef exists.