How to Bind Role to Service Account in Kubernetes

To bind a Role to a ServiceAccount in Kubernetes, create a RoleBinding resource that references the Role and the ServiceAccount. This grants the ServiceAccount the permissions defined in the Role within a namespace.

Syntax

A RoleBinding connects a Role to a ServiceAccount by specifying the subjects and roleRef. The subjects field lists the ServiceAccount, and roleRef points to the Role to bind.

This binding is namespace-scoped, so both Role and ServiceAccount must be in the same namespace.

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: <binding-name>
  namespace: <namespace>
subjects:
- kind: ServiceAccount
  name: <service-account-name>
  namespace: <namespace>
roleRef:
  kind: Role
  name: <role-name>
  apiGroup: rbac.authorization.k8s.io

Example

This example creates a RoleBinding named read-pods-binding in the default namespace. It binds the Role pod-reader to the ServiceAccount my-service-account, allowing it to read pods.

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: my-service-account
  namespace: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Output

rolebinding.rbac.authorization.k8s.io/read-pods-binding created

Common Pitfalls

• Forgetting to specify the namespace for the ServiceAccount causes binding failure because ServiceAccounts are namespace-scoped.
• Binding a Role from a different namespace than the ServiceAccount will not work; both must be in the same namespace.
• Using ClusterRoleBinding instead of RoleBinding when you want namespace-scoped permissions can cause unintended cluster-wide access.

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: wrong-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: my-service-account
  # Missing namespace here causes error
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

---
# Corrected version
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: correct-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: my-service-account
  namespace: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Quick Reference

Field	Description
apiVersion	API version for RoleBinding, always 'rbac.authorization.k8s.io/v1'
kind	Resource type, must be 'RoleBinding'
metadata.name	Name of the RoleBinding
metadata.namespace	Namespace where RoleBinding, Role, and ServiceAccount exist
subjects.kind	Type of subject, here 'ServiceAccount'
subjects.name	Name of the ServiceAccount to bind
subjects.namespace	Namespace of the ServiceAccount
roleRef.kind	Type of role, usually 'Role' or 'ClusterRole'
roleRef.name	Name of the Role to bind
roleRef.apiGroup	API group, always 'rbac.authorization.k8s.io'

Key Takeaways

Use RoleBinding to grant a Role's permissions to a ServiceAccount within the same namespace.

Always specify the namespace for both the RoleBinding and the ServiceAccount.

RoleBinding is namespace-scoped; use ClusterRoleBinding only for cluster-wide permissions.

Check for missing namespaces in subjects to avoid binding errors.

Role and ServiceAccount must be in the same namespace for RoleBinding to work.