Tech-debt register¶
This register lists material limitations of the current implementation and its verification. Planned product outcomes belong in the backlog; accepted design choices belong in the ADRs. Close an entry by meeting its exit criteria, then delete it or mark it complete with a pointer to the evidence.
TD-001: Live coverage uses OpenBao dev mode¶
Status: open
Integration tests run each kind against bao server -dev: in-memory storage, a root token, one
node, no TLS. The e2e test (test/e2e) runs the manager in kind, where a namespaced connection logs
in with Kubernetes auth through TokenRequest as the tenant ServiceAccount, under a non-root tenant
policy, and reconciles a Policy, a KVSecret and an OpenBaoEndpoint through create, drift
repair, steady state and delete; a two-tenant e2e test (test/e2e/isolation_test.go) proves that a second tenant's writes outside its OpenBao namespace and policy, its references to another tenant's objects and its use of a server that excludes it are refused, and that none of the objects it tried to create exists in OpenBao.
In the e2e workflow, test/livekit/kind.sh also applies the live kit (64 built-in kinds, the database kinds
against PostgreSQL) to a three-node Raft OpenBao with TLS and persistent volumes (hack/e2e/openbao.yaml), logged
in with non-root tokens (Kubernetes auth, AppRole and an orphan token under an admin policy). The four kinds with dedicated integration fixtures run only
against bao server -dev, and the external-plugin kinds only in golden payload tests
(verification guide).
Exit criteria: the per-kind tests run against a server with persistent storage, TLS and a
non-root token. The second-tenant scenario is done (test/e2e/isolation_test.go). Storage, HA,
TLS and backup behaviour of the server stay out of scope.
TD-002: Compatibility with other servers was claimed but not tested¶
Status: closed by ADR 0009. The project targets OpenBao only and makes no compatibility claim for other servers.
TD-003: No OpenAPI field coverage check¶
Status: open
Path-level coverage is checked: api-coverage/ holds the OpenAPI snapshots for OpenBao 2.6 and 2.7,
and make api-coverage (CI job api-coverage) and test/apicoverage fail when a writable path is
unclassified. Field-level coverage is not checked, so a request field added or renamed upstream on a
typed path is noticed only by hand.
Exit criteria: a check that lists the request fields of each typed path that map to no CRD field and have no recorded exclusion (BL-014).
TD-004: Unconfirmed paths and external-plugin kinds¶
Status: open
Rows marked (u) in the kind catalogue take their path from documentation, not from
OpenBao source. External-plugin kinds cannot run against
bao server -dev, so they are verified by golden payload tests only.
Exit criteria: before an external-plugin kind is un-gated (phase 6), confirm its path in the plugin source and run
it once against a server with the plugin registered through Plugin; remove the (u) mark.
TD-005: The default install can read Secrets cluster-wide¶
Status: open; mitigated by watchNamespaces
Without watchNamespaces, the manager ClusterRole can get, list and watch Secrets and
ConfigMaps and request ServiceAccount tokens in every namespace, because any namespace may hold
a connection or a referenced Secret. The tenant boundary is enforced by the OpenBao identity of
each connection, not by Kubernetes RBAC. Setting watchNamespaces in the Helm chart replaces the
cluster-wide grants with a Role per listed namespace.
Exit criteria: keep the scoped install covered by make validate-manifests, document which
install mode fits which tenancy model, and revisit only if a shared installation needs
controller-enforced Secret scoping.
TD-006: The docs site depends on Material for MkDocs, which reaches end of life¶
Status: open
The documentation site is built with MkDocs and the Material theme (mkdocs.yml,
hack/docs/requirements.txt). Material for MkDocs is in maintenance mode and reaches end of life on
2027-05-05; its authors point users to Zensical as the successor.
Exit criteria: before 2027-05-05, build the site with Zensical (or another maintained generator),
keep mkdocs build --strict equivalent link checking in CI, and drop the Material pin.
TD-007: Some adapters read OpenBao and Kubernetes outside the engine's resolver¶
Status: open
Desired gets no OpenBao client, so seven adapters resolve their connection themselves inside Desired
through refs.For and an adapter-held engine.Connections (GroupMembership, EntityAlias, GroupAlias,
OIDCAssignment, OIDCProvider, MFALoginEnforcement, Policy with accessorRefs), and AuthMount and SecretsMount
read Plugins through an adapter-held client.Reader instead of Resolver.Object. These reads bypass the
client of the pass (request attribution, priority, the namespace and server checks done in connect) and the
read-only resolver of managementPolicy: Observe, and a zero-value adapter fails with "needs a reader".
Two ways out, both a contract change for the maintainers:
- pass the pass's namespace-scoped
openbao.ClienttoDesired(or to a new optionalDesiredWithClient), and route every Kubernetes read throughResolver.Object; - move the OpenBao name lookups into
PathResolverorObserver, which already get the client, and keepDesiredpure.
Exit criteria: no adapter holds engine.Connections or a client.Reader for use in Desired.
TD-008: A KV history purge can destroy a version written right before it¶
Status: mitigated for concurrent version writes; metadata recreation remains a boundary.
Destructive cleanup of an operator-created KVSecret or RandomSecret now persists
status.purgeThroughVersion before destroying history. It sends bounded batches to
<mount>/destroy/<path>, never deletes metadata, and never extends that cutoff on retries.
Newer versions survive even when they are written between observation and destruction.
The connection needs read on metadata and update on destroy; see
ADR 0024.
OpenBao has no conditional path-incarnation check: an administrator who deletes metadata and recreates the same path resets its version numbers. Do not do that while cleanup is pending. Historical versions up to the cutoff may also contain another writer's older keys; destructive cleanup is therefore still opt-in and suitable only for an exclusively administered path.
Exit criteria: an upstream conditional destroy API can bind cleanup to the original metadata incarnation, or external metadata deletion/recreation is excluded operationally.