Skip to content

Commit a381944

Browse files
docs(user-secrets-api): state finalizer placement and forced deletion behaviour
Review found cross-namespace finalization under-specified: the text required controller finalization without saying where finalizers sit or what happens while the controller is unavailable. Place them only on platform-side records so an unavailable controller cannot block tenant deletion, and state that a forced namespace deletion leaves surviving records to be resolved by bound UID rather than read as a fresh install. The cleanup sequence itself is unchanged and stays where it already is. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent f277c55 commit a381944

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

‎design-proposals/user-secrets-api/details.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Add a versioned API in `core.cozystack.io`, served by the aggregated API server.
88

99
Persist an internal `CredentialRecord` CR per account and, in phase 2, a `CredentialInputRecord` per supplier input. These are CRD-backed Kubernetes objects stored by kube-apiserver in etcd, with durable state across aggregated-server and controller restarts. They live in a platform-controlled namespace, have real UIDs, and are inaccessible through tenant raw APIs. Bind a record to the tenant namespace UID, backing HelmRelease UID, and a server-assigned account incarnation. Do not owner-reference a virtual application. Removing and later re-adding an engine username creates a new account incarnation; cosmetic display-name changes do not. Kubernetes names are derived from opaque IDs, never lossy username normalization.
1010

11-
The credential record holds policy revision, active and candidate version IDs, operation ordering, collection state, and a bounded transactional audit outbox. It contains no material or material-derived fingerprints. Protected Secrets store immutable candidate/version bundles, linked to record UID and random version ID. Canonical generated versions live with the platform records; native adapter copies and SecretRef inputs live in the consumer's tenant namespace. Cross-namespace relationships use explicit UID mappings and controller finalization, never invalid cross-namespace owner references. The controller creates a candidate once before any engine mutation; recovery reuses it. Losing material while its record survives is `MaterialMissing`, not evidence of a fresh install.
11+
The credential record holds policy revision, active and candidate version IDs, operation ordering, collection state, and a bounded transactional audit outbox. It contains no material or material-derived fingerprints. Protected Secrets store immutable candidate/version bundles, linked to record UID and random version ID. Canonical generated versions live with the platform records; native adapter copies and SecretRef inputs live in the consumer's tenant namespace. Cross-namespace relationships use explicit UID mappings and controller finalization, never invalid cross-namespace owner references. Finalizers are placed only on platform-side records, never on the tenant namespace, its Secrets, or the application release, so an unavailable controller cannot block tenant deletion. The controller creates a candidate once before any engine mutation; recovery reuses it. Losing material while its record survives is `MaterialMissing`, not evidence of a fresh install.
1212

1313
For an operator that requires a stable Secret name, the controller maintains a private adapter Secret with the exact required layout. Existing `<release>-credentials` names may remain internal compatibility destinations after handoff; they are not the public credential identity. Their `data` has one writer. New grants target an account record and explicit fields, never all keys of that bundle. Maintenance credentials are separated from tenant-user records and eventually from legacy mixed bundles.
1414

@@ -337,7 +337,7 @@ Data restore runs into an isolated destination incarnation with fresh generated
337337

338338
MariaDB **logical** restore bootstraps destination maintenance credentials first, imports application data without restoring privilege tables, and reconciles destination users. Verify the actual dump/import behavior for the supported backup implementation. MariaDB **physical** restore and foreign datadir import are initially unsupported: they may restore historical maintenance authority, which cannot be inferred from the source's current Secret. Reject them before starting a destination, unless a later adapter supplies explicit historical recovery authority and proves its isolation. External backup access and decryption material enter through private inputs; they do not authorize disclosure of source credentials.
339339

340-
Deleting an app drains/fences pending executors, revokes or removes platform-managed engine accounts, and then removes its controller-owned material. Issuer outages leave visible finalization failures. An operator may deliberately orphan a service through a separate administrative procedure, which records outstanding accounts and copies rather than calling them revoked. Shared supplier inputs and audit history survive app deletion. Namespace deletion cannot erase the platform-side lifecycle records before this cleanup is resolved. Existing-account import under strict policy preserves data and grants but requires replacement with generated material; retaining a chosen password is unsupported.
340+
Deleting an app drains/fences pending executors, revokes or removes platform-managed engine accounts, and then removes its controller-owned material. Issuer outages leave visible finalization failures. An operator may deliberately orphan a service through a separate administrative procedure, which records outstanding accounts and copies rather than calling them revoked. Shared supplier inputs and audit history survive app deletion. Namespace deletion cannot erase the platform-side lifecycle records before this cleanup is resolved. A forced namespace deletion is not blocked: the surviving records are resolved by their bound UID through this same cleanup, and their material is not read as a fresh install. Existing-account import under strict policy preserves data and grants but requires replacement with generated material; retaining a chosen password is unsupported.
341341

342342
The one-time and revocation guarantees survive ordinary restarts and supported upgrades preserving the credential records. They do **not** automatically survive restoration of an old control-plane snapshot, which cannot contain later consumption or revocation decisions. Whole-platform recovery is an explicit offline procedure: isolate engines and tenant API access, invalidate collection for all restored versions, establish a fresh recovery epoch, and regenerate managed credentials before reopening strict service. Unsupported issuer/engine recovery blocks that account. Reconcile source identity, policy, and subscription grants before delivery resumes. The procedure must run before serving restored records; an independently restored old snapshot brought online without this barrier is outside the guarantee. Strong automatic anti-rollback against an unannounced storage rollback would require a durable authority outside that backup domain and is deferred.
343343

0 commit comments

Comments
 (0)