What Are Aggregated ClusterRoles in Kubernetes?

Detailed Answer

Aggregated ClusterRoles allow you to compose multiple ClusterRoles into a single one using label selectors. The RBAC aggregation controller watches for ClusterRoles matching the selector and automatically merges their rules into the parent ClusterRole.

How Aggregation Works

An aggregated ClusterRole has an aggregationRule field with a clusterRoleSelectors list. The controller finds all ClusterRoles matching those selectors and combines their rules.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring-aggregate
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.example.com/aggregate-to-monitoring: "true"
rules: []  # Rules are auto-populated by the controller

Any ClusterRole with the label rbac.example.com/aggregate-to-monitoring: "true" will have its rules merged into monitoring-aggregate.

Built-in Aggregated ClusterRoles

Kubernetes ships with four aggregated ClusterRoles:

kubectl get clusterrole admin -o yaml | head -20

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: admin
  labels:
    kubernetes.io/bootstrapping: rbac-defaults
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules: []  # auto-populated

The four defaults and their aggregation labels:

| ClusterRole | Aggregation Label | |---|---| | admin | rbac.authorization.k8s.io/aggregate-to-admin: "true" | | edit | rbac.authorization.k8s.io/aggregate-to-edit: "true" | | view | rbac.authorization.k8s.io/aggregate-to-view: "true" | | cluster-admin | (not aggregated — it uses a wildcard rule) |

Note: Rules aggregate upward. If a ClusterRole aggregates to view, it also aggregates to edit (which includes view), and edit aggregates to admin.

Real-World Use Case: CRD Permissions

When you create a Custom Resource Definition, users with the admin, edit, or view ClusterRoles cannot access your CRD by default. Aggregation lets you extend these roles automatically.

Suppose you create a CRD for BackupSchedule resources:

# 1. CRD definition (abbreviated)
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: backupschedules.backup.example.com
spec:
  group: backup.example.com
  names:
    kind: BackupSchedule
    plural: backupschedules
  scope: Namespaced
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                schedule:
                  type: string
                retention:
                  type: integer
---
# 2. Read-only access — aggregates into the 'view' ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backupschedule-viewer
  labels:
    rbac.authorization.k8s.io/aggregate-to-view: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules:
  - apiGroups: ["backup.example.com"]
    resources: ["backupschedules"]
    verbs: ["get", "list", "watch"]
---
# 3. Read-write access — aggregates into 'edit' and 'admin'
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backupschedule-editor
  labels:
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules:
  - apiGroups: ["backup.example.com"]
    resources: ["backupschedules"]
    verbs: ["create", "update", "patch", "delete"]

After applying these ClusterRoles:

• Users with the view ClusterRole can get, list, and watch BackupSchedules.
• Users with the edit ClusterRole can also create, update, patch, and delete them.
• Users with the admin ClusterRole get all of the above.

No existing bindings need to change.

Verifying Aggregation

# Check the aggregated rules in the admin ClusterRole
kubectl get clusterrole admin -o yaml | grep -A5 "backupschedules"

# List all ClusterRoles that aggregate into admin
kubectl get clusterroles -l rbac.authorization.k8s.io/aggregate-to-admin=true

# Verify a user with 'view' can see the custom resource
kubectl auth can-i list backupschedules.backup.example.com \
  --as=viewer-user -n default

Creating Custom Aggregated Roles

You can create your own aggregated ClusterRoles for organizational patterns:

# Parent: aggregated role for the platform team
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: platform-ops
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.myorg.com/aggregate-to-platform-ops: "true"
rules: []
---
# Child: networking permissions
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: platform-networking
  labels:
    rbac.myorg.com/aggregate-to-platform-ops: "true"
rules:
  - apiGroups: ["networking.k8s.io"]
    resources: ["networkpolicies", "ingresses"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
# Child: storage permissions
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: platform-storage
  labels:
    rbac.myorg.com/aggregate-to-platform-ops: "true"
rules:
  - apiGroups: [""]
    resources: ["persistentvolumes", "persistentvolumeclaims"]
    verbs: ["get", "list", "watch", "create", "delete"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]

The platform-ops ClusterRole automatically includes all rules from platform-networking and platform-storage. Adding a new child ClusterRole with the matching label extends platform-ops without editing it.

Important Behaviors

1. Rules field is controller-managed. Do not manually edit the rules on an aggregated ClusterRole. The controller will overwrite your changes during the next reconciliation cycle.

2. Reconciliation is continuous. The RBAC aggregation controller runs as part of the controller manager and continuously watches for changes.

3. Order does not matter. The parent and children can be created in any order. The controller reconciles asynchronously.

4. Multiple selectors are OR-ed. If clusterRoleSelectors has multiple entries, a ClusterRole matching any of them is included.

When Not to Use Aggregation

Aggregation is best for extending well-known roles with new resource types. Do not use it as a general-purpose permission composition mechanism when simple Roles and multiple RoleBindings would suffice. Overusing aggregation makes it harder to audit who has access to what, because the permissions are spread across many labeled ClusterRoles.