Roles and ClusterRoles

Kubernetes uses Role-Based Access Control (RBAC) to regulate who can do what in your cluster. Roles and ClusterRoles define sets of permissions, but they differ in scope.

Role vs ClusterRole

A Role grants permissions within a single namespace. A ClusterRole grants permissions cluster-wide or across all namespaces.

Defining a Role

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: development
  name: pod-reader
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]

Each rule specifies three things:

apiGroups -- the API group for the resource ("" means the core API group)
resources -- which resource types the rule applies to
verbs -- which actions are allowed (get, list, watch, create, update, patch, delete)

Defining a ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-viewer
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list"]

ClusterRoles have no namespace field because they apply cluster-wide.

Managing Roles with kubectl

# List roles in a namespace
kubectl get roles -n development

# List all cluster roles
kubectl get clusterroles

# Describe a role to see its rules
kubectl describe role pod-reader -n development

# Create a role imperatively
kubectl create role pod-manager \
  --verb=get,list,create,delete \
  --resource=pods \
  -n development

Key Takeaways