Create Custom RBAC Roles for Fine-Grained Access Control - Container Compute Service

Kubernetes role-based access control (RBAC) defines fine-grained permissions on cluster resources. In Alibaba Cloud Container Compute Service (ACS), create a Role (namespace-scoped) or a ClusterRole (cluster-wide) to control what actions specific users or service accounts can perform.

This article covers:

How to decide whether a built-in ClusterRole already meets your needs
How to create a namespace-scoped Role using YAML or kubectl
How to create a cluster-wide ClusterRole using YAML, kubectl, or the ACS console

When to use Role vs. ClusterRole

Attribute	Role	ClusterRole
Scope	Single namespace	Entire cluster
Use when	Granting access to resources in one namespace, such as Pods in `default`	Granting access to cluster-scoped resources (nodes, PersistentVolumes), resources across all namespaces, or namespaced resources scoped to a single namespace via a RoleBinding
Activated by	RoleBinding	ClusterRoleBinding, or a RoleBinding to scope it to one namespace

A ClusterRole has three distinct use cases:

Cluster-scoped resources -- Grant access to resources that exist outside any namespace, such as nodes or PersistentVolumes.
All namespaces -- Grant the same permissions across every namespace in the cluster.
Single namespace via RoleBinding -- Define a reusable set of permissions as a ClusterRole, then bind it to a specific namespace with a RoleBinding. This avoids duplicating identical Role definitions in multiple namespaces.

Important

A Role or ClusterRole has no effect on its own. You must create a RoleBinding or ClusterRoleBinding to attach the role to a RAM user, RAM role, or Kubernetes service account. For instructions, see Grant RBAC permissions to RAM users or RAM roles.

Prerequisites

Before you begin, ensure that you have:

An ACS cluster
kubectl configured to connect to your cluster
Permissions to create Role and ClusterRole resources (typically cluster-admin or an equivalent custom role)

Built-in ClusterRoles

Before creating a custom role, check whether a built-in ClusterRole meets your needs. Kubernetes provides four default user-facing ClusterRoles:

ClusterRole	Scope	Permissions	Key exclusions
`cluster-admin`	Cluster-wide	Full access to all resources	None
`admin`	Namespace (via RoleBinding)	Read/write access to most resources, including Roles and RoleBindings	No write access to resource quotas or the namespace itself
`edit`	Namespace (via RoleBinding)	Read/write access to most resources	Cannot view or modify Roles or RoleBindings
`view`	Namespace (via RoleBinding)	Read-only access to most resources	Cannot view Secrets

If a built-in role covers your access requirements, skip the creation steps below and go directly to Grant RBAC permissions to RAM users or RAM roles to bind it.

Create a Role

A Role defines permissions scoped to a single namespace.

Option 1: Declarative YAML

The following YAML creates a Role named test-role in the default namespace. This role grants full permissions on Pods.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: test-role
  namespace: default
rules:
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - create
  - delete
  - deletecollection
  - get
  - list
  - patch
  - update
  - watch

To grant permissions on multiple resource types, add additional entries under rules. For example, to also grant read access to Deployments and batch Jobs:

rules:
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - "apps"
  resources:
  - deployments
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - "batch"
  resources:
  - jobs
  verbs:
  - get
  - list
  - watch

Apply the YAML to your cluster:

kubectl apply -f role.yaml

Verify that the Role was created:

kubectl get role test-role -n default

Option 2: Imperative command

For quick, one-off role creation, use kubectl create role directly:

# Grant get, list, and watch on Pods in the default namespace
kubectl create role pod-reader --verb=get,list,watch --resource=pods -n default

Additional examples:

# Grant access to Pods and Pod status (subresource)
kubectl create role pod-full --verb=get,list,watch --resource=pods,pods/status -n default

# Grant access to a specific resource by name
kubectl create role configmap-reader --verb=get --resource=configmaps --resource-name=my-config -n default

Note

To grant access to subresources such as pods/log or pods/exec, use a slash (/) to separate the resource and subresource in both YAML and imperative commands. For the full RBAC specification, see Roles and ClusterRoles in the Kubernetes documentation.

Create a ClusterRole

A ClusterRole defines permissions that apply across all namespaces or to cluster-scoped resources.

Option 1: Declarative YAML

The following YAML creates a ClusterRole named test-clusterrole that grants full permissions on Pods.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: test-clusterrole
rules:
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - create
  - delete
  - deletecollection
  - get
  - list
  - patch
  - update
  - watch

Apply the YAML to your cluster:

kubectl apply -f clusterrole.yaml

Verify that the ClusterRole was created:

kubectl get clusterrole test-clusterrole -o yaml

Option 2: Imperative command

# Grant get, list, and watch on Pods cluster-wide
kubectl create clusterrole pod-reader --verb=get,list,watch --resource=pods

# Grant access to non-resource URLs
kubectl create clusterrole log-reader --verb=get --non-resource-url="/logs/*"

Option 3: ACS console

Note

The following steps create a ClusterRole. The steps for creating a namespace-scoped Role are similar.

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster.
In the left navigation pane, choose Security > Role.
On the Role page, click the Cluster Role tab.
Click Create.
In the Create YAML pane, enter the ClusterRole YAML content, then click OK.

After creation, the new ClusterRole appears on the Cluster Role tab.

Best practices

Grant only the verbs your workload requires. The examples above grant all eight verbs (create, delete, deletecollection, get, list, patch, update, watch) for demonstration. In production, restrict verbs to the minimum set needed. For example, a monitoring agent typically only needs get, list, and watch.
Prefer namespace-scoped RoleBindings over ClusterRoleBindings. Namespace-scoped bindings limit the blast radius if credentials are compromised.
Avoid wildcard permissions. Using * for resources or verbs grants access to all current and future resource types, which can introduce unintended privilege escalation.

What's next

A Role or ClusterRole has no effect until you bind it to a subject. To grant the role to a RAM user or RAM role, see Grant RBAC permissions to RAM users or RAM roles.

For the full RBAC specification, including aggregated ClusterRoles and default roles, see Roles and ClusterRoles in the Kubernetes documentation.