Skip to content

Commit 0e6e82d

Browse files
committed
docs(marketplace): update for the declared-name tap model
Tapped repositories keep their own declared PackageSource name instead of a community. prefix, and a clash with a core component is rejected at tap time. Drops the reserved-name note and the --allow-reserved-names flag, updates the CLI examples to declared names, and describes the collision behaviour and the label-based untap. Signed-off-by: IvanHunters <[email protected]>
1 parent 41b2236 commit 0e6e82d

4 files changed

Lines changed: 18 additions & 18 deletions

File tree

‎content/en/docs/next/marketplace/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ The lifecycle has two sides:
3333
| `Tap` | `core.cozystack.io/v1alpha1` | Virtual resource backing the dashboard "Repositories" view: connect, list, and disconnect repositories. |
3434
| `OCIRepository` | `source.toolkit.fluxcd.io/v1` | Flux source Cozystack creates for a connected repository's artifact. |
3535

36-
Repositories connected through the marketplace are always named under the `community.` prefix, so an external package can never shadow an official one.
36+
A connected repository keeps its own declared `PackageSource` name. If that name (or an application it registers) would collide with a core component, the connect is rejected, so an external package can never shadow an official one.
3737

3838
## Trust model
3939

‎content/en/docs/next/marketplace/connecting.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ cozypkg search database
3131

3232
## Connect from the CLI
3333

34-
`cozypkg tap` registers a published repository. It creates a Flux `OCIRepository` pointing at the artifact and materializes the `PackageSource` resources the artifact carries, named under the `community.` prefix so they cannot shadow official packages. Nothing is installed yet:
34+
`cozypkg tap` registers a published repository. It creates a Flux `OCIRepository` pointing at the artifact and materializes the `PackageSource` resources the artifact carries under their declared names. If a name (or an application it registers) would collide with a core component or another connected repository, the tap is rejected instead of overwriting it, so an external package cannot shadow an official one. Nothing is installed yet:
3535

3636
```bash
3737
cozypkg tap oci://ghcr.io/acme/hello:v1.0.0
@@ -61,14 +61,15 @@ cozypkg tap oci://ghcr.io/acme/hello:v1.0.0 --secret acme-pull
6161

6262
## Connect from the dashboard
6363

64-
The dashboard "Repositories" view is backed by the `Tap` resource and covers the same flow without the CLI. Open it from the sidebar, choose **Connect**, and provide the `oci://` reference and, for a private repository, the name of a pull-credential `Secret` in `cozy-system`. Connected repositories are listed with their status, and community repositories can be disconnected from the same view.
64+
The dashboard "Repositories" view is backed by the `Tap` resource and covers the same flow without the CLI. Open it from the sidebar, choose **Connect**, and provide the `oci://` reference and, for a private repository, the name of a pull-credential `Secret` in `cozy-system`. Connected repositories are listed with their status; a tapped repository still connecting or blocked by a name collision shows its message there, and tapped repositories can be disconnected from the same view.
6565

6666
## Install applications
6767

68-
Once a repository is connected, install an application from it with `cozypkg add`, naming the materialized `PackageSource`:
68+
Once a repository is connected, install an application from it with `cozypkg add`, naming the materialized `PackageSource`. A tapped repository keeps its own declared name, so run `cozypkg list` first to see the exact name to use:
6969

7070
```bash
71-
cozypkg add community.acme.hello
71+
cozypkg list
72+
cozypkg add acme.hello
7273
```
7374

7475
`cozypkg add` installs the `PackageSource` and its dependencies. If a component is privileged, it asks for confirmation first; pass `--allow-privileged` to install privileged components without the interactive prompt.
@@ -91,13 +92,13 @@ Disconnecting has two independent steps, mirroring the two connect steps.
9192
Remove installed applications with `cozypkg del`. This deletes the `Package` and its resources but leaves the connected source in place:
9293

9394
```bash
94-
cozypkg del community.acme.hello
95+
cozypkg del acme.hello
9596
```
9697

97-
Then remove the source itself with `cozypkg untap`. This deletes the `community.` `PackageSource` and its Flux source, and refuses official sources. Already-installed `Package` resources are left untouched, so untap warns if any remain; pass `--yes` to untap anyway:
98+
Then remove the source itself with `cozypkg untap`. This deletes the tapped `PackageSource` (identified by its marketplace-tap marker, not a name prefix) and its Flux source, and refuses official sources. Already-installed `Package` resources are left untouched, so untap warns if any remain; pass `--yes` to untap anyway:
9899

99100
```bash
100-
cozypkg untap community.acme.hello
101+
cozypkg untap acme.hello
101102
```
102103

103-
From the dashboard, disconnecting a community repository in the "Repositories" view removes the `PackageSource` and its Flux source in one step; it does not remove already-installed applications.
104+
From the dashboard, disconnecting a tapped repository in the "Repositories" view removes the `PackageSource` and its Flux source in one step; it does not remove already-installed applications.

