guardian

RBAC governance operator for the ONT platform. Guardian owns all RBAC across every cluster. No operator, application, or human provisions Kubernetes RBAC outside of guardian.

API group: guardian.ontai.dev

---

CRD types

All types under guardian.ontai.dev/v1alpha1.

Kind	Short name	Scope	Description
RBACPolicy	rp	Namespaced	Governing policy constraining what RBACProfiles in its scope may declare
RBACProfile	rbp	Namespaced	Per-component per-tenant permission declaration; gates operator enablement
PermissionSet	ps	Namespaced	Named, reusable collection of permission rules; used as governance ceiling
PermissionSnapshot	psn	Namespaced	Computed, versioned, signed EPG for a specific target cluster; never hand-authored
PermissionSnapshotReceipt	psr	Namespaced	Target-cluster acknowledgement record; written by conductor in agent mode
IdentityProvider	idp	Namespaced	External identity source declaration (OIDC, PKI, token)
IdentityBinding	ib	Namespaced	Maps an external identity to an ONT permission principal

---

Architecture

Management cluster role

Guardian runs as a single Deployment on the management cluster with GUARDIAN_ROLE=management. It is provisioned exclusively by the compiler enable bundle. No human, operator, or pipeline stamps role=management on a Guardian Deployment.

Responsibilities in this role:

• EPG computation from provisioned RBACProfiles
• PermissionSnapshot generation (one per target cluster)
• Policy validation and admission webhook enforcement on the management cluster
• ClusterRBACPolicyReconciler: creates cluster-policy and cluster-maximum per TalosCluster
• APIGroupSweepController: extends management-maximum as new CRD API groups are discovered
• PermissionService gRPC: the authoritative authorization decision point for the fleet
• AuditSinkReconciler: receives forwarded audit events from federated tenant Guardians
• CNPG-backed persistence for EPG and audit state

Guardian deploys first. No other operator is considered enabled until its RBACProfile reaches provisioned=true. INV-003.

Target cluster admission via conductor

Guardian does not deploy a separate agent on target clusters. Conductor in agent mode (CONDUCTOR_ROLE=tenant) hosts the security plane on each target cluster:

• Admission webhook at /validate/rbac-ownership: rejects unannotated RBAC resources
• PermissionSnapshotReceipt: acknowledges the current signed snapshot
• Local PermissionService gRPC: serves authorization decisions from the locally acknowledged snapshot

The conductor local PermissionService means target cluster authorization decisions are fully operational even when the management cluster is temporarily unreachable.

Optional tenant Guardian

Tenants may optionally deploy a Guardian ClusterPack (GUARDIAN_ROLE=tenant) via the Dispatcher pack delivery flow. Role=tenant Guardian is sovereign by default: it connects to a tenant-local CNPG instance and does not forward audit events to the management Guardian unless GUARDIAN_AUDIT_FORWARD=true is explicitly set. Platform never knows whether a tenant has deployed Guardian and never depends on its presence.

---

Two-phase boot

Guardian on the management cluster starts after the CNPG operator and CNPG Cluster CR are pre-provisioned by the compiler enable bundle (phase 0).

Phase 1 - Migration and bootstrap:

1. Startup migration runner connects to CNPG and applies all pending schema migrations. If CNPG is unreachable, Guardian holds in degraded state until CNPG becomes reachable. This is the only blocking gate before controller registration.
2. Bootstrap annotation sweep stamps ontai.dev/rbac-owner=guardian on all pre-existing RBAC resources across non-exempt namespaces (audit mode during the sweep).
3. Guardian creates baseline PermissionSet, RBACPolicy, and RBACProfile for each known third-party component whose namespace is present.

Phase 2 - Full enforcement:

4. All role-gated controllers register. The admission webhook becomes operational. The bootstrap RBAC window closes permanently. INV-020.
5. BootstrapController monitors all RBACProfiles. Once all profiles reach provisioned=true, the webhook advances from ObserveOnly to Enforcing. Any RBAC resource created or updated without ontai.dev/rbac-owner=guardian is rejected at admission.

The two-phase transition is a named, explicit event. It is never a silent fallback.

---

Build

make build
make docker-build
make docker-push

---

Test

make test
make e2e

E2e specs live under test/e2e/ and skip automatically when MGMT_KUBECONFIG is absent. Every skipped spec references the exact backlog item ID required for promotion to live.

---

Schema

The authoritative field reference is docs/guardian-schema.md.

---

Issues

https://github.com/ontai-dev/guardian/issues

---

guardian - Seam RBAC Governance / Apache License, Version 2.0