Start design changes from the contracts the operator is trying to preserve.

These invariants are the cross-cutting rules behind the rest of the architecture. They explain why some designs are intentionally split, why certain shortcuts are blocked, and which safety properties should survive refactors, new features, or operational changes.

Lifecycle contract

OpenBaoCluster is an operator-owned lifecycle contract. It is not a generic import API for arbitrary unmanaged OpenBao clusters.

Decision matrix

Invariant families

Invariant families.

Family	What the operator is trying to preserve	Why it matters
Identity boundaries	Provisioning, control-plane, and workload trust boundaries stay explicit and mutation-locked.	This keeps privileged access narrow and prevents tenant onboarding or operator RBAC from drifting into normal reconcile paths.
Production posture	Hardened production means self-init, trusted TLS, and a non-static unseal path.	Production safety is a contract, not just a suggested configuration style.
Integration assumptions	External dependencies surface as explicit status and readiness conditions.	This turns environment assumptions into visible contracts instead of late runtime failures.
Lifecycle safety	Disruptive workflows stay explicit, lock-aware, and separated from steady-state workload reconciliation.	This prevents upgrades, backups, and restores from colliding or becoming invisible side effects.

Identity boundary invariants

Reference table

Identity and access

Identity and access.

Invariant	Why it exists	Primary enforcement
Provisioner and controller identities stay separate.	A long-running workload identity should not both mint and consume tenant access.	Split ServiceAccounts, RBAC boundaries, and admission policies.
Rendered operator identities stay internally consistent and mutation-locked.	Install drift in ServiceAccounts, RoleBindings, and admission subjects weakens the control-plane trust model.	Helm/raw-manifest rendering, managed-resource locks, and break-glass allowlists.
Tenant namespace access is introduced explicitly and remains provisioner-owned.	Tenant onboarding should be deliberate, not discovered passively by a broad controller identity.	OpenBaoTenant onboarding flow, tenant governance policy, and controller RBAC exclusions.
Secret access stays name-scoped and non-enumerating.	The operator needs to create or read specific secrets without gaining broad tenant secret visibility.	Allowlisted Secret roles, blind-create patterns, and admission restrictions on managed Secret writes.
Admission enforcement remains part of the normal safety model.	Guardrails should fail early at the API boundary, and loss of those guardrails should pause sensitive reconciliation.	Validating admission policy inventory, runtime admission tracking, and degraded conditions.

Related reading: RBAC Architecture, Admission Policies, and Operator Identity and Access.

Production posture invariants

Reference table

Production posture

Production posture.

Invariant	Why it exists	Primary enforcement
Hardened production requires self-init, trusted TLS, and a non-static unseal path.	This prevents root token Secret persistence and weak bootstrap or transport defaults in production.	Cluster validation, the ProductionReady condition, and hardened-profile checks.
OperatorManaged TLS is not a hardened production path.	Production trust should align with externally managed or OpenBao-native certificate models.	Admission validation and ProductionReady=False when an unsupported TLS mode is selected.
Self-init is the supported production bootstrap path.	Production bootstrap should stay declarative and avoid persisting the initial root token.	Self-init validation, hardened profile requirements, and production posture evaluation.
Operator-owned configuration stays operator-owned.	Networking, storage, seal settings, and listener identity need a single ownership model to stay correct.	Rendered configuration ownership and admission policy enforcement.

Related reading: Security Profiles, TLS and Identity, and Self-Initialization.

Integration invariants

Reference table

External dependencies and readiness

External dependencies and readiness.

Invariant	Why it exists	Primary enforcement
Gateway, ACME, and API-server assumptions surface as explicit conditions.	Environment and controller dependencies should become visible status contracts before they become runtime failures.	GatewayIntegrationReady, ACMEIntegrationReady, ACMECacheReady, and APIServerNetworkReady conditions.
Backup and restore identity stays separate from the main workload identity.	Day-2 Jobs should not silently inherit the wrong auth path, cloud permissions, or egress assumptions from the StatefulSet.	Dedicated job identities, readiness evaluation, and explicit backup/restore status reasons.

Related reading: Status and Events and Configure Backups.

Lifecycle safety invariants

Reference table

Disruptive operation safety

Disruptive operation safety.

Invariant	Why it exists	Primary enforcement
Only one disruptive operation owns the cluster operation lock at a time.	Upgrades, backups, and restores should not collide on the same cluster.	status.operationLock, shared lifecycle coordination, and manager-specific lock handling.
Restore remains destructive, explicit, and lock-aware.	Restore should never be mistaken for a routine reconcile side effect.	OpenBaoRestore, restore validation, override-lock handling, and operation-lock checks.
Break-glass access stays explicit and narrow.	Administrative escape hatches should exist without turning privileged mutation into the normal operating model.	Configured maintenance groups, admission exceptions, and recovery runbooks.
OpenBao remains the source of truth for data consistency and snapshot semantics.	The operator should orchestrate and guard the lifecycle, not reimplement the data plane.	Supervisor pattern, API-driven backup/restore flows, and OpenBao-led snapshot semantics.

Related reading: Operation Lifecycle, Restore from Backup, and Recovery and Restore.

Treat invariant changes as contract changes

If a change weakens one of these invariants, update the related architecture, security, and user-guide pages in the same change set. This is not only an implementation detail; it changes the operating contract of the product.

Continue through the architecture

Component designSee where controllers, app facades, and managers split responsibilities to preserve these invariants.Operation lifecycleTrace how shared lifecycle coordination keeps upgrades, backups, and restores from colliding.Security overviewMove into the user-facing security model that these invariants are designed to protect.