design-proposal: tenant-supplied secrets by reference through External Secrets Operator

[Timofei Larkin (lllamnyp)]

Adds design-proposals/tenant-supplied-secrets/: how a tenant supplies a secret to a managed application without a plaintext field in the spec and without any grant on core/v1 Secrets.

Tenants get a secret store of their own; application specs reference an entry in it by name; a chart-rendered ExternalSecret materialises the value for the operator. External Secrets Operator becomes a required component. The default store is a single platform OpenBao with one OpenBao namespace per tenant, but the only coupling to any store is one per-tenant SecretStore object, overridable cluster-wide by the operator and per tenant by the tenant, so an external OpenBao, a cloud secrets manager, or the tenant's own managed OpenBao all fit behind the same seam. Tenant Kubernetes clusters consume from the same store through an externalSecrets addon, with a per-cluster auth method the platform provisions.

The store topology is the main open question: the text recommends the in-cluster instance as the installed default, an external OpenBao as the documented production posture, and per-tenant instances as a tenant-level choice. Reviewers who would set a different default should argue it there. The concrete reference shape is deliberately left to the first conversions.

Relationship to existing work

• Absorbs design-proposal: SecretRef for external credentials in managed app specs #37 (SecretRef for external credentials): its per-engine analysis and reference-passing rule are adopted, and its open prerequisite, how a tenant creates the referenced object, is what this answers. Proposes closing design-proposal: SecretRef for external credentials in managed app specs #37 as superseded once this is accepted.
• Inherits feat: Replace Helm lookup with OpenBao + ESO + Operator architecture cozystack#1942 (OpenBao plus External Secrets Operator) as prior work: its storage half is this proposal, its generation half belongs to design-proposal: user secrets API, credentials minted on request and shown once #74.
• Sits beside design-proposal: user secrets API, credentials minted on request and shown once #74 (user secrets API): that proposal keeps platform-generated credentials and rotation; this one keeps tenant-supplied secrets. Its phase 2 is withdrawn in favour of this proposal, per the maintainers' call.
• Builds on the central OpenBao in feat(openbao): central platform instance and per-tenant transit provisioning cozystack#4177 and the auto-unseal work in feat(openbao): optional static-key auto-unseal and apiserver egress label cozystack#4168.
• First consumers waiting on it: VM import, MariaDB users, and the site-to-site gateway from the merged tenant-site-connectivity proposal.

Opening non-draft for direction review. Extends the platform's required components and the Tenant and Kubernetes application schemas, so it sits behind the API-owner gate.

Before review

• If this revises a merged design proposal: it adds a decision record under that proposal's decisions/ directory, or says below why none is needed. New proposal; no decision record needed.

DCO

• Commits are signed off (git commit --signoff).

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 12b76c38-38ba-42d7-a3a6-36ce2de53d01

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Timofei Larkin (lllamnyp)]

Revised in response to the discussion on #74, where this proposal was read as making External Secrets Operator and a central OpenBao required components. It never should have said so, and it did. What changed:

• Capability model instead of required components. Both are default-installed optional packages. Disabling External Secrets Operator makes a chart that receives a reference fail the render naming the capability, the way database autoscaling already fails without KEDA; an application whose only credential field is reference-only is not installable there. Disabling the default store leaves the seam waiting for a provider override. The tenant chart gates its SecretStore on the operator's API being present, so disabling the package does not fail tenant releases on an unknown kind. The expected trajectory, that conversions narrow what an installation without the capability can run, is stated as intended rather than left implied.
• Rollout reordered so nothing waits on the central OpenBao. The seam takes any store, so the first consumers are validated against a managed OpenBao application and an external store before feat(openbao): central platform instance and per-tenant transit provisioning cozystack#4177 lands. The central instance becomes step 5, not step 2.
• Platform service-account credentials named as a non-goal. MariaDB root, ClickHouse's backup user, OpenSearch admin and Harbor's redis password are neither tenant-supplied nor tenant-facing; separating them from tenant users belongs to design-proposal: user secrets API, credentials minted on request and shown once #74's closure of the raw-grant route.
• The write-only TenantSecret alternative argued concretely rather than dismissed: what create, update and delete on tenantsecrets each let a tenant do in a namespace shared with operator secrets, and why fencing that in is building a secrets engine inside an aggregated API. The stopgap of granting those verbs is dropped; the interim for strict installations is design-proposal: user secrets API, credentials minted on request and shown once #74 admitting the inline form as Legacy for reference-only classes until the capability exists.
• The no-Keycloak write path stated plainly: one ServiceAccount identity per tenant, audit names the tenant.

The phase-2 withdrawal is no longer recorded as done; the scope section says the comparison is what this review settles.