Roles and ClusterRoles in Kubernetes - Commands & Configuration

Introduction

In Kubernetes, you need to control who can do what inside your cluster. Roles and ClusterRoles help you set these permissions safely. They let you decide which users or apps can access or change resources.

When you want to allow a user to only read pods in a specific namespace without giving full access.

When you need to let a service account create deployments across all namespaces.

When you want to restrict access so a user can only update config maps in one namespace.

When you want to give cluster-wide permissions to monitor nodes and system components.

When you want to separate permissions for different teams working in different namespaces.

Config File - role.yaml

role.yaml

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

This file defines two permission sets:

• Role: Named pod-reader limited to example-namespace. It allows reading pods only in that namespace.
• ClusterRole: Named node-reader with permissions to read nodes across the whole cluster.

Commands

This command creates the Role and ClusterRole in Kubernetes so you can assign them to users or service accounts.

Terminal

kubectl apply -f role.yaml

Expected Output

role.rbac.authorization.k8s.io/pod-reader created

clusterrole.rbac.authorization.k8s.io/node-reader created

This command lists all Roles in the example-namespace to verify the pod-reader Role was created.

Terminal

kubectl get roles -n example-namespace

Expected Output

NAME         AGE

pod-reader   10s

→

-n - Specifies the namespace to look in

This command lists all ClusterRoles in the cluster to verify the node-reader ClusterRole was created.

Terminal

kubectl get clusterroles

Expected Output

NAME          AGE

node-reader   10s

admin         1d

cluster-admin 1d

view          1d

This command shows detailed information about the pod-reader Role, including its permissions.

Terminal

kubectl describe role pod-reader -n example-namespace

Expected Output

Name:         pod-reader

Labels:       <none>

Annotations:  <none>

PolicyRule:

  Resources   Non-Resource URLs   Resource Names   Verbs

  ---------   -----------------   --------------   -----

  pods        []                  []               [get watch list]

→

-n - Specifies the namespace of the Role

Key Concept

Roles define permissions within a namespace, while ClusterRoles define permissions cluster-wide.

Common Mistakes

Trying to use a Role to grant permissions across all namespaces.

Roles only work inside a single namespace and cannot grant cluster-wide access.

Use a ClusterRole when you need permissions across all namespaces.

Not specifying the namespace when creating or viewing a Role.

Roles are namespace-scoped, so missing the namespace causes errors or shows no results.

Always use the -n flag with kubectl commands for Roles.

Assigning ClusterRoles without proper binding to users or service accounts.

Roles and ClusterRoles alone do not grant access until bound with RoleBinding or ClusterRoleBinding.

Create RoleBinding or ClusterRoleBinding to link roles to users or service accounts.

Summary

Create Roles for permissions limited to a namespace and ClusterRoles for cluster-wide permissions.

Use kubectl apply to create these roles from YAML files.

Verify roles with kubectl get and kubectl describe commands specifying namespaces when needed.