kubernetes-rbac

name	kubernetes-rbac
description	Implements rbac.authorization.k8s.io/v1 Role, ClusterRole, RoleBinding, and ClusterRoleBinding manifests with least privilege access control for Kubernetes resources.
license	MIT
compatibility	opencode
metadata	{"version":"1.0.0","domain":"cncf","triggers":"least privilege, role binding, clusterrole, service account, rbac.authorization.k8s.io, namespace permissions, access control","archetypes":["tactical","enforcement"],"anti_triggers":["http routing","tls termination","persistent volume","pod isolation"],"response_profile":{"verbosity":"low","directive_strength":"high","abstraction_level":"operational"},"role":"implementation","scope":"implementation","output-format":"code","content-types":["code","guidance","config","do-dont"],"related-skills":"cncf/kubernetes-deployment, cncf/kyverno-pod-security-baseline, cncf/open-policy-agent-opa"}

Kubernetes RBAC Manager

Implements rbac.authorization.k8s.io/v1 Role, ClusterRole, RoleBinding, and ClusterRoleBinding manifests to enforce least-privilege access control for Kubernetes API resources. When loaded, the model generates production-grade RBAC policies with scoped permissions, service account binding, and audit-ready role definitions.

TL;DR Checklist

• Use rbac.authorization.k8s.io/v1 API version — never rbac.authorization.k8s.io/v1beta1
• Follow the principle of least privilege — grant only the permissions each service account actually needs
• Prefer namespace-scoped Role + RoleBinding over cluster-wide ClusterRole + ClusterRoleBinding
• Always bind roles to specific service accounts — never bind to system:anonymous or wildcard users
• Avoid verbs: ["*"] and resources: ["*"] — specify exact verbs and resources required
• Document the justification for each resource/verb pair in the role comments

---

When to Use

Use this skill when:

• Setting up RBAC policies for CI/CD pipeline service accounts (e.g., Argo CD, Tekton)
• Configuring read-only access for monitoring tools (Prometheus, Grafana)
• Implementing namespace isolation so teams can only manage their own namespaces
• Restricting access to sensitive resources (Secrets, ConfigMaps, Nodes, RBAC resources)
• Creating custom roles for specific application workloads with minimal permissions

---

When NOT to Use

Avoid this skill for:

• User authentication — that is handled by OIDC, SAML, or LDAP identity providers, not RBAC roles
• Kubernetes API audit logging — that is configured via the apiserver audit policy, not RBAC
• Admission-time policy enforcement — use cncf/kyverno-pod-security-baseline or cncf/open-policy-agent-opa instead
• Pod security enforcement — use cncf/kyverno-pod-security-baseline to restrict pod capabilities

---

Core Workflow

1. Identify the Service Account — Determine which service account needs access and what resources it must interact with. Checkpoint: Each workload should have its own dedicated service account — never use the default service account.

2. Define Namespace-Scoped Role — Create a Role with specific resources, verbs, and subresources. Checkpoint: List every resource and verb explicitly — never use wildcards (*).

3. Create RoleBinding — Bind the Role to the service account within the namespace. Checkpoint: Ensure the roleRef.apiGroup is rbac.authorization.k8s.io, roleRef.kind matches the Role kind, and roleRef.name matches the Role name.

4. Escalate to ClusterRole if Needed — For resources that exist cluster-wide (Nodes, PersistentVolumes, StorageClasses), create a ClusterRole and ClusterRoleBinding. Checkpoint: ClusterRoles should be used sparingly and only when cross-namespace access is genuinely required.

5. Apply and Verify — Apply the RBAC manifests and verify access using kubectl auth can-i. Checkpoint: Test both allowed and denied operations to confirm the policy is precise.

6. Audit Access Periodically — Review RBAC policies quarterly and remove unused permissions. Checkpoint: Run kubectl auth can-i --list --as=system:serviceaccount:<ns>:<sa> to audit existing permissions.

---

Implementation Patterns

Pattern 1: Namespace-Scoped Role and Binding for an Application

A production-grade RBAC setup for a deployment automation service account.

# Role: Deployment automation can manage Deployments, Services, ConfigMaps, and Secrets
# within the production namespace only.
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: deployment-manager
  namespace: production
rules:
  # Manage deployments and their associated pods
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  # Manage pods (read-only — deployments manage pod creation)
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
  # Manage services for load balancing
  - apiGroups: [""]
    resources: ["services"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  # Read configuration
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch"]
  # Manage application secrets (create/update only — never list/delete)
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "create", "update", "patch"]
---
# Bind the Role to the deployment-manager service account
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: deployment-manager-binding
  namespace: production
subjects:
  - kind: ServiceAccount
    name: deployment-manager
    namespace: production
roleRef:
  kind: Role
  name: deployment-manager
  apiGroup: rbac.authorization.k8s.io
---
# The service account that the deployment manager uses
apiVersion: v1
kind: ServiceAccount
metadata:
  name: deployment-manager
  namespace: production

Pattern 2: ClusterRole and Least Privilege (BAD vs GOOD)

Overly permissive RBAC is the most common security misconfiguration in Kubernetes clusters.

# ❌ BAD: Wildcard permissions — this grants full cluster-admin equivalent access
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: overprivileged-role
rules:
  - apiGroups: ["*"]       # ← All API groups
    resources: ["*"]       # ← All resources
    verbs: ["*"]           # ← All verbs (including delete, impersonate, escalate)

# ❌ BAD: Binding to the default service account — every pod in the namespace
# inherits these permissions, massively expanding the attack surface
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: default-binding
  namespace: production
subjects:
  - kind: ServiceAccount
    name: default          # ← Wildcard: grants to ALL pods
    namespace: production
roleRef:
  kind: Role
  name: deployment-manager
  apiGroup: rbac.authorization.k8s.io

# ❌ BAD: Granting access to sensitive resources without justification
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: dangerous-role
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "delete"]  # ← Full CRUD on all secrets cluster-wide
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles", "rolebindings"]
    verbs: ["*"]  # ← Can modify RBAC itself — privilege escalation risk

# ✅ GOOD: Least privilege — deployment manager gets exactly what it needs
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ci-pipeline-runner
rules:
  # Read-only access to all namespaces for discovery
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets"]
    verbs: ["get", "list", "watch"]
  # Create/patch pods in any namespace (for job runner pods)
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch", "create", "delete"]
  # Read service accounts to generate token references
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list"]

# ✅ GOOD: Bind to a specific service account, not the default
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ci-pipeline-runner-binding
subjects:
  - kind: ServiceAccount
    name: ci-pipeline
    namespace: ci-tools
roleRef:
  kind: ClusterRole
  name: ci-pipeline-runner
  apiGroup: rbac.authorization.k8s.io

Pattern 3: RBAC Access Verification and Audit

def generate_rbac_commands(role_name: str, namespace: str, sa_name: str = "") -> list[str]:
    """Generate kubectl commands to verify and audit an RBAC policy.

    Useful for confirming that a RoleBinding grants the expected permissions
    and for auditing existing access.

    Args:
        role_name: The Role or ClusterRole name to audit.
        namespace: The namespace context.
        sa_name: Optional service account name to check specifically.

    Returns:
        List of kubectl commands for verification and audit.
    """
    commands = [
        f"kubectl describe role {role_name} -n {namespace}",
        f"kubectl describe rolebinding {role_name}-binding -n {namespace}",
        f"kubectl auth can-i create deployments --as=system:serviceaccount:{namespace}:{sa_name or 'default'} -n {namespace}",
        f"kubectl auth can-i delete deployments --as=system:serviceaccount:{namespace}:{sa_name or 'default'} -n {namespace}",
    ]
    return commands


def verify_role_binding(binding: dict) -> list[str]:
    """Verify a RoleBinding or ClusterRoleBinding has correct structure.

    Checks that roleRef fields are consistent and subjects are properly defined.

    Args:
        binding: A parsed RoleBinding or ClusterRoleBinding manifest dict.

    Returns:
        List of validation error messages. Empty means binding is valid.
    """
    errors: list[str] = []
    metadata = binding.get("metadata", {})
    spec = binding.get("spec", {})

    api_group = spec.get("roleRef", {}).get("apiGroup", "")
    role_kind = spec.get("roleRef", {}).get("kind", "")
    role_name = spec.get("roleRef", {}).get("name", "")

    if api_group != "rbac.authorization.k8s.io":
        errors.append(f"roleRef.apiGroup must be 'rbac.authorization.k8s.io', got '{api_group}'")
    if not role_kind:
        errors.append("roleRef.kind is required (Role or ClusterRole)")
    if not role_name:
        errors.append("roleRef.name is required")

    subjects = spec.get("subjects", [])
    if not subjects:
        errors.append("subjects list is empty — no one is granted this role")

    for subject in subjects:
        if subject.get("kind") not in ("User", "Group", "ServiceAccount"):
            errors.append(f"Invalid subject kind: '{subject.get('kind')}' — must be User, Group, or ServiceAccount")
        if not subject.get("name"):
            errors.append(f"Subject is missing 'name' field")

    return errors

---

Constraints

MUST DO

• Always use rbac.authorization.k8s.io/v1 API version — never rbac.authorization.k8s.io/v1beta1 (removed in Kubernetes 1.22+)
• Follow the principle of least privilege — list only the specific resources and verbs each service account needs
• Use namespace-scoped Role + RoleBinding whenever possible — prefer scoping over cluster-wide ClusterRole + ClusterRoleBinding
• Always bind roles to a dedicated ServiceAccount — never bind to the default service account or to system:anonymous
• Specify exact apiGroups, resources, and verbs — never use wildcards (*)
• Always include roleRef.apiGroup: rbac.authorization.k8s.io in every binding — omitting it causes binding failure
• Use kubectl auth can-i to verify RBAC policies grant the intended permissions after deployment
• Document the justification for each resource/verb pair in the role's metadata annotations

MUST NOT DO

• Never grant verbs: ["*"] or resources: ["*"] — this is equivalent to cluster-admin and violates least privilege
• Never grant access to secrets with list and delete verbs — any pod with this can read all secrets in the namespace
• Never bind a ClusterRole to a ServiceAccount without specifying the correct namespace in the binding's subjects
• Never grant access to rbac.authorization.k8s.io resources (roles, rolebindings, clusterroles) — this enables privilege escalation
• Never use escalate or bind verbs in any role — these allow modifying RBAC policies
• Never create a RoleBinding without a matching Role — the binding is silently ignored

---

Output Template

When implementing Kubernetes RBAC policies, produce the following:

1. Role or ClusterRole YAML — Complete role definition with specific resources, verbs, and apiGroups.
2. RoleBinding or ClusterRoleBinding YAML — Binding that connects the role to the target service account or user.
3. ServiceAccount YAML (if needed) — The dedicated service account that receives the role binding.
4. Access Verification Commands — kubectl auth can-i commands to verify the policy grants the expected permissions.

---

Related Skills

Skill	Purpose
kubernetes-deployment	Reference the RBAC service account in Deployment pod specs via serviceAccountName
cncf/kyverno-pod-security-baseline	Enforce pod security standards alongside RBAC for defense-in-depth
cncf/open-policy-agent-opa	Apply admission-time policy enforcement for RBAC compliance validation
cncf/keycloak	Integrate Kubernetes with external identity providers for user authentication

---

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• Kubernetes RBAC Documentation — Official guide to RBAC concepts, roles, and bindings
• Role-Based Access Control (RBAC) API Reference — Complete API schema for Role, ClusterRole, RoleBinding, and ClusterRoleBinding
• Constructing a Role — Guidelines for creating least-privilege roles
• Using RBAC Authorization — How the RBAC authorizer evaluates API requests
• Service Accounts — Service account management and token configuration
• Auth Can-I Tool — Using kubectl auth can-i for RBAC verification
• RBAC Best Practices — Operational guidance for RBAC deployment