‎content/en/docs/next/marketplace/cozypkg.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Scaffold a new repository built around the `PackageSource` model: a `PackageSour
2222
| Flag | Description |
2323
| --- | --- |
2424
| `--app <label>` | Name of the sample app/component, an RFC-1123 label (default `myapp`). |
25-
| `--name <name>` | `PackageSource` name (defaults to `example.<app>`). Reserved prefixes `cozystack.` and `community.` are rejected. |
25+
| `--name <name>` | `PackageSource` name (defaults to `example.<app>`). Any name is allowed; a clash with a core component is caught at tap time, not here. |
2626

2727
```bash
2828
cozypkg init --app hello --name acme.hello ./hello-repo
@@ -39,7 +39,6 @@ Validate a repository offline, the same way publication would, without installin
3939
| `--require-signature` | Require a valid keyless cosign signature on the OCI artifact (needs the `cosign` binary and an `oci://` reference). |
4040
| `--certificate-identity <id>` | Expected cosign certificate identity for `--require-signature`. |
4141
| `--certificate-oidc-issuer <url>` | Expected cosign certificate OIDC issuer for `--require-signature`. |
42-
| `--allow-reserved-names` | Permit reserved `PackageSource` name prefixes. The index gate never sets this. |
4342

4443
```bash
4544
cozypkg validate ./hello-repo --helm-lint
@@ -78,7 +77,7 @@ cozypkg search database --index oci://ghcr.io/cozystack/packages-index:latest
7877

7978
### `cozypkg tap <oci-ref>`
8079

81-
Register an external repository: create a Flux `OCIRepository` for the artifact and materialize the `PackageSource` resources it carries, named under the `community.` prefix. Nothing is installed until `cozypkg add`. Tapping is idempotent and validates the artifact's structure but does not verify its cosign signature.
80+
Register an external repository: create a Flux `OCIRepository` for the artifact and materialize the `PackageSource` resources it carries under their declared names. A name that collides with a core component (or another tap) is rejected rather than overwritten. Nothing is installed until `cozypkg add`. Tapping is idempotent and validates the artifact's structure but does not verify its cosign signature.
8281

8382
| Flag | Description |
8483
| --- | --- |
@@ -94,15 +93,15 @@ cozypkg tap oci://ghcr.io/acme/hello:v1.0.0
9493

9594
### `cozypkg untap <packagesource-name>`
9695

97-
Remove a community-tapped `PackageSource` and its Flux source. Only `community.*` sources can be untapped; official sources are refused. Already-installed `Package` resources are left untouched.
96+
Remove a tapped `PackageSource` and its Flux source. Only tapped sources (marked with the marketplace-tap label) can be untapped; official sources are refused. Already-installed `Package` resources are left untouched.
9897

9998
| Flag | Description |
10099
| --- | --- |
101100
| `--yes` | Untap even if a `Package` from this source is still installed. |
102101
| `--kubeconfig <path>` | Path to kubeconfig file. |
103102

104103
```bash
105-
cozypkg untap community.acme.hello
104+
cozypkg untap acme.hello
106105
```
107106

108107
## Installing and inspecting
@@ -118,7 +117,7 @@ Install a `PackageSource` and its dependencies interactively. Packages can be gi
118117
| `--kubeconfig <path>` | Path to kubeconfig file. |
119118

120119
```bash
121-
cozypkg add community.acme.hello
120+
cozypkg add acme.hello
122121
```
123122

124123
### `cozypkg del [package]...`
@@ -131,7 +130,7 @@ Delete `Package` resources. Packages can be given as arguments or read from file
131130
| `--kubeconfig <path>` | Path to kubeconfig file. |
132131

133132
```bash
134-
cozypkg del community.acme.hello
133+
cozypkg del acme.hello
135134
```
136135

137136
### `cozypkg list`

‎content/en/docs/next/marketplace/publishing.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ cozypkg init --app hello --name acme.hello ./hello-repo
2929

3030
{{% note %}}
3131

32-
A `PackageSource` name must not start with a reserved prefix (`cozystack.` or `community.`). `cozystack.` is the platform's own namespace, and `community.` is applied automatically when a repository is connected. `cozypkg init` and `cozypkg validate` both reject reserved names. Use a neutral prefix such as your organization name, for example `acme.hello`.
32+
A `PackageSource` name is yours to choose: there is no reserved prefix. A tapped repository keeps its declared name on the cluster, and a clash with a core component is caught when the repository is connected (see [Connecting a Repository]({{% ref "/docs/next/marketplace/connecting" %}})), not by `init`. Use your organization as a prefix, for example `acme.hello`, to keep the name distinctive.
3333

3434
{{% /note %}}
3535

@@ -76,7 +76,7 @@ spec:
7676
```
7777
7878
- `packages/apps/hello` is the application chart that templates the user-facing resources.
79-
- `packages/system/hello-rd` is a paired chart whose `cozyrds/` asset carries the `ApplicationDefinition` that registers the application in the API and dashboard. Its `chartRef` is templated so it keeps resolving after the source is renamed under the `community.` prefix at connect time.
79+
- `packages/system/hello-rd` is a paired chart whose `cozyrds/` asset carries the `ApplicationDefinition` that registers the application in the API and dashboard. Its `chartRef` names the app component's assembled artifact directly; because a connected repository keeps its declared name, the reference resolves without any tap-time rewriting.
8080

8181
Replace the placeholder chart in `packages/apps/hello/templates/` with your application's real resources, and add more components or variants to the `PackageSource` as needed.
8282

0 commit comments

Comments
 (0)