Master Kubernetes RBAC: A Complete Guide to Roles, Bindings, and Permissions

Overview

Official documentation: Authorization and RBAC .

Kubernetes manages a distributed cluster; security is achieved through Authentication, Authorization, and Admission Control. Every request to the API server must pass these checks before interacting with resources.

Authentication Account Types

Two account types exist in Kubernetes:

User accounts – for human users.

Service accounts – for pods.

Groups can be used to aggregate users or service accounts for collective permission assignment.

Authentication Management Methods

HTTP Basic Authentication

Credentials (username:password) are Base64‑encoded and sent in the HTTP Authorization header. The server decodes the header to verify the user.

HTTP Token Authentication

A long, unguessable token represents the client identity. The token is placed in the Authorization header and matched against stored tokens.

HTTPS Authentication (Recommended)

Mutual TLS uses CA‑signed certificates for both client and server, providing the highest security level, though it is the most complex to operate.

Authorization Management Methods

After authentication, Kubernetes evaluates the request against predefined authorization policies.

AlwaysDeny – denies every request (used for testing).

AlwaysAllow – allows every request (default policy).

ABAC – attribute‑based access control.

Webhook – calls an external REST service for authorization decisions.

Node – authorizes kubelet requests.

RBAC – role‑based access control (default with kubeadm).

RBAC Introduction

RBAC (Role‑Based Access Control) describes which objects receive which permissions.

Objects : User, Group, ServiceAccount.

Roles : collections of allowed actions on resources.

Bindings : associate a role with subjects.

Top‑Level RBAC Resources

Role – namespace‑scoped permissions.

ClusterRole – cluster‑wide or cross‑namespace permissions.

RoleBinding – binds a Role to subjects within a namespace.

ClusterRoleBinding – binds a ClusterRole to subjects cluster‑wide.

Role Details

A Role defines permissions inside a specific namespace, following the principle of least privilege.

Define Role Manifest

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: develop-role
rules:
- apiGroups: ["", "apps"]
  resources: ["pods", "deployments"]
  verbs: ["get", "list"]
- apiGroups: ["", "apps"]
  resources: ["configmaps", "secrets", "daemonsets"]
  verbs: ["get", "list"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["delete", "create"]

Rules Explanation

apiGroups : API group identifiers (e.g., "", "apps").

resources : Full resource names (e.g., pods, deployments).

verbs : Allowed actions (e.g., get, list, create, delete).

resourceNames (optional): Specific resource names.

nonResourceURLs (optional): Non‑resource endpoints (ClusterRole only).

Example Rule Variants

apiGroups: [""]

matches core resources like pods. apiGroups: ["apps"] matches resources such as deployments. apiGroups: ["*"] matches all API groups (use with caution).

Role Practical Example

# Define Role
cat role-default.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: custom-role
rules:
- apiGroups: ["", "apps"]
  resources: ["pods", "deployments"]
  verbs: ["get", "list"]
- apiGroups: ["", "apps"]
  resources: ["configmaps", "secrets", "daemonsets"]
  verbs: ["get", "list"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["delete", "create"]

kubectl apply -f role-default.yaml

View the created Role:

kubectl get role -o wide
kubectl describe role custom-role

ClusterRole Details

A ClusterRole defines permissions that apply across the whole cluster, including cluster‑level resources and non‑resource URLs.

Core Concepts

Cluster‑level resources (e.g., Nodes, PersistentVolumes).

All namespaces resources (e.g., Pods in any namespace).

Non‑resource endpoints (e.g., /healthz, /metrics).

ClusterRole Manifest

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: custom-clusterrole
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["*"]
  resourceNames: ["backend"]
- nonResourceURLs: ["/healthz", "/metrics"]
  verbs: ["get"]

ClusterRole Practical Example

# Define ClusterRole
cat ClusterRole-1.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: custom-clusterrole
rules:
- apiGroups: ["", "apps"]
  resources: ["pods", "deployments"]
  verbs: ["get", "list"]
- apiGroups: ["", "apps"]
  resources: ["configmaps", "secrets", "daemonsets"]
  verbs: ["get", "list"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["delete", "create"]

kubectl apply -f ClusterRole-1.yaml

View the created ClusterRole:

kubectl get clusterrole custom-clusterrole -o yaml
kubectl describe clusterrole custom-clusterrole

Default ClusterRoles

admin : read/write access within a namespace.

cluster-admin : super‑user with full cluster permissions.

edit : read/write most objects but cannot manage roles or bindings.

view : read‑only access to most objects, cannot view or modify roles, bindings, or secrets.

RoleBinding Details

RoleBinding assigns a Role (or a compatible ClusterRole) to subjects (users, groups, or service accounts) within a single namespace.

RoleBinding Manifest

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: developer-rolebinding
  namespace: dev-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: developer
subjects:
- kind: User
  name: alice
  apiGroup: ""
- kind: ServiceAccount
  name: my-app-sa
  namespace: dev-namespace
- kind: Group
  name: my-group
  apiGroup: ""

Field Explanation

metadata : name and namespace of the binding.

roleRef : reference to the Role or ClusterRole being bound.

subjects : list of users, groups, or service accounts that receive the permissions.

RoleBinding with ClusterRole

A RoleBinding can bind a ClusterRole when the ClusterRole’s rules are applicable to the target namespace.

# Bind a ClusterRole to a namespace
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: clusterrole-binding
  namespace: dev-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: namespace-pod-reader
subjects:
- kind: User
  name: charlie
  apiGroup: ""

ClusterRoleBinding Details

ClusterRoleBinding assigns a ClusterRole to subjects across the entire cluster, enabling access to cluster‑level resources or all namespaces.

ClusterRoleBinding Manifest

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cluster-admin-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: User
  name: admin-user
  apiGroup: ""
- kind: Group
  name: system:serviceaccounts
  apiGroup: ""

Field Explanation

metadata : unique name of the binding.

roleRef : must reference a ClusterRole.

subjects : users, groups, or service accounts that receive the permissions.

Differences Between Role and ClusterRole

Scope : Role – namespace‑scoped; ClusterRole – cluster‑wide or cross‑namespace.

Definition Location : Role includes a namespace field; ClusterRole does not.

Resource Types : Role can grant permissions on namespaced resources only; ClusterRole can also grant permissions on cluster‑level resources and non‑resource URLs.

Binding : Role is bound via RoleBinding; ClusterRole can be bound via RoleBinding (namespace‑limited) or ClusterRoleBinding (cluster‑wide).

Typical Use Cases : Role – grant developers access within their own namespace; ClusterRole – grant administrators or cross‑namespace capabilities.

Differences Between RoleBinding and ClusterRoleBinding

Scope : RoleBinding – namespace‑scoped; ClusterRoleBinding – cluster‑wide.

Bound Role Type : RoleBinding can bind a Role or a compatible ClusterRole; ClusterRoleBinding binds only a ClusterRole.

Definition Location : RoleBinding is a namespaced resource; ClusterRoleBinding is a cluster‑level resource.

Typical Scenarios : RoleBinding – grant a user or service account permissions inside a specific namespace; ClusterRoleBinding – grant cluster‑admin rights, cross‑namespace access, or access to cluster‑level resources such as Nodes.