Skip to content

Child Cluster RBAC Policy#

k0rdent can manage authorization inside child clusters through the RBACPolicy resource. An RBACPolicy is a role catalog: a list of bindings, each mapping one Kubernetes ClusterRole to a set of users and groups. The RBAC operator, which is part of the KCM controller, applies the catalog to the child cluster of every ClusterDeployment that references it, and keeps it in sync.

RBACPolicy complements ClusterAuthentication: ClusterAuthentication defines how the child cluster API server identifies users, while RBACPolicy defines what those users are allowed to do.

RBACPolicy Resource#

RBACPolicy is a namespaced resource (short name rbacpol) in the k0rdent.mirantis.com/v1beta1 API group. Each RBACPolicy can be referenced by one or more ClusterDeployment objects in the same namespace.

Example#

apiVersion: k0rdent.mirantis.com/v1beta1
kind: RBACPolicy
metadata:
  name: project-2-rbac
  namespace: kcm-system
spec:
  bindings:
    # Bind a built-in ClusterRole that already exists in the child cluster.
    - name: project-viewer
      clusterRole: view
      subjects:
        - kind: Group
          name: k0rdent:project:project-2:viewer
        - kind: User
          name: bob@example.com

    # Define a custom ClusterRole inline and bind it.
    - name: compute-admin
      clusterRole: k0rdent-compute-admin
      rules:
        - apiGroups: [""]
          resources: ["pods", "pods/log"]
          verbs: ["get", "list", "watch", "delete"]
        - apiGroups: ["apps"]
          resources: ["deployments", "statefulsets"]
          verbs: ["*"]
      subjects:
        - kind: Group
          name: k0rdent:project:project-2:compute-admin
        - kind: User
          name: alice@example.com

Key Fields#

  • spec.bindings (required, 1-200 entries) – The role catalog. Each entry produces one ClusterRoleBinding in the child cluster.
  • spec.bindings[].name (required) – Unique name of the binding within the policy. The generated ClusterRoleBinding is named k0rdent-<name>, so the result must be a valid DNS-1123 subdomain.
  • spec.bindings[].clusterRole (required) – Name of the ClusterRole to bind. It can be a built-in role (for example, admin, edit, view), a custom role that already exists in the child cluster, or a role defined inline using rules.
  • spec.bindings[].rules (optional) – PolicyRule objects for the ClusterRole. If set, the operator creates or updates the ClusterRole with these rules. If omitted, the ClusterRole must already exist in the child cluster.
  • spec.bindings[].subjects (required) – Subjects to bind. Each subject has a kind (User or Group) and a name. The name is used verbatim, so it must match the user or group name that the child cluster authentication produces, for example, after the claim mappings and prefixes configured in ClusterAuthentication.

Note

RBACPolicy grants cluster-wide permissions only. A binding always produces a ClusterRoleBinding; Role and RoleBinding objects and ServiceAccount subjects are not supported. To grant namespaced permissions, manage them through a service deployed to the child cluster.

Validation#

The validation webhook rejects an RBACPolicy in the following cases:

  • Two bindings have the same name.
  • A binding contains duplicate subjects.
  • The generated ClusterRoleBinding name (k0rdent-<name>) or, when rules are set, the clusterRole name is not a valid object name.
  • The same clusterRole has rules defined in more than one binding.

The webhook also blocks deletion of an RBACPolicy while any ClusterDeployment still references it.

Configuring RBAC Policy for ClusterDeployments#

To apply an RBACPolicy to a cluster, set the spec.rbacPolicy field of the ClusterDeployment to the name of an RBACPolicy in the same namespace:

apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: cluster-name
  namespace: kcm-system
spec:
  template: openstack-hosted-cp-1-0-12
  credential: openstack-cluster-identity-cred
  rbacPolicy: project-2-rbac

Note

RBACPolicy objects can be distributed across namespaces using the AccessManagement resource.

How the RBAC Operator Works#

The RBAC operator runs as a step of the ClusterDeployment reconciliation. It connects to the child cluster using the kubeconfig generated by Cluster API, so it does not wait for the cluster to be fully ready, only for the kubeconfig to be available.

For each binding in the referenced RBACPolicy, the operator:

  1. Creates or updates the ClusterRole if the binding defines rules. The operator never modifies a ClusterRole that it did not create. If a ClusterRole with the same name already exists in the child cluster, the binding fails.
  2. Creates or updates the k0rdent-<name> ClusterRoleBinding that binds the ClusterRole to the subjects. If clusterRole of the binding changes, the operator recreates the ClusterRoleBinding, because its roleRef is immutable.

All objects that the operator creates in the child cluster are labeled with k0rdent.mirantis.com/managed-by: rbac-operator. Any object with this label that is no longer described by the policy is deleted. As a result:

  • Removing a binding from the RBACPolicy revokes the corresponding ClusterRoleBinding and the ClusterRole created for it.
  • Removing spec.rbacPolicy from the ClusterDeployment, or deleting the referenced RBACPolicy, revokes all objects the operator created in the child cluster.

A failure in one binding does not stop the others from being applied. The operator re-syncs every 5 minutes to correct drift, for example, if a managed object was modified or deleted directly in the child cluster.

Status#

The result of the sync is reported in the RBACPolicyReady condition of the ClusterDeployment:

Status Reason Meaning
True Succeeded All bindings of the referenced RBACPolicy generation are applied.
Unknown Progressing The child cluster kubeconfig is not available yet.
False RBACPolicyPartiallyApplied Some bindings failed to apply. Others may already be in effect.
False RBACPolicyNotFound The referenced RBACPolicy does not exist. Previously granted objects are revoked.
False Failed The RBACPolicy is invalid or cannot be read.

The status.rbacPolicyGrant field of the ClusterDeployment is set to Granted while objects created by the operator may exist in the child cluster, and is cleared once all of them are revoked.

To check the status, run:

kubectl -n kcm-system get clusterdeployment cluster-name \
  -o jsonpath='{.status.conditions[?(@.type=="RBACPolicyReady")]}'

Access to RBACPolicy Objects#

RBACPolicy objects are as privileged as the child clusters they reach: rules are applied with the Cluster API admin kubeconfig, so arbitrary rules, including wildcards, are accepted and the Kubernetes escalate and bind protections of the child cluster do not apply. Grant permission to manage RBACPolicy objects only to users who already have administrative access to the target clusters.

k0rdent ships the following roles for RBACPolicy objects, which are aggregated into the namespace-scoped roles:

  • kcm-rbacpolicies-creator-role – Full access to RBACPolicy objects. Aggregated into the Namespace Admin role.
  • kcm-rbacpolicies-viewer-role – Read-only access to RBACPolicy objects. Aggregated into the Namespace Editor and Namespace Viewer roles.