Skip to content
SRE & DevOpsDeep Dive Published Updated 5 min readViews unavailable

Kubernetes RBAC Reconciliation: Using kubectl auth reconcile Safely

Use kubectl auth reconcile to merge RBAC rules and subjects deliberately, preview changes, and avoid accidental privilege removal or binding replacement.

Kubernetes RBAC is declarative, but ordinary manifest workflows can obscure the difference between adding a permission and removing one. kubectl auth reconcile is a specialized command for reconciling Role, ClusterRole, RoleBinding, and ClusterRoleBinding objects. It compares the requested object with the live object and performs RBAC-aware merging. The useful operational question is not just whether a manifest is valid. It is whether the manifest is intended to be additive, authoritative, or allowed to replace an existing binding.

The command is deliberately narrower than kubectl apply. Upstream describes it as preferred for RBAC because it semantically merges rule and subject lists. Keep its input limited to RBAC resources. The implementation handles the four RBAC kinds and skips other object types, so a mixed file should not be treated as a general deployment bundle.

What reconciliation changes by default

For a missing object, reconciliation creates it. For an existing Role or ClusterRole, it adds permissions listed in the input. For a RoleBinding or ClusterRoleBinding, it adds listed subjects. Extra rules and extra subjects are preserved unless their respective removal flags are supplied. This default avoids silently deleting grants that another workflow may own, but it also means a reconciled manifest is not automatically a complete source of truth.

The two removal options are separate controls:

  • --remove-extra-permissions removes rules absent from the desired role.
  • --remove-extra-subjects removes subjects absent from the desired binding.

Treat either option as a privilege-changing migration. Before enabling it, identify every controller and human process that writes the object, compare the live rules or subjects with the approved policy, and arrange an access-recovery path. A manifest that lists one intended service account is not evidence that all other subjects are obsolete.

There is another important boundary: Kubernetes makes a binding’s roleRef immutable. If the desired binding points at a different Role or ClusterRole, kubectl auth reconcile handles that by deleting and recreating the binding. That is not an in-place edit. Every subject on the replacement binding receives the new role’s permissions, so review the full subject list and role target together before proceeding.

A namespaced, read-only example

This example grants one existing service account read access to Pod objects in the metrics namespace. It does not grant Secret access, create workloads, or grant rights outside that namespace.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-observer
  namespace: metrics
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: pod-observer
  namespace: metrics
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: pod-observer
subjects:
- kind: ServiceAccount
  name: scrape-agent
  namespace: metrics

First confirm that the selected kubeconfig context and namespace are the intended target. Then ask the command to calculate and print its planned result without writing RBAC objects:

kubectl config current-context
kubectl --context=staging auth reconcile \
  -f rbac/pod-observer.yaml --dry-run=client -o yaml

Read both the returned object and the reconciliation diagnostics. Check that the Role is namespaced, the resource is only pods, the verbs are only the required reads, and the binding references the expected service account and role. If the output reports extra permissions or subjects, stop and determine who owns them. Do not add the removal flags simply to make the output look cleaner.

When the reviewed change is approved, perform the live reconciliation as a separate command against the explicit context:

kubectl --context=staging auth reconcile -f rbac/pod-observer.yaml

That command is mutating. Keep it in the change window and authorization path used for other RBAC changes. Follow it with kubectl get role,rolebinding -n metrics -o yaml and an authorization check for the intended identity. An impersonated kubectl auth can-i check requires the operator to have the relevant impersonation authority; do not borrow a service-account token to test a grant.

Dry-run mode is command-specific

Use --dry-run=client for this command’s preview, but do not mistake that preview for an offline syntax check or a server admission test. Reconciliation needs the selected cluster state to compare existing objects, and the preview does not persist the calculated changes. It cannot prove that a later live request will pass admission, that permissions will remain unchanged until apply, or that another controller will not race with the operation.

There is a version-sensitive trap in the shared CLI help. The generated reference lists client and server dry-run strategies, but the upstream kubectl auth reconcile implementation pinned below, at commit a1031fca dated 2026-10-14, explicitly rejects --dry-run=server. Treat the behavior of the installed kubectl binary as authoritative, check its version, and use the client preview followed by a separately approved live run. Do not rely on a generic inherited flag description to infer server-side validation support.

Keep the ownership contract explicit

Use kubectl auth reconcile when the desired behavior is RBAC-specific merging. Use a field-management workflow when the desired contract is ownership of particular fields through server-side apply. These are different ownership models, and switching between them without agreement can produce confusing drift or unexpected removals.

Avoid reconciling control-plane default objects with system: names unless the cluster vendor’s procedure specifically requires it. The API server auto-reconciles many default roles and bindings; local changes may be restored or can impair cluster operation. For application teams, prefer dedicated namespaced roles, narrowly scoped bindings, and one documented owner per object.

A safe RBAC rollout makes the ownership decision visible: additive by default, destructive pruning only after inventory, and binding replacement treated as a new grant. Preview the exact target, review both permissions and subjects, then verify effective access without exposing credentials.

Related:

Sources:

Comments