Skip to content

Kubernetes Role and ClusterRole

In the context of Kubernetes RBAC, Role and ClusterRole are resources that define a set of permissions (rules). These permissions determine what operations are allowed on specific Kubernetes resources^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md].

The primary distinction between the two lies in their scope: a Role is namespace-specific, whereas a ClusterRole is a cluster-wide, non-namespaced resource^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md].

Role

A Role defines permissions within a specific namespace. It sets rules that apply only to resources within that namespace boundary^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md].

Rules Structure

A Role contains a list of rules. Each rule requires three specific fields to grant access^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md]:

  • apiGroups: The API group the resource belongs to (e.g., "" for the core group, apps, batch).
  • resources: The type of resource (e.g., pods, deployments, services).
  • verbs: The actions allowed (e.g., get, list, watch, create, delete).

Example

The following example defines a Role named pod-viewer within the default namespace. It grants permission to get, watch, and list pods^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md]:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: pod-viewer
rules:
- apiGroups: [""] # "" indicates the core API group
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

ClusterRole

A ClusterRole is a non-namespaced resource used to define permissions at the cluster level^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md]. Unlike a Role, it does not specify a namespace in its metadata^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md].

While it can grant permissions for cluster-scoped resources (like nodes), it is also frequently used to define permissions for namespaced resources that should apply across all namespaces^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md].

Example

The following example defines a ClusterRole named cluster-pod-viewer. Notice the absence of the namespace field^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md]:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-pod-viewer
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

Applying Permissions

Creating a Role or ClusterRole only declares the permissions; it does not apply them to any user. To grant these permissions to a user, group, or [[Service Account]], you must create a Binding^[400-devops-06-kubernetes-k8s-ithelp-day29-readme.md]:

  • RoleBinding: Grants permissions defined in a Role (or ClusterRole) to a user within a specific namespace.
  • ClusterRoleBinding: Grants permissions defined in a ClusterRole to a user across the entire cluster.

Sources

  • 400-devops-06-kubernetes-k8s-ithelp-day29-readme.md