Split the control plane so pod churn, long-running operations, and status writes stay separate.

OpenBao Operator avoids a single reconciliation loop. The control plane is divided into focused controllers, then delegated into app-layer orchestration and narrower domain managers so the system can react quickly without mixing unrelated responsibilities.

Controller Split

Diagram

Controller split

Workload, admin operations, and status are separated so high-churn reconciliation, long-running workflows, and API status writes do not block each other.

Reference table

Controller responsibilities

Controller responsibilities.

Controller	Primary role	Why it stays separate
Workload	Reconciles StatefulSets, Services, ConfigMaps, and Secrets.	It handles high-churn pod and platform state and needs to react quickly.
AdminOps	Runs upgrades and backups.	Long-running workflows should not block pod recovery or normal reconciliation.
Status	Aggregates state and writes status updates.	Serializing status writes avoids ResourceVersion conflicts and keeps conditions stable.
OpenBaoRestore	Reconciles destructive restore workflows.	Restore needs its own lock-aware control surface instead of riding on normal cluster reconcile loops.
Provisioner	Reconciles OpenBaoTenant onboarding and namespace scaffolding.	Tenant guardrails belong to Day 0 provisioning, not to workload reconciliation.

Restore controller

Restores are reconciled through the separate OpenBaoRestore controller, which orchestrates restore Jobs and acquires the cluster operation lock before destructive work starts.

App Orchestration And Managers

Diagram

App-layer orchestration

Controllers hand off to narrow app-layer facades first, then into focused managers and shared lifecycle services. This keeps import surfaces small and responsibilities explicit.

Reference table

Manager boundaries

Manager boundaries.

Manager	Scope	Key reason for separation
Infrastructure Manager	Renders config and manages StatefulSet-facing infrastructure.	Workload state and rendered configuration change frequently and should stay close to the pod lifecycle.
Cert Manager	Handles operator-managed, ACME, and external TLS interactions.	TLS integration has its own dependency model and readiness surface.
Init Manager	Coordinates initialization when self-init is disabled.	Bootstrap logic is security-sensitive and distinct from normal steady-state reconcile work.
Upgrade / Backup / Restore Managers	Run lock-aware disruptive operations.	These workflows share lifecycle helpers but own different risk profiles and side effects.
Provisioner Manager	Onboards tenant namespaces and guardrails.	Tenant governance belongs to provisioning time, not to the cluster workload loop.

Boundary contract

Controller import surfaces are intentionally narrow and enforced by generated architecture-boundary rules from .ast-grep/policy/architecture-boundaries.yml.

Deep dives

Infrastructure managerSee how configuration rendering and StatefulSet ownership are coordinated.Upgrade managerReview how RollingUpdate and BlueGreen state transitions are modeled.Restore managerUnderstand the destructive restore path and lock lifecycle behind OpenBaoRestore.Lifecycle architectureMove from component boundaries into the day-by-day lifecycle flows that use them.