Roles

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

Action	Permission
View Roles	`iam:project:infrastructure:kubernetes:read`
Create Role	`iam:project:infrastructure:kubernetes:write`
Edit Role	`iam:project:infrastructure:kubernetes:write`
Delete Role	`iam:project:infrastructure:kubernetes:delete`

Role Types

Type	Description
System	Built-in Kubernetes roles (should not be modified)
Custom	User-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

Select Cluster

Choose a cluster from the cluster dropdown.

Select Namespace

Choose a namespace to view Roles in that namespace.

Filter and Search

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

How to View Role Details

Find the Role

Locate the Role in the list.

Click Role Name

Click on the Role name to open the detail drawer.

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

Click Create Role

Click the Create Role button in the page header.

Write YAML

Enter the Role manifest in YAML format. Key fields:

metadata.namespace - Target namespace
rules - Array of permission rules

Create

Click Create to apply the manifest.

How to Edit a Role

Open Actions Menu

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

Click Edit YAML

Select Edit YAML to open the YAML editor.

Modify Rules

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

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

Open Actions Menu

Click the actions menu on the Role row.

Click Delete

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

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:

Field	Description
apiGroups	API groups containing the resources (empty string for core API)
resources	Resource types to grant access to
verbs	Actions allowed on the resources
resourceNames	Optional: specific resource names to restrict access

Common Verbs

Verb	Description
`get`	Read a single resource
`list`	List resources
`watch`	Watch for changes
`create`	Create new resources
`update`	Update existing resources
`patch`	Partially update resources
`delete`	Delete resources
`deletecollection`	Delete 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

Aspect	Role	ClusterRole
Scope	Single namespace	Cluster-wide
Can access	Namespace resources only	All resources including cluster-scoped
Use case	Team/app specific permissions	Admin, operators, cross-namespace access
Binding	RoleBinding only	RoleBinding 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

User cannot access namespace resources

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

Cannot delete Role

System roles cannot be deleted
Verify you have delete permission
Check for finalizers blocking deletion

Permission changes not taking effect

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

Role in wrong namespace

Roles only grant permissions in their namespace
Delete and recreate the Role in the correct namespace
Or use a ClusterRole with RoleBinding for reusability

Cannot access resources in other namespaces

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

What is the difference between Role and ClusterRole?

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.

Can a Role grant access to cluster-scoped resources?

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.

How do I reuse a Role across namespaces?

You have two options:

Create identical Roles in each namespace
Use a ClusterRole and bind it with RoleBindings in each namespace (recommended)

The second approach is easier to maintain.

Can I bind a ClusterRole with a RoleBinding?

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.

What happens if I delete a namespace with Roles?

When a namespace is deleted, all Roles and RoleBindings in that namespace are automatically deleted. This is part of Kubernetes garbage collection.

How do I check what permissions a Role grants?

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.

Can a Role grant permissions to resources it doesn't have?

No. You cannot escalate privileges. A user can only create Roles with permissions they already have. This prevents privilege escalation attacks.

Should I create Roles or use built-in ClusterRoles?

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.

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Key Concepts

Role

Rules

Namespace

System Role

Required Permissions

Role Types

How to View Roles

How to View Role Details

How to Create a Role

How to Edit a Role

How to Delete a Role

Rule Structure

Common Verbs

Example Roles

Pod Reader

Deployment Manager

ConfigMap and Secret Manager

Specific Resource Access

Full Namespace Admin

Role vs ClusterRole

Troubleshooting

FAQ

​Key Concepts

Role

Rules

Namespace

System Role

​Required Permissions

​Role Types

​How to View Roles

​How to View Role Details

​How to Create a Role

​How to Edit a Role

​How to Delete a Role

​Rule Structure

​Common Verbs

​Example Roles

​Pod Reader

​Deployment Manager

​ConfigMap and Secret Manager

​Specific Resource Access

​Full Namespace Admin

​Role vs ClusterRole

​Troubleshooting

​FAQ

Key Concepts

Required Permissions

Role Types

How to View Roles

How to View Role Details

How to Create a Role

How to Edit a Role

How to Delete a Role

Rule Structure

Common Verbs

Example Roles

Pod Reader

Deployment Manager

ConfigMap and Secret Manager

Specific Resource Access

Full Namespace Admin

Role vs ClusterRole

Troubleshooting

FAQ