Manage OpenBao configuration with Kubernetes and GitOps¶
A Kubernetes operator for GitOps management of an existing OpenBao server: policies, auth methods, secrets engines and tenant namespaces as typed custom resources.
The operator manages the configuration of an existing OpenBao server. Server deployment, unsealing and upgrades remain separate; secret delivery tools such as External Secrets Operator consume the configured policies and auth roles.
Choose a task¶
| You want to… | Follow this path |
|---|---|
| Learn the workflow from installation to a Ready policy | Quickstart on kind |
| Define and update an ACL policy | Manage OpenBao policies |
| Give teams their own OpenBao namespaces and identities | Tenant onboarding |
| Reconcile OpenBao configuration from Git | Argo CD integration |
| Configure OIDC login, JWT roles and group mappings | JWT and OIDC authentication |
| Adopt configuration already present in OpenBao | Import and observe mode |
Why this operator¶
Keep OpenBao configuration in Git. Each object is one custom resource, and each tenant logs in through a connection in its own namespace, so that tenant's OpenBao policy is the limit of what it can change. The operator writes only when OpenBao differs from the spec.
Why this operator exists compares it with other tools. The decisions list each architecture choice in one sentence.
Status: alpha
v0.5.0 is the latest release. The API is v1alpha1, so a minor release may change it under the
deprecation policy; the API group domain
openbaoconfig.io is final (ADR 0008). Check the
known limitations before you point the operator at production configuration.
Features¶
-
Typed OpenBao configuration
One custom resource is one object at one OpenBao API path: policies, namespaces, mounts, auth methods and roles, secrets engines, identity, the OIDC provider and MFA.
OpenBaoEndpointcovers any path without a typed kind. -
Tenants act as themselves
The platform team owns
OpenBaoServer. A tenant'sOpenBaoConnectionlogs in with an identity from that tenant's namespace, never as the operator. The tenant's OpenBao policy is the limit. -
Silent at rest
A steady-state reconcile reads and does not write. The load test recorded zero OpenBao writes and zero Kubernetes writes in steady state at up to 5,000 objects.
-
Drift tiers
Access-critical kinds such as policies and auth roles are re-read every 15 minutes, everything else every hour, inside a per-server request budget. Each resource can set its own interval.
-
Observe and import
obc-importreads a running OpenBao and writes custom resources inObservemode, which reports drift and never writes. Switch them toManageone at a time. -
Safe by default
creationPolicy: CreateanddeletionPolicy: Orphanby default, one owner per path, a second guard before deleting mounts, namespaces, KV data, audit devices, key material, MFA methods, entities or the target of anOpenBaoEndpoint, and validation in the CRDs with no webhooks.
Where it fits¶
The operator configures OpenBao. It does not deploy, initialise, unseal or upgrade OpenBao, and it does not copy secret values into Kubernetes (ADR 0007).
flowchart LR
git["Git"] --> gitops["Argo CD or Flux"] --> crs["custom resources"]
crs --> operator["openbao-config-operator"]
operator -- "policies, auth roles, mounts" --> bao[("OpenBao")]
delivery["secret delivery tool"] -- "reads secrets with that configuration" --> bao
delivery --> pods["pods"]
- Configuration as code. Argo CD, Flux or
kubectl applyput the custom resources in the cluster; the operator converges OpenBao to them. The Argo CD guide adds a health check for every kind. - Secret delivery is a separate job. Getting secret values into pods is done by tools such as External Secrets Operator or the Secrets Store CSI Driver. A typical split: this operator writes the policy and the Kubernetes auth role, and the delivery tool logs in with that role to read the secret.
- One exception. When OpenBao returns a generated value only once, such as an AppRole secret ID, the operator
writes that value to a Kubernetes Secret it owns, through
writeSecretRef.