Skip to content

Architecture decisions

The operator keeps the configuration of an existing OpenBao server in the state Kubernetes custom resources declare. Each record states its status, the context that forced the choice, the decision and the consequences.

Engine: one reconciler serves every kind

Number Title Decision
0001 Use the OpenBao api/v2 client Every OpenBao call uses github.com/openbao/openbao/api/v2 through a small logical client, and adapters call generic paths instead of the typed Sys() helpers.
0002 One generic engine with per-kind adapters and FieldSpec One reconciler serves every kind, each kind supplies an adapter and a FieldSpec, and 0011 replaces the rule that compared only the keys the spec sets.
0011 Full-field comparison with declared defaults The desired payload includes every typed field, an omitted field is sent as the default the adapter declares, and OpenBaoEndpoint still compares only its own data keys.
0012 Ownership: path index and server-side marker The older resource owns a path, a server-side marker wins where the API stores metadata, and a second resource gets Conflict and does not write.
0014 Drift tiers and per-server request budget Access-critical kinds are re-read every 15 minutes and other kinds every hour, with jitter, and a spec change is served ahead of drift reads under that server's rate limit.
0017 Write-once fields for rotated root credentials A write-once field is sent on create and again only when its rotation nonce changes, and it is never compared.

Tenancy: the platform owns the server, and a tenant acts as itself

Number Title Decision
0003 Connection kinds and the tenant boundary A namespaced connection logs in as a ServiceAccount in its own namespace, never as the operator, and a cluster-scoped connection is limited to the namespaces it allows.
0010 OpenBaoServer owns the address and audiences The platform-owned OpenBaoServer holds the address, CA bundle, allowed namespaces, audiences, rate limit and request timeout, and a connection names that server and carries no address of its own.
0021 One writer cluster per OpenBao namespace One OpenBao namespace has one writer cluster, and a marker that names another cluster yields Conflict.

Safety: changes to OpenBao stay explicit

Number Title Decision
0004 Creation and deletion policy defaults This record defaulted creation to CreateOrAdopt and deletion by kind; 0015 replaces both, with Create and Orphan for every kind.
0007 No OpenBao-to-Kubernetes secret sync Secret values stay in OpenBao; the only Kubernetes Secret the operator writes is a value it generates and OpenBao returns once.
0013 Destructive-delete guard Mounts, namespaces, KV and random secrets, audit devices, key material, MFA methods, entities and OpenBaoEndpoint delete only with openbaoconfig.io/allow-destructive-delete: "true", and a terminating Kubernetes namespace orphans them.
0015 Create by default and orphan by default creationPolicy defaults to Create and deletionPolicy defaults to Orphan for every kind.
0016 Observe mode and import tool Observe reads and reports drift and does not write, delete or add a finalizer, and obc-import emits resources in that mode with creationPolicy: Adopt.
0018 Write circuit breaker Rewrites of an owned object whose spec and input secrets are unchanged are capped at 60 per minute per server; creates, adoptions, spec changes and new secret inputs do not spend that budget.
0019 Pause annotation openbaoconfig.io/paused: "true" on a resource, its Kubernetes namespace or its OpenBaoServer stops reads, writes and deletes, and a deletion keeps the finalizer.
0022 Audit attribution header Every request sends X-Openbao-Config-Resource set to the custom resource's group, kind, namespace and name.

API lifecycle: CRDs stay stable as OpenBao changes

Number Title Decision
0005 CEL validation without admission webhooks OpenAPI and CEL in the CRD schema validate each object, and v1alpha1 does not ship an admission webhook.
0006 Endpoint escape hatch OpenBaoEndpoint writes any payload to any path through the same engine, and deletionPolicy: Delete also requires openbaoconfig.io/allow-destructive-delete: "true".
0008 Keep the API group domain openbaoconfig.io openbaoconfig.io is the final domain for every API group and for the annotation prefix.
0009 OpenBao-only target The operator targets OpenBao 2.6 and later only, with no Vault kinds and no flavor detection.
0020 CRD versioning without webhooks A new CRD version only adds fields, Kubernetes converts it with conversion: None, and a conversion webhook is reserved for a break that cannot be avoided.
0023 OpenBao API changes and the CRD lifecycle Adapters absorb OpenBao's wire changes, and a CRD changes only when users gain a field or lose one that OpenBao removed, so an OpenBao release does not bump the CRD version.

KV cleanup

0024. Bounded KV history cleanup records the version cutoff, retained metadata and permissions.