Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

Roles define permissions within a specific namespace. Unlike ClusterRoles, Roles can only grant access to resources within the namespace where they are created.

​
Key Concepts

Role

A namespace-scoped set of permissions defined as rules with verbs, resources, and API groups.

Rules

Permission definitions specifying what actions (verbs) are allowed on which resources.

Namespace

The namespace where the Role exists and can grant permissions.

System Role

Built-in Roles managed by Kubernetes (prefixed with system: or containing kubernetes.io).
Roles are namespace-scoped resources. They can only grant access to resources within the same namespace. For cluster-wide permissions, use ClusterRoles.

​
Required Permissions

ActionPermission
View Rolesiam:project:infrastructure:kubernetes:read
Create Roleiam:project:infrastructure:kubernetes:write
Edit Roleiam:project:infrastructure:kubernetes:write
Delete Roleiam:project:infrastructure:kubernetes:delete

​
Role Types

TypeDescription
SystemBuilt-in Kubernetes roles (should not be modified)
CustomUser-created Roles
System roles (names starting with system: or containing kubernetes.io) are managed by Kubernetes and should not be modified or deleted.

​
How to View Roles

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

Select Namespace

Choose a namespace to view Roles in that namespace.
3

Filter and Search

Use the search box to find Roles by name. Filter by role type (System, Custom).

​
How to View Role Details

1

Find the Role

Locate the Role in the list.
2

Click Role Name

Click on the Role name to open the detail drawer.
3

Review Details

View Role information including:
  • Overview: Name, namespace, type (system/custom), rules count, age
  • Rules: Detailed list of permissions (verbs, resources, API groups)
  • Labels & Annotations: Metadata attached to the Role

​
How to Create a Role

1

Click Create Role

Click the Create Role button in the page header.
2

Write YAML

Enter the Role manifest in YAML format. Key fields:
  • metadata.namespace - Target namespace
  • rules - Array of permission rules
3

Create

Click Create to apply the manifest.

​
How to Edit a Role

1

Open Actions Menu

Click the actions menu (three dots) on the Role row.
2

Click Edit YAML

Select Edit YAML to open the YAML editor.
3

Modify Rules

Edit the Role rules. Add, remove, or modify permissions as needed.
4

Save

Click Update to apply changes.
Modifying system Roles can break namespace functionality. Only edit custom Roles unless you understand the implications.

​
How to Delete a Role

1

Open Actions Menu

Click the actions menu on the Role row.
2

Click Delete

Select Delete from the menu (disabled for system roles).
3

Confirm

Confirm the deletion. Any RoleBindings referencing this role will be affected.
Deleting a Role removes the permissions it grants within the namespace. Any subjects bound to this role via RoleBindings will lose those permissions immediately.

​
Rule Structure

Each rule in a Role specifies:
FieldDescription
apiGroupsAPI groups containing the resources (empty string for core API)
resourcesResource types to grant access to
verbsActions allowed on the resources
resourceNamesOptional: specific resource names to restrict access

​
Common Verbs

VerbDescription
getRead a single resource
listList resources
watchWatch for changes
createCreate new resources
updateUpdate existing resources
patchPartially update resources
deleteDelete resources
deletecollectionDelete multiple resources
*All verbs (full access)

​
Example Roles

​
Pod Reader

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

​
Deployment Manager

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: deployment-manager
  namespace: production
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]

​
ConfigMap and Secret Manager

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: config-manager
  namespace: app-namespace
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

​
Specific Resource Access

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: specific-configmap-reader
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["app-config", "db-config"]
    verbs: ["get"]

​
Full Namespace Admin

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: namespace-admin
  namespace: development
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]

​
Role vs ClusterRole

AspectRoleClusterRole
ScopeSingle namespaceCluster-wide
Can accessNamespace resources onlyAll resources including cluster-scoped
Use caseTeam/app specific permissionsAdmin, operators, cross-namespace access
BindingRoleBinding onlyRoleBinding or ClusterRoleBinding
Use Roles for namespace-isolated workloads. Use ClusterRoles when you need to grant the same permissions across multiple namespaces or access cluster-scoped resources.

​
Troubleshooting

  • Verify a RoleBinding exists binding the user to a Role
  • Check the Role has the necessary rules
  • Verify the Role and RoleBinding are in the same namespace
  • Use kubectl auth can-i --as=<user> -n <namespace> to test permissions
  • System roles cannot be deleted
  • Verify you have delete permission
  • Check for finalizers blocking deletion
  • RBAC changes are immediate, no restart needed
  • Verify the RoleBinding references the correct Role
  • Check if there are multiple Roles/bindings affecting the user
  • Clear any client-side caching
  • Roles only grant permissions in their namespace
  • Delete and recreate the Role in the correct namespace
  • Or use a ClusterRole with RoleBinding for reusability
  • Roles are namespace-scoped
  • Create separate Roles in each namespace, or
  • Use ClusterRole with RoleBinding per namespace, or
  • Use ClusterRole with ClusterRoleBinding for all namespaces

​
FAQ

Role is namespace-scoped and can only grant access to resources within that namespace.ClusterRole is cluster-scoped and can grant access to cluster-scoped resources (nodes, PVs), non-resource endpoints, and resources across all namespaces.
No. Roles can only grant access to namespace-scoped resources within their namespace. For cluster-scoped resources like nodes, PVs, or namespaces themselves, use ClusterRoles.
You have two options:
  1. Create identical Roles in each namespace
  2. Use a ClusterRole and bind it with RoleBindings in each namespace (recommended)
The second approach is easier to maintain.
Yes. A RoleBinding can reference a ClusterRole, but permissions are limited to the RoleBinding’s namespace. This is the recommended way to reuse permission sets across namespaces.
When a namespace is deleted, all Roles and RoleBindings in that namespace are automatically deleted. This is part of Kubernetes garbage collection.
View the Role details to see all rules. Use kubectl describe role <name> -n <namespace> or click on the Role in the UI to see the complete rule list.
No. You cannot escalate privileges. A user can only create Roles with permissions they already have. This prevents privilege escalation attacks.
Use built-in ClusterRoles (admin, edit, view) with RoleBindings for common scenarios. Create custom Roles when you need fine-grained, namespace-specific permissions that don’t match built-in roles.