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 d546598
Browse filesBrowse the repository at this point in the historyBrowse files
- Place tap Flux source and its Secret in cozy-system (alongside the
existing platform/External-Apps sources, per #2472), not a new
namespace; the community. prefix is a PackageSource name convention
and the install target namespace is set per PackageSource/Package.
- State the private-tap metadata-visibility threat model explicitly:
credentials stay protected but catalog metadata is cluster-wide
visible via open GET; add a visibility: private marker restricting
such entries to cluster-admin.
- Specify the orphaned-Package mechanism: no ownerReference from
Package to PackageSource (no GC cascade) plus a PackageSource
finalizer gating deletion; OrphanedSource computed from a dangling
sourceRef.
- Prefer secretRef (name of a pre-created Secret) on the tap API;
discourage raw inline credentials in the POST body.
Signed-off-by: IvanHunters <[email protected]>
Copy file name to clipboardExpand all lines: design-proposals/cozymarketplace-supplementary/README.md
+9-5Lines changed: 9 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -77,7 +77,7 @@ flowchart TB
77
77
cli -. "tap --secret" .-> ep
78
78
ep -->|"create / list / delete"| ps
79
79
ep -->|create when private| src
80
-
ep -->|create when inline creds| sec
80
+
ep -. "reference secretRef (admin pre-creates)" .-> sec
81
81
cache -. watch .-> src
82
82
cache -->|"parse PackageSource + ApplicationDefinition"| ep
83
83
ps --> ag --> hr
@@ -97,7 +97,7 @@ The dashboard reads marketplace state through a small set of endpoints layered i
97
97
|`GET`|`/marketplace/taps`| List connected taps with metadata, derived from `PackageSource` + `ApplicationDefinition`. |
98
98
|`GET`|`/marketplace/taps/{name}/packages`| Packages exposed by one tap. |
99
99
|`GET`|`/marketplace/search?q=<query>`| Search across all taps by name, tag, description. |
100
-
|`POST`|`/marketplace/taps`| Connect a tap: creates the Flux source (with `spec.secretRef`when a Secret is supplied), the `Secret` when inline credentials are given, and the `PackageSource` — the same resources `cozypkg tap` creates. |
100
+
|`POST`|`/marketplace/taps`| Connect a tap: creates the Flux source (with `spec.secretRef`referencing a `Secret` the admin pre-created in `cozy-system`, when private) and the `PackageSource` — the same resources `cozypkg tap` creates. The body carries a `secretRef` (Secret name), not raw credentials (see Security). |
101
101
|`DELETE`|`/marketplace/taps/{name}`| Disconnect a tap; mirrors `cozypkg untap`. Lifecycle of installed `Package` CRs follows `#12` (see below). |
102
102
103
103
A `TapIndex` cache controller in the same binary watches each tap's Flux source `status.artifact.revision`, pulls the assembled artifact on each revision change, parses the `PackageSource` + `ApplicationDefinition`s it carries, and serves the GET endpoints from memory. Without it, every search would hit OCI per request. Cluster-admin is required for `POST` and `DELETE`, matching both the cluster-scoped `PackageSource` model and `#12`'s "tap requires cluster-admin". `GET` returns catalog metadata only and is open to any authenticated user so tenant-admins can browse; it never returns Secret names or contents (see Security).
@@ -107,7 +107,7 @@ A `TapIndex` cache controller in the same binary watches each tap's Flux source
107
107
`cozypkg tap` and the `POST /marketplace/taps` endpoint already create the Flux source, so threading credentials is a change to that creation step, not to any CRD:
108
108
109
109
-`cozypkg tap <oci-ref> --secret <name>` (and a `secretRef` field on the POST body) sets `spec.secretRef` on the `OCIRepository`/`GitRepository` it creates.
110
-
- The Secret lives in the same namespace as that Flux source. Community taps place both the Flux source and its pull Secret in a single fixed, dotless namespace, `cozy-community`; the `community.` prefix stays only on the cluster-scoped `PackageSource` name (`community.<org>.<repo>`, per `#12`), for collision-avoidance. A namespace cannot carry that prefix: `PackageSource` is cluster-scoped and has no namespace of its own, and namespace names are RFC 1123 labels that forbid dots. Both the `POST /marketplace/taps` handler and `cozypkg tap --secret` create the Secret in `cozy-community`, so they agree on one place. Flux source-controller resolves `secretRef` in the source's own namespace, so there is no cross-namespace lookup to special-case.
110
+
- The Secret lives in the same namespace as that Flux source. Community taps place both the Flux source and its pull Secret in `cozy-system`, alongside the existing platform and External-Apps Flux sources (and where `#2472` already puts the platform source's Secret), rather than introducing a new namespace. The `community.` prefix stays only on the cluster-scoped `PackageSource` name (`community.<org>.<repo>`, per `#12`), for collision-avoidance: it is a name convention, not a namespace — `PackageSource` is cluster-scoped, and namespace names are RFC 1123 labels that forbid dots anyway. The namespace a package installs *into* is set per-`PackageSource`/`Package`, independent of where the tap's source and Secret live. Both the `POST /marketplace/taps` handler and `cozypkg tap --secret` create the source in `cozy-system` and reference a Secret there, so they agree on one place, and Flux source-controller resolves `secretRef` in that same namespace with no cross-namespace lookup to special-case.
111
111
- Secret format depends on source kind, matching what Flux source-controller documents and what `#2472` already wired for the platform source: `kubernetes.io/dockerconfigjson` for OCI; Opaque with `username`+`password` or `bearerToken` for Git over HTTPS; Opaque with `identity` (PEM private key) and `known_hosts` for Git over SSH.
112
112
113
113
This is exactly symmetric with `cozystack/cozystack#2472` (merged): that change made the operator set `spec.secretRef` on the platform source it generates; this makes `cozypkg tap` / the backend do the same for every user-tapped repository. No field is added to `PackageSourceRef`: it is a by-name reference to an already-created source, and the `PackageSource` reconciler only reads it to build the `ArtifactGenerator` — it never creates the Flux source, so a `secretRef` on the ref would have no reconcile path. Because nothing on the CRD changes, no migration is needed.
@@ -165,13 +165,17 @@ Privileged components are surfaced both at validation time (the CI workflow emit
165
165
166
166
Credentials never live on a CR field: the `secretRef` set at tap time names a `Secret` consumed by Flux source-controller under its existing RBAC; `cozypkg` and the backend never read or log the credential. The `GET` endpoints return catalog metadata only — package names, tags, descriptions, privileged badges — and never a Secret name, its contents, or the private source's credentials, so browsing cannot leak private-tap credentials across the tenant boundary.
167
167
168
+
The tap API takes a `secretRef` (the name of a `Secret` the admin pre-creates in `cozy-system`), not raw credentials in the request body. Accepting inline credentials over the API is discouraged: it would land secrets in request logs and API audit trails and force the server to persist them itself, whereas referencing a pre-created `Secret` keeps credential handling inside Flux's existing RBAC and the cluster's at-rest Secret encryption.
169
+
170
+
Metadata visibility is a boundary to state explicitly, because it is easy to over-read "credentials do not leak" as "a private tap is private". They are different claims. The pull credential stays protected, but the *catalog metadata* of a private tap — package names, tags, descriptions — is visible to every authenticated user through the open `GET /marketplace/*` endpoints, because taps are cluster-scoped. A cluster-admin tapping a private repository must therefore treat its package names and descriptions as visible cluster-wide; only the artifact contents behind the pull credential are protected. Where even that metadata is sensitive in a multi-tenant cluster, the tap carries a `visibility: private` marker on its `PackageSource` and the `GET` endpoints restrict those entries to cluster-admin. Recommended default for multi-tenant clusters: private taps are admin-only in the catalog, public taps stay world-readable.
171
+
168
172
## Failure and edge cases
169
173
170
174
`PackageSource` / `ApplicationDefinition` malformed inside the artifact → cache controller logs the parse error, marks the tap as `Degraded`, and returns the last-known-good payload. Operator sees a clear error in the dashboard.
171
175
172
176
Secret removed while still referenced → Flux surfaces the failed-pull condition on the source, which the marketplace endpoint forwards.
173
177
174
-
Tap removed while packages from it remain installed → handled per `#12`'s `cozypkg untap`: warn and require confirmation, reusing the reverse-dependency analysis from `cozypkg del`; already-installed `Package` resources are left in place until explicitly removed. The dashboard marks them`OrphanedSource` until the operator re-taps or removes them.
178
+
Tap removed while packages from it remain installed → handled per `#12`'s `cozypkg untap`: warn and require confirmation, reusing the reverse-dependency analysis from `cozypkg del`; already-installed `Package` resources are left in place until explicitly removed. Mechanically, installed `Package` CRs carry no `ownerReference` to the tap's `PackageSource`, so removing the tap never triggers Kubernetes garbage collection of the packages — orphaning is the default by construction, not an active step. A finalizer on the `PackageSource` lets the backend / `cozypkg untap` run the reverse-dependency check and surface the confirmation before the object is actually deleted. The dashboard computes the`OrphanedSource` state by detecting installed `Package`s whose `sourceRef` no longer resolves to a live `PackageSource`, and holds it until the operator re-taps or removes them.
175
179
176
180
`POST /marketplace/taps` with a `secretRef` pointing at a non-existent Secret → endpoint accepts the request (Flux can recover later when the Secret appears), and the dashboard shows the `Secret not found` condition sourced from Flux.
177
181
@@ -185,7 +189,7 @@ Independent PRs in cozystack, several landable in parallel. The `--secret` flag
185
189
186
190
## Open questions
187
191
188
-
Tap-remove lifecycle. `#12` already proposes warn-and-confirm reusing `cozypkg del` reverse-dependency analysis; this proposal adopts that and adds only the dashboard `OrphanedSource` marker. Whether disconnect should ever cascade-delete rather than orphan is left open. Default proposed: keep installed packages, mark orphaned.
192
+
Tap-remove lifecycle. Mechanism is specified (no `ownerReference` from `Package` to `PackageSource` so nothing cascades via garbage collection; a `PackageSource` finalizer gates deletion behind the `cozypkg del` reverse-dependency confirmation; `OrphanedSource` is computed from a dangling `sourceRef`). What remains open is policy, not mechanism: whether disconnect should ever offer an opt-in cascade-delete rather than always orphaning. Default proposed: keep installed packages, mark orphaned.
189
193
190
194
Endpoint hosting. Marketplace endpoints inside `cozystack-api` versus a new `cozystack-marketplace-controller`. Default proposed: extend `cozystack-api`.
0 commit comments