RBAC

The Authorization Flow

The API server evaluates authorizers in a fixed priority order (Node, RBAC, Webhook, ABAC, AlwaysAllow). RBAC is evaluated second, after Node authorization (which handles kubelet-to-API-server communication). Each authorizer can ALLOW or DENY. The first decision wins — if Node allows, RBAC never runs.

Key Numbers

RBAC Objects at a Glance

A Real Role + Binding

# Role — namespace-scoped permissions
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: app
  name: pod-reader
rules:
  - apiGroups: [""]
    resources: [pods, pods/log]
    verbs: [get, list, watch]
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list]
  - apiGroups: [acme.io]                  # custom resources
    resources: [databases]
    verbs: [get, list, watch]
  - nonResourceURLs: [/healthz, /metrics]
    verbs: [get]

---
# RoleBinding — bind subjects to a Role within the namespace
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: app
  name: pod-readers
subjects:
  - kind: User                            # human via OIDC
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io
  - kind: Group                           # group claim from OIDC
    name: oncall-engineers
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount                  # workload identity
    name: log-shipper
    namespace: app
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

ClusterRole and ClusterRoleBinding

# ClusterRole — cluster-wide permissions OR a template usable by namespaced bindings
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata: { name: deployment-manager }
rules:
  - apiGroups: [apps]
    resources: [deployments, replicasets]
    verbs: ["*"]                          # everything

---
# Use it cluster-wide
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata: { name: cluster-deployment-managers }
subjects:
  - kind: Group
    name: platform-team
roleRef:
  kind: ClusterRole
  name: deployment-manager
  apiGroup: rbac.authorization.k8s.io

---
# OR scope it to one namespace via RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: app-deployment-managers
  namespace: app
subjects:
  - kind: Group
    name: app-team
roleRef:
  kind: ClusterRole                       # references the ClusterRole
  name: deployment-manager
  apiGroup: rbac.authorization.k8s.io

The same ClusterRole can be referenced by both a ClusterRoleBinding (granting it cluster-wide) and multiple RoleBindings (granting it in specific namespaces). When a RoleBinding references a ClusterRole, only the rules that apply to the binding's namespace are granted — cluster-scoped rules are ignored. This is one of RBAC's most powerful patterns for multi-tenant clusters.

ClusterRole Aggregation

# An aggregation rule — its rules are the union of any matching ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring-edit
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.authorization.k8s.io/aggregate-to-monitoring-edit: "true"
rules: []   # filled in automatically

---
# Operators contribute by labeling their own ClusterRoles
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: prometheus-rules
  labels:
    rbac.authorization.k8s.io/aggregate-to-monitoring-edit: "true"
rules:
  - apiGroups: [monitoring.coreos.com]
    resources: [prometheusrules, servicemonitors]
    verbs: [get, list, watch, create, update, patch, delete]

# The built-in 'admin', 'edit', 'view' ClusterRoles use this same mechanism
# so cert-manager, Argo, etc. can extend them at install time.

API Groups and Resource Matching

Every resource belongs to an API group. The empty string "" represents the core group (v1) — containing primitives like Pod, Service, Secret, ConfigMap, Namespace, Node. Everything else uses named groups like apps, batch, rbac.authorization.k8s.io, or custom groups like monitoring.coreos.com.

# Core group — no apiGroups entry needed (represented as "")
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: { name: core-resources }
rules:
  - apiGroups: [""]
    resources: [pods, services, configmaps, secrets]
    verbs: [get, list, watch]

# Named API groups — specify the group string exactly
  - apiGroups: [apps]
    resources: [deployments, statefulsets, daemonsets]
    verbs: [get, list, watch]
  - apiGroups: [batch]
    resources: [jobs, cronjobs]
    verbs: ["*"]
  - apiGroups: [networking.k8s.io]
    resources: [ingresses, networkpolicies]
    verbs: [get, update, patch]
  - apiGroups: [rbac.authorization.k8s.io]
    resources: [roles, rolebindings, clusterroles, clusterrolebindings]
    verbs: [get, list, watch]

# Non-resource URLs — for /healthz, /metrics, /api, /apis
  - nonResourceURLs: [/healthz, /readyz, /metrics, /api/*, /apis/*]
    verbs: [get]

# Wildcard apiGroup — matches ANY group including core
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: [get, list]  # read across all groups

Verbs: The Permission Matrix

RBAC verbs map closely to HTTP methods. Understanding the semantic differences is critical for writing least-privilege policies.

# Patch implies update for the same resource, but not vice versa
# This role can patch deployments but cannot replace them with full objects
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: deployment-patcher
  namespace: app
rules:
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [patch]  # can patch, cannot update (full replace) or create

---
# deletecollection is the most dangerous verb — test it carefully
# A role with deletecollection on secrets could wipe all secrets in a namespace
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cleanup-script
rules:
  - apiGroups: [""]
    resources: [pods]
    verbs: [deletecollection]

Subjects: Users, Groups, ServiceAccounts

A subject is the entity being granted a role. RBAC knows three kinds — plus the implicit system: identities that Kubernetes creates for itself.

Users

Users are strings — not Kubernetes objects. The API server never verifies a user exists; it trusts the authenticator. An OIDC provider might return [email protected], a certificate might encode O=engineering, CN=alice, and a webhook authenticator might return alice@ldap. All are valid RBAC subjects. This is powerful (works with any IdP) but also means there's no kubectl get users.

Groups

Groups are also strings. A user can belong to many groups simultaneously — the authenticator returns a list of groups, and RBAC evaluates all of them. This is how you grant permissions to teams: instead of binding 50 individual users, you bind one group. system:authenticated and system:unauthenticated are special groups covering all authenticated (or not) requests.

ServiceAccounts

ServiceAccounts are Kubernetes objects. They're namespaced and stored in kube-system by default, though you create them per-application namespace. The subject format for an SA includes the namespace: kind: ServiceAccount, name: my-app, namespace: production. When a Pod authenticates, its bound token's sub claim is system:serviceaccount:production:my-app, and the API server maps that to the ServiceAccount object.

# A binding with all three subject types
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: app-access
  namespace: app
subjects:
  # OIDC user — string from 'sub' or 'email' claim
  - kind: User
    name: [email protected]
    apiGroup: rbac.authorization.k8s.io

  # OIDC group — string from 'groups' claim, potentially with prefix
  - kind: Group
    name: oidc:app-developers
    apiGroup: rbac.authorization.k8s.io

  # Kubernetes ServiceAccount — namespaced, IS an object
  - kind: ServiceAccount
    name: app-backend
    namespace: app

roleRef:
  kind: Role
  name: app-developer
  apiGroup: rbac.authorization.k8s.io

---
# Implicit system groups (granted automatically by API server)
# system:authenticated  — every authenticated request
# system:unauthenticated — anonymous requests
# system:serviceaccounts — all ServiceAccounts in all namespaces
# system:serviceaccounts: — all SAs in a specific namespace
# system:node — kubelets (via Node authorizer, based on CSR node names)

Built-in ClusterRoles

Kubernetes ships four default ClusterRoles at the cluster scope. They form a hierarchy and use aggregation so operators can extend them.

# view — can't read secrets, events, or execute in pods
# These restrictions are hard-coded in the view ClusterRole rules themselves,
# not in the aggregation selectors
$ kubectl get clusterrole view -o yaml | head -60
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: view
  labels:
    kubernetes.io/bootstrapping: rbac-defaults
    rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
  - apiGroups: [""]
    resources: [configmaps, endpoints, persistentvolumeclaims,
                pods, pods/log, replicationcontrollers, services]
    verbs: [get, list, watch]
  # notably ABSENT: secrets, events, pods/exec, pods/attach

---
# Operator extending 'edit' for a custom resource
# cert-manager does this to let developers manage certificates
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cert-manager-edit
  labels:
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
  - apiGroups: [cert-manager.io]
    resources: [certificates, issuers, certificaterequests]
    verbs: [get, list, watch, create, update, patch, delete]

# A developer with 'edit' on namespace 'app' automatically gets cert-manager permissions
# No changes to the developer's RoleBinding needed — aggregation handles it

ServiceAccount Tokens: Bound vs Legacy

ServiceAccount authentication uses JWT tokens. The token format, issuance mechanism, and lifetime have evolved significantly — understanding the difference is critical for cluster security.

# Legacy: an auto-created Secret containing a never-expiring JWT
# Created automatically when a ServiceAccount is created (before 1.24)
# Stored in etcd, never rotated, mounted into every Pod using that SA
$ kubectl get secret -n app
NAME                        TYPE     DATA   AGE
default-token-xxxxx         Opaque   3      2y    # never expires!

# The JWT claims:
# { "iss": "kubernetes/serviceaccount",          # who issued it
#   "namespace": "app",                           # which namespace
#   "name": "default",                            # SA name
#   "uid": "....",                                # SA UID
#   "sub": "system:serviceaccount:app:default" }  # auth identity

# Bound token (1.21+ default): short-lived, Pod-projected, auto-rotated
apiVersion: v1
kind: Pod
spec:
  serviceAccountName: my-sa
  # opt out of legacy auto-mount (1.24+ default)
  automountServiceAccountToken: false
  containers:
    - name: app
      image: my-app
      volumeMounts:
        - name: api-token
          mountPath: /var/run/secrets/tokens
          readOnly: true
  volumes:
    - name: api-token
      projected:
        sources:
          - serviceAccountToken:
              path: api-token           # inside container at this path
              audience: vault.example.com  # audience restriction
              expirationSeconds: 3600  # 1 hour TTL (max 3600 by default)

# kubelet projects the token and auto-rotates it ~80% through TTL
# Inside the container:
$ cat /var/run/secrets/tokens/api-token
eyJhbGciOiJSUzI1NiIs...      # has audience: vault.example.com, not kubernetes.default

# Token is bound to this Pod's UID — if Pod is deleted, token is immediately invalid
# On API side, API server validates 'sub' claim matches requesting pod's UID

Security Comparison

OIDC Integration for kubectl

OIDC (OpenID Connect) is the standard way to authenticate human users to Kubernetes. Instead of sharing static kubeconfig files, each user authenticates to your IdP (Okta, Auth0, Google Workspace, Keycloak) and receives a short-lived token. The cluster validates the token's signature against the IdP's public keys (JWKS).

# kube-apiserver OIDC flags
--oidc-issuer-url=https://accounts.example.com
--oidc-client-id=k8s-cli
--oidc-username-claim=email          # use email as the username
--oidc-username-prefix="oidc:"       # prefix to avoid collision with local users
--oidc-groups-claim=groups           # claim containing group memberships
--oidc-groups-prefix="oidc:"         # prefix all groups (e.g., oidc:admins)
--oidc-ca-file=/etc/ssl/certs/idp.crt  # CA cert to verify IdP signature

# The ID token payload (what the IdP signs):
{
  "iss": "https://accounts.example.com",
  "sub": "[email protected]",
  "email": "[email protected]",
  "groups": ["admins", "developers"],
  "aud": "k8s-cli",
  "exp": 1700000000,
  "iat": 1709999999
}

# kubeconfig — uses a credential plugin (kubelogin) to perform OIDC flow
apiVersion: v1
kind: Config
clusters:
  - name: production
    cluster:
      server: https://k8s.example.com
      certificate-authority-data: BASE64ENCODED_CA
contexts:
  - name: production
    context:
      user: alice
      cluster: production
current-context: production
users:
  - name: alice
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1beta1
        kind: ExecCredential
        command: kubelogin
        args:
          - get-token
          - --oidc-issuer-url=https://accounts.example.com
          - --oidc-client-id=k8s-cli
          - --oidc-extra-scope=email
          - --oidc-extra-scope=groups
        env:
          - name: KUBELOGIN_CLIENT_SECRET
            value: $KUBELOGIN_CLIENT_SECRET
        interactiveMode: Always

# ClusterRoleBinding to grant admins via OIDC group
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: oidc-cluster-admins
subjects:
  - kind: Group
    name: "oidc:admins"          # prefix from --oidc-groups-prefix
roleRef:
  kind: ClusterRole
  name: cluster-admin

kubelogin Flow

kubelogin (or aws-iam-authenticator, gcloud, Azure plugin) bridges kubectl and your IdP. When kubectl needs to authenticate, it calls the plugin, which opens a browser to your IdP, receives the callback with the ID token, and returns it to kubectl. kubectl embeds the token in the Authorization: Bearer <token> header. The API server's RBAC layer then sees the user [email protected] in group oidc:admins — mapped directly to ClusterRoleBindings.

Impersonation — Testing as Another User

Impersonation lets you test what permissions someone else has by temporarily running kubectl as them. The API server treats the impersonated identity exactly like a real authenticated request — RBAC is evaluated against it. This is the primary tool for verifying least-privilege policies.

# Impersonate a ServiceAccount to test its permissions
$ kubectl auth can-i create pods --as=system:serviceaccount:app:log-shipper
no

$ kubectl auth can-i list pods --as=system:serviceaccount:app:log-shipper --namespace=app
yes

# Impersonate a user with a specific group
$ kubectl get secrets [email protected] --as-group=oidc:admins
Error from server (Forbidden): secrets is forbidden ...

# Impersonate with full context
$ kubectl [email protected] \
           --as-group=oidc:developers \
           --as-group=oidc:app-team \
           --namespace=app \
           get pods

# What permissions does the app developer role actually grant?
# Create a test namespace and check
$ kubectl auth can-i --list --namespace=app --as=system:serviceaccount:app:ci-pipeline

# Impersonation requires special RBAC permission to use
# You need 'impersonate' verb on users, groups, or serviceaccounts
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonator
rules:
  - apiGroups: [""]
    resources: [users]
    verbs: [impersonate]
  - apiGroups: [""]
    resources: [groups]
    verbs: [impersonate]
  - apiGroups: [""]
    resources: [serviceaccounts]
    verbs: [impersonate]
  # For serviceaccounts, also need to impersonate the 'extra' sub resource
  - apiGroups: [""]
    resources: [serviceaccounts/token]
    verbs: [impersonate]

# RBAC prevents regular users from impersonating — only admins or CI systems
# with impersonate permission can test other identities

RBAC vs Admission Authorization

Kubernetes has two distinct authorization layers that run at different stages of API request processing. Confusing them is a common source of debugging headaches.

# Admission webhook — runs BEFORE RBAC authorization
# This webhook rejects any Pod that has hostPath volumes
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: no-hostpath-pods
webhooks:
  - name: validate-pods.example.com
    rules:
      - apiGroups: [""]
        apiVersions: [v1]
        operations: [CREATE, UPDATE]
        resources: [pods]
        scope: Namespaced
    clientConfig:
      url: https://webhook-service.namespace.svc/validate
      caBundle: BASE64_CA
    namespaceSelector:
      matchLabels:
        enforce-hostpath-policy: "true"
    admissionReviewVersions: [v1, v1beta1]
    sideEffects: None

# RBAC cannot enforce this — it doesn't inspect pod spec fields
# It only controls whether the 'pods' API endpoint can be called
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-creator
  namespace: production
rules:
  - apiGroups: [""]
    resources: [pods]
    verbs: [create]  # can call POST /api/v1/namespaces/production/pods
    # but still might get rejected by the admission webhook above

The key insight: RBAC says "you can make this API call." Admission says "the object you're submitting passes my policy." They're independent checks — a request can pass RBAC but fail admission, or vice versa. The RBAC authorizer runs during the authorization phase (after authentication, before the object is written to etcd). Validating webhooks run during admission (after object is decoded but before it's persisted). Mutating webhooks can even change the object before RBAC evaluation happens if they run first.

SelfSubjectAccessReview and SelfSubjectRulesReview

These are special API endpoints that let any user ask "what can I do?" They bypass the normal resource-based API — instead they return the effective permissions for the requesting user (or a specified user/SA).

# SelfSubjectAccessReview — can I do this specific action?
# Returns YES/NO for a single permission check
$ kubectl create -f - <<'EOF'
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
metadata:
  name: can-i-delete-pods
spec:
  resourceAttributes:
    namespace: app
    verb: delete
    group: ""
    resource: pods
EOF
# Response:
spec:
  allowed: true    # yes, I can delete pods in 'app'
  reason:         # auto-computed from all RoleBindings/ClusterRoleBindings

---
# SelfSubjectRulesReview — what can I do in this namespace?
# Returns the full list of permissions for a subject in a namespace
$ kubectl create -f - <<'EOF'
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectRulesReview
metadata:
  name: my-permissions
spec:
  namespace: app
spec:
  namespace: app
  resources:
    - pods          # all verbs on pods
    - services      # all verbs on services
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list, watch, update, patch]
  - nonResourceURLs: [/healthz]
    verbs: [get]
  incomplete: false

---
# In practice — the k8s.io/python-client library uses this
# to check permissions before attempting operations
from kubernetes import client
from kubernetes.client import authorization

auth_api = authorization.AuthorizationV1Api()
review = auth_api.create_self_subject_access_review(
    body={
        "spec": {
            "resourceAttributes": {
                "namespace": "app",
                "verb": "get",
                "resource": "pods"
            }
        }
    }
)
if not review.spec.allowed:
    raise PermissionError(f"Cannot list pods in app namespace")

---
# Checking permissions for a ServiceAccount (impersonation required)
$ kubectl auth can-i list pods \
    --as=system:serviceaccount:monitoring:prometheus \
    --namespace=monitoring
yes

# This is what the Kubernetes Dashboard uses to show the "You're not allowed
# to see this" UI — it queries SelfSubjectRulesReview and hides resources
# the user has no access to.

Writing a Least-Privilege Role: Practical Walkthrough

Let's build a real-world role for a web application that reads from a database, emits metrics, and needs to update its own deployment's replica count. We'll grow it from minimal to complete.

Step 1: Identify the workloads and their needs

# Application: backend-api
# Needs:
#   - Read config from ConfigMaps (database credentials)
#   - Write to its own ConfigMaps (leader election status)
#   - Read from its own Secrets (DB password)
#   - Update deployment replica count (HPA writes this)
#   - Emit Prometheus metrics via ServiceMonitor (Prometheus scrapes)
#   - Read pods to find replica IPs for gRPC
#   - Read services for service discovery
#   - Write events to track deployments
#   - No access to other namespaces, other apps' resources, or cluster-wide stuff

Step 2: Write the Role incrementally

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: backend-api
  namespace: backend
rules:
  # ConfigMaps — read (config), write (leader election state)
  - apiGroups: [""]
    resources: [configmaps]
    verbs: [get, list, watch]
    resourceNames: [backend-config, backend-leader]  # restrict to named objects

  # Secrets — read only, and only the specific secret
  - apiGroups: [""]
    resources: [secrets]
    verbs: [get]
    resourceNames: [backend-db-credentials]  # least privilege on secrets

  # Services — read for discovery, write for endpoints updates
  - apiGroups: [""]
    resources: [services]
    verbs: [get, list, watch]

  # Pods — read for replica IP lookup
  - apiGroups: [""]
    resources: [pods]
    verbs: [get, list, watch]

  # Events — write (namespace-scoped, no resourceNames needed)
  - apiGroups: [""]
    resources: [events]
    verbs: [create]

  # Deployments — update only (for HPA and rollout pause/resume)
  # Cannot create or delete deployments — only update specific fields
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list, watch, update, patch]
    resourceNames: [backend-api]  # only our own deployment

  # ServiceMonitor (if using Prometheus Operator) — update metrics address
  - apiGroups: [monitoring.coreos.com]
    resources: [servicemonitors]
    verbs: [get, update, patch]
    resourceNames: [backend-api]

  # Endpoints — write for registering replica IPs
  - apiGroups: [""]
    resources: [endpoints]
    verbs: [get, update, patch]
    resourceNames: [backend-api}

# The SA that runs this pod:
apiVersion: v1
kind: ServiceAccount
metadata:
  name: backend-api
  namespace: backend
---
# RoleBinding to grant the role to the SA
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: backend-api
  namespace: backend
subjects:
  - kind: ServiceAccount
    name: backend-api
    namespace: backend
roleRef:
  kind: Role
  name: backend-api
  apiGroup: rbac.authorization.k8s.io

Step 3: Verify with impersonation

# Test all the expected permissions
$ kubectl auth can-i get configmaps/backend-config \
    --as=system:serviceaccount:backend:backend-api --namespace=backend
yes

$ kubectl auth can-i delete configmaps/backend-config \
    --as=system:serviceaccount:backend:backend-api --namespace=backend
no   # correct — delete not in role

$ kubectl auth can-i get configmaps/other-app-config \
    --as=system:serviceaccount:backend:backend-api --namespace=backend
no   # correct — resourceNames prevents cross-object access

# Full permission report
$ kubectl auth can-i --list \
    --as=system:serviceaccount:backend:backend-api --namespace=backend

RBAC in CI/CD Pipelines

CI/CD systems need to interact with Kubernetes — deploying, rolling out, checking status. The right approach depends on the pipeline's architecture.

Using a dedicated ServiceAccount per pipeline job

# Per-namespace CI SA with scoped permissions
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-runner
  namespace: production
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gitlab-runner-production
rules:
  # Deployments — can roll out, scale, restart
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list, watch, update, patch]
    resourceNames: ["*"]  # can manage any deployment in production
  # Rollouts — for Argo Rollouts or similar
  - apiGroups: [argoproj.io]
    resources: [rollouts]
    verbs: [get, list, watch, update, patch]
  # Jobs — can create deployment jobs
  - apiGroups: [batch]
    resources: [jobs]
    verbs: [create, delete]
  # Pods — for logs and exec (debugging)
  - apiGroups: [""]
    resources: [pods, pods/log]
    verbs: [get, list]
  # Events — read deployment status
  - apiGroups: [""]
    resources: [events]
    verbs: [get, list]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gitlab-runner-production
  namespace: production
subjects:
  - kind: ServiceAccount
    name: gitlab-runner
    namespace: production
roleRef:
  kind: Role
  name: gitlab-runner-production
  apiGroup: rbac.authorization.k8s.io

---
# In the CI job, mount the bound token
apiVersion: v1
kind: Pod
metadata:
  name: gitlab-pipeline-runner
spec:
  serviceAccountName: gitlab-runner
  containers:
    - name: runner
      image: gitlab-runner:latest
      command: ["/bin/sh", "-c"]
      args:
        - kubectl get ns && kubectl rollout status deployment/my-app

GitOps with image pull secrets for private registries

# CI needs to push images — this uses a different auth mechanism (docker config)
# But CI deploying to k8s uses the SA approach above
# For imagePullSecrets on ServiceAccounts (for private registry pull):
apiVersion: v1
kind: ServiceAccount
metadata:
  name: ci-deploy
  namespace: production
imagePullSecrets:
  - name: ghcr-io-secret  # contains docker config.json for GHCR
secrets:
  - name: ghcr-io-secret
---
# The secret must be a kubernetes.io/dockerconfigjson type
apiVersion: v1
kind: Secret
metadata:
  name: ghcr-io-secret
  namespace: production
type: kubernetes.io/dockerconfigjson
data:
  # echo -n '{"ghcr.io":{"auth":"BASE64_USER:TOKEN"}}' | base64
  .dockerconfigjson: BASE64_ENCODED_DOCKER_CONFIG

Node Authorization and kubelet RBAC

Node authorization is a special RBAC mode for kubelets — it restricts the API server to only the permissions that a kubelet legitimately needs. It's not traditional RBAC with Role objects, but it uses the same attribute-matching logic.

# Node authorizer behavior (enabled via --authorization-mode=Node)
# A kubelet authenticates as system:node: group system:nodes
# The Node authorizer ALLOWS these specific operations:

# Read operations — kubelet reads its own node and pod specs
- apiGroups: [""]
  resources: [nodes]
  verbs: [get]           # read own node status
  resourceNames: [node-01.internal]  # only this node's node object

- apiGroups: [""]
  resources: [pods]
  verbs: [get, list]     # list pods scheduled to this node
  #kubelet reads pods to report status back to API server

- apiGroups: [""]
  resources: [pods/status]
  verbs: [get]

# Write operations — kubelet updates its own pod status
- apiGroups: [""]
  resources: [pods/status]
  verbs: [update]

- apiGroups: [""]
  resources: [events]
  verbs: [create, patch]

# Certificate signing requests — kubelet submits CSRs for client certs
- apiGroups: [certificates.k8s.io]
  resources: [certificatesigningrequests]
  verbs: [create, get, list, watch]

- apiGroups: [coordination.k8s.io]
  resources: [leases]
  verbs: [get, create, update]  # leader election via lease objects

# The node restriction admission plugin further limits kubelet to only
# mutate pods it owns (via nodeName field matching)
# Enabled via --admission-control-config-file pointing to:
apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
pluginConfig:
  - name: NodeRestriction
    configuration:
      limitedByExample: "kubelet-"

# What the kubelet CANNOT do (without additional RBAC):
# - Read secrets from other namespaces
# - Access other nodes' status
# - Modify other nodes' leases
# - Create other pods on other nodes
# - Access PersistentVolumes (controller handles this)

Inspect and Audit RBAC

# What can the current user do?
$ kubectl auth can-i create pods --namespace=app
yes

$ kubectl auth can-i delete nodes
no

# What can someone else do?
$ kubectl auth can-i list secrets \
    --as=system:serviceaccount:app:log-shipper \
    --namespace=app
no

# Full permission inventory — very useful for audit
$ kubectl auth can-i --list --namespace=app
[ ]
  resources:   # empty — no permissions!

# Check as a real user with OIDC
$ kubectl auth can-i get deployments \
    [email protected] \
    --as-group=oidc:developers \
    --namespace=production
yes

# All permissions for a ServiceAccount
$ kubectl auth can-i --list \
    --as=system:serviceaccount:monitoring:prometheus \
    --namespace=monitoring

# Who has access to a resource? (audit who can do what)
$ kubectl get clusterrolebinding -o json | \
  jq '.items[] | select(.roleRef.name=="cluster-admin") | .subjects'
[
  { "kind": "Group", "name": "oidc:admins" },
  { "kind": "User", "name": "system:kube-controller-manager" }
]

# Find all bindings granting access to 'secrets' in a namespace
$ kubectl get rolebinding,clusterrolebinding -n production \
  -o json | jq '.items[] | select(
    .roleRef.name == "secret-reader" or
    (.roleRef.kind == "ClusterRole" and
     any(.roleRef.name; . == "admin"))
  ) | .subjects'

# kube-bench checks if RBAC follows CIS benchmarks
$ kube-bench run --targets=policy

# kubectl-whoami — shows current identity and groups
$ kubectl-whoami
User: [email protected]
Groups: [oidc:admins, oidc:developers]

$ kubectl-whoami --as=system:serviceaccount:app:my-sa
User: system:serviceaccount:app:my-sa
Groups: [system:serviceaccounts:app]

Audit Log Patterns for RBAC

# In your audit policy, log all RBAC decisions
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  # Log all requests to RBAC APIs — who is changing permissions?
  - level: RequestResponse
    resources:
      - group: rbac.authorization.k8s.io
        resources: [roles, rolebindings, clusterroles, clusterrolebindings]

  # Log all secret access
  - level: Metadata   # not RequestResponse (too much data for secrets)
    resources:
      - group: ""
        resources: [secrets]
    namespaces: [production, staging]

  # Log admin actions
  - level: RequestResponse
    users: [[email protected]]
    verbs: ["*"]

# Event that shows an RBAC-authorized request (status code 200)
{
  "kind": "Event",
  "apiVersion": "audit.k8s.io/v1alpha1",
  "metadata": { "name": "pod-create-2024-01-15" },
  "level": "RequestResponse",
  "timestamp": "2024-01-15T10:23:45Z",
  "auditID": "abcd-1234",
  "stage": "ResponseComplete",
  "user": {
    "username": "ci-pipeline@prod",
    "uid": "system:serviceaccount:production:ci-deploy",
    "groups": ["system:serviceaccounts:production"]
  },
  "verb": "create",
  "requestURI": "/api/v1/namespaces/production/pods",
  "resource": { "group": "", "version": "v1", "resource": "pods" },
  "responseStatus": { "code": 201 },
  "requestObject": { ... },
  "responseObject": { ... }
}

Escalation Prevention

Kubernetes prevents you from granting permissions you don't already have. This is called escalation prevention and it applies to both Roles and ClusterRoles referenced by Bindings.

# Alice has only 'get' and 'list' on pods
# She tries to create a Role that grants 'create' on pods → API REJECTS IT
$ kubectl create role alice-admin \
    --verb=create \
    --resource=pods
Error from server (Forbidden): ...
# "roles.rbac.authorization.k8s.io is forbidden:
#  cannot create Role with verbs that would result in
#  escalation from 'get,list' to 'create'"

# Same for ClusterRoleBinding — can't grant cluster-admin if you don't have it
# (unless you're cluster-admin, which is exempt from escalation checks)

---
# The escalation check also covers roleRef in bindings:
# If Bob only has 'view' ClusterRole permissions,
# binding Bob to 'admin' ClusterRole via RoleBinding is rejected
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bob-admin
  namespace: app
subjects:
  - kind: User
    name: [email protected]
roleRef:
  kind: ClusterRole
  name: admin   # Bob can't grant admin if he doesn't have admin
apiGroup: rbac.authorization.k8s.io
# Error: user "[email protected]" cannot bind ClusterRole "admin"
# because the ClusterRole has permissions the user doesn't have

# BUT — if Alice has cluster-admin, she can grant admin to anyone
# (she has all permissions, so no escalation is possible)

Common Pitfalls and How to Avoid Them

Debugging RBAC: A Decision Tree

# Step 1: What identity are you running as?
$ kubectl auth whoami
# or: kubectl config view --context=your-context
# Shows username + groups

# Step 2: Can you do the specific thing?
$ kubectl auth can-i <verb> <resource> --namespace=<ns>
yes/no

# Step 3: What can you do at all? (full inventory)
$ kubectl auth can-i --list --namespace=<ns>

# Step 4: Impersonate the failing identity and reproduce
$ kubectl get <resource> --as=<failing-user> --namespace=<ns>

# Step 5: Check bindings in the failing namespace
$ kubectl get rolebinding,clusterrolebinding -n <ns> -o wide

# Step 6: Check if you're hitting the API discovery rule
# (you're authenticated but RBAC denies API group access)
$ kubectl auth can-i get /apis/monitoring.coreos.com/v1
no  # if no permissions on that API group

# Step 7: Check if the SA token is expired or misconfigured
$ kubectl get sa <sa-name> -n <ns> -o yaml
# Check if automountServiceAccountToken: false is set
# Check if projected volume is configured correctly

# Step 8: Check if you're hitting Node authorization boundaries
# (kubelet can't read secrets from other namespaces)
# The error will be: "nodes is forbidden: User system:node:xxx
#  cannot list resource 'secrets' in API group '' in the namespace 'other'"

# Step 9: Check the audit log for the actual denial
# Your audit policy should capture responseStatus.code=403
# which will show user, verb, resource, and namespace of denied request

Tradeoffs

Frequently Asked Questions