Adopt existing OpenBao configuration¶
This page brings objects that already exist in OpenBao under openbao-config-operator: objects created by hand, by scripts or by another configuration tool. The objects in OpenBao stay where they are; only the manager changes.
Approach¶
Observe first, hand each object over, then retire the old manager. At no point should two tools write the same object.
- Install openbao-config-operator (Install). Create the connections and their OpenBao identities (Connect to OpenBao, OpenBao policy for the operator).
- Stop the previous manager from writing or deleting the objects you hand over. If it deletes an OpenBao object when its own record of that object is removed, switch that off first, so that retiring it in step 7 leaves the object in place.
- Generate the resources with
obc-import, or write them by hand. Each resource needsmanagementPolicy: Observe,creationPolicy: AdoptanddeletionPolicy: Orphan;obc-importsets the first two.AdoptreportsNotFoundinstead of creating an object when a name or path is wrong. - Create the Secrets for write-only fields with their real values. In
Observea missing write-only Secret resolves to an empty value, so the resource still reportsObserved; OpenBao never returns these values, soObservecannot compare them. The first write inManagesends whatever the Secret holds, empty included, so the real values must be in place before step 6 (Import). -
Apply the resources and read their
Syncedcondition.Observedmeans OpenBao matches the spec;Driftednames the keys that differ. Fix the spec until every resource isObserved: -
Switch resources to
managementPolicy: Manage, one namespace or one kind at a time. Check that each resource isReadyand that its events showAdopted, notCreated:An
Updatedevent names the keys that differed from the spec. Fix the spec if the difference was not intended. -
Retire the previous manager's records. With step 2 done, the OpenBao objects stay.
- Once the operator is the only manager, set
deletionPolicy: Deletewhere you want deleting the resource to remove the object; leaveOrphaneverywhere else.
A field the spec leaves unset is not compared, so an adopted object keeps its other settings until the spec names them.
Fields to set¶
| topic | openbao-config-operator |
|---|---|
| connection and login | spec.connectionRef: {kind, name} to an OpenBaoConnection (same namespace) or ClusterOpenBaoConnection |
| OpenBao namespace | the connection's namespace plus the resource's relative spec.namespace (immutable) |
| mount path | spec.mountPath (auth kinds without the auth/ prefix) |
| object name | spec.name, defaulting to metadata.name |
| fields | camelCase OpenBao keys under spec, such as boundServiceAccountNames and tokenPolicies |
| secret inputs | <field>SecretRef: {name, key} in the resource's namespace; the value is hashed into status.writeOnlyHash, never compared |
| generated outputs | writeSecretRef: {name}, only for values OpenBao returns once; no general secret sync (ADR 0007) |
| existing objects | creationPolicy: Create (default), Adopt or CreateOrAdopt |
| deletion | deletionPolicy: Orphan (default) or Delete; destructive kinds (mounts, namespaces, KV data, audit devices, key material, MFA methods, entities and OpenBaoEndpoint) are deleted only with the annotation openbaoconfig.io/allow-destructive-delete: "true" (backup and restore) |
| drift | compared key by key; written only on a difference; driftDetection: Disabled stops re-reads |
Check each field against the CRD before you write the resource:
Which kind¶
The kind catalogue lists every typed kind with its OpenBao path. Manage a path without a
typed kind with OpenBaoEndpoint (ADR 0006). Features with no
typed kind, and what to use instead, are under not typed.