You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a381944
Browse filesBrowse the repository at this point in the historyBrowse 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]>
Copy file name to clipboardExpand all lines: design-proposals/user-secrets-api/details.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ Add a versioned API in `core.cozystack.io`, served by the aggregated API server.
8
8
9
9
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.
10
10
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.
12
12
13
13
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.
14
14
@@ -337,7 +337,7 @@ Data restore runs into an isolated destination incarnation with fresh generated
337
337
338
338
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.
339
339
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.
341
341
342
342
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.
0 commit comments