0023. OpenBao API changes and the CRD lifecycle¶
Status: accepted. Date: 2026-11-14.
Context¶
OpenBao ships a minor release every few months and has no long-term-support line. A minor can add, rename, deprecate or remove request fields, change a default, change a read shape, add or remove an endpoint, or need a new capability in a policy. The operator has 68 built-in kinds and 52 plugin kinds whose CRDs users write into Git, so every OpenBao change must reach users without breaking their manifests and without an API version bump on OpenBao's schedule.
Already decided elsewhere and assumed here:
- ADR 0006:
OpenBaoEndpointcovers any path without a typed kind. - ADR 0009: OpenBao only.
- ADR 0020: CRD versions change additively with
conversion: None. - Support window: each operator minor supports the OpenBao
minors that have an API snapshot in
api-coverage/; no version-branching shims in adapters.
Decision¶
1. The CRDs are our API, the adapter is the translation layer¶
CRD field names, types and defaults are chosen for users and stay stable. OpenBao's wire shape lives in the
adapter (Desired, FieldSpec, optional Observer). OpenBao changes are absorbed there first; a CRD changes
only when users gain something (a new field) or lose something upstream removed. CRDs are not generated from
OpenBao's OpenAPI document: generated types leak wire names and churn on every upstream release.
2. How each upstream change maps to the CRD¶
| OpenBao change | CRD change | Mechanism |
|---|---|---|
| new optional request field | new optional field in the served version; unset is not sent | additive; a server that rejects it gives reason Unsupported |
| field renamed on the wire | none | FieldSpec.Aliases |
| type or format change (string to list, duration format) | none when possible | adapter normalisation, FieldSpec.Durations/Sets |
| default changed | none | the no-write conformance gate fails; update the declared default |
| read shape changed | none | read fixtures and the no-write gate fail; fix the adapter |
| field deprecated upstream | Deprecated: doc comment, still read |
deprecation policy |
| field removed upstream | kept while any supported minor has it, then deprecated and removed per policy | support window |
| new endpoint or engine | OpenBaoEndpoint at once; a typed kind later as a new CRD |
additive |
| endpoint removed | the kind reports Unsupported on newer servers; removed after the window |
support window |
| new capability needed in a policy | none | the least-privilege integration run fails (section 4); update docs/operate/openbao-policy.md |
OpenBao's schedule never forces a CRD version bump. Only our own breaking changes do, and ADR 0020 keeps those additive with a deprecation period.
3. CRD version lifecycle¶
v1alpha1today;v1beta1as the storage version at operator 1.0;v1when the API has been stable for a year of releases. Rules per level are in the deprecation policy.- A new version is served alongside the old one with
conversion: None; both schemas stay identical except for additions. Stored objects move with kube-storage-version-migrator; a version leavesservedonly afterstatus.storedVersionsno longer lists it, announced one minor ahead. - The chart ships CRDs as templates with
helm.sh/resource-policy: keep, sohelm upgradeupgrades them and uninstall keeps them; CRDs are applied before the manager rolls. - Every CRD change passes the install test (CEL cost) and
make verify-generated(no hand edits).
4. Detection: every OpenBao minor becomes a failing pull request¶
| Check | Catches | Status |
|---|---|---|
per-minor OpenAPI snapshot, every writable path classified (go test ./test/apicoverage/...) |
new or removed endpoints | in place |
| no-write conformance gate and adapter read fixtures | changed defaults and read shapes | in place |
integration suite against the pinned BAO_VERSION |
behaviour changes on typed kinds | in place |
| field-level coverage: every request parameter of a typed path maps to a CRD field or is excluded with a reason | new fields on typed kinds | to do (BL-014) |
Renovate bumps BAO_VERSION; that pull request refreshes the snapshot and runs every check above |
starts the work without a person watching releases | partly in place: Renovate tracks BAO_VERSION (Makefile, renovate.json) and the pull request runs integration and API coverage; snapshot refresh and conformance on that pull request to do (BL-014) |
| nightly integration run against every supported minor (today 2.6 and 2.7) | regressions on the older minor | to do (BL-014) |
| integration run logged in with the documented least-privilege operator policy, not a root token | new capabilities or sudo requirements |
to do (BL-014) |
api-coverage diff <old> <new>: paths and fields added, removed, changed |
release-note input and triage list | to do (BL-014) |
5. Runtime¶
In place: OpenBaoServer status records the server version from sys/health (status.version in
api/core/v1alpha1/openbaoserver_types.go), and acquired objects are bound to one server by its cluster id
(status.serverID, reason ServerChanged emitted by internal/engine/reconciler.go). To do (BL-014):
Unsupported and PermissionDenied messages name the version. Adapters do not branch on the version: a field or
endpoint the server lacks surfaces as Unsupported.
Consequences¶
- An OpenBao minor costs a maintainer one Renovate pull request: classify new paths and fields, fix what fails, merge. The six-week support target in the release process stays realistic.
- CRDs stay stable across OpenBao minors; users rewrite manifests only on our deprecations.
- The adapter carries the complexity of wire changes, kept small by
FieldSpecand covered by fixtures. - Until BL-014 lands, new fields on typed kinds and new capability requirements are found by users or by reading OpenBao release notes.