docs(design-proposals): add community package index and cozypkg authoring workflow#12
docs(design-proposals): add community package index and cozypkg authoring workflow#12Andrei Kvapil (kvaps) wants to merge 1 commit into
Conversation
Add a design proposal for a community package ecosystem built on the existing PackageSource/Package/OCI machinery: cozypkg tap/init/push plus a metadata-only community index for publishing, discovering, and installing third-party packages over OCI. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a design proposal for a Community Package Index and cozypkg authoring workflow, extending Cozystack's packaging stack to support third-party package publishing, discovery, and installation. The review feedback highlights several critical areas for improvement in the proposal, including addressing authentication for private OCI registries, resolving package name collisions across different tapped sources, clarifying CLI authentication for automated PR creation, and correcting the assumption that installed packages remain unaffected when a tap is removed.
|
|
||
| ### 2. `tap` = registering an external `PackageSource` | ||
|
|
||
| `cozypkg tap oci://ghcr.io/<org>/<repo>[:tag]` creates a cluster-scoped `PackageSource` (and the underlying Flux `OCIRepository`) pointing at the external artifact. It mirrors `brew tap`: it only adds a source, nothing is installed until `cozypkg add`. `cozypkg untap <name>` removes it. |
There was a problem hiding this comment.
The proposal does not specify how authentication and pull secrets will be handled for private OCI registries when using cozypkg tap. Since Flux OCIRepository supports secretRef for credentials, cozypkg tap should ideally support a way to associate pull secrets (e.g., via a --secret-ref flag or automatic secret creation/detection) to allow tapping private or enterprise community registries.
| # variants, dependencies, components come from the artifact itself | ||
| ``` | ||
|
|
||
| Because `PackageSource` already supports `OCIRepository`/`GitRepository`, `tap` is mostly UX sugar plus naming conventions and safety: community `PackageSource`s are namespaced (e.g. a `community.` prefix) so a third-party package can never silently shadow an official package name. |
There was a problem hiding this comment.
While namespacing the PackageSource (e.g., community.<org>.<repo>) prevents collisions at the PackageSource resource level, it doesn't address how cozypkg add will handle name collisions of the actual packages within different tapped sources. If two tapped sources both define a package named mariadb, running cozypkg add mariadb could be ambiguous. It would be helpful to define a syntax for referencing packages from specific taps (e.g., cozypkg add <tap-name>/<package-name>) to resolve such ambiguities.
|
|
||
| ### 5. `cozypkg push` | ||
|
|
||
| Packages the local directory and pushes it to the target OCI registry, then optionally opens or updates a PR against the index. Before publishing it validates the manifest (lint + schema check, reusing `cozyvalues-gen`/OpenAPI tooling) so broken packages do not reach a registry. |
There was a problem hiding this comment.
Automating the creation or update of a pull request against the community index repository (cozystack/packages-index) from a local CLI tool (cozypkg push) introduces complexity around GitHub authentication, forking, and API usage. It would be beneficial to clarify how cozypkg will handle these requirements (e.g., requiring a GitHub token, leveraging the gh CLI if available, or simply generating the metadata file for the user to manually submit).
|
|
||
| ## Upgrade and rollback compatibility | ||
|
|
||
| Purely additive. Existing `PackageSource`/`Package` resources are untouched, and the official "core" source keeps working. Removing a tap removes only its `PackageSource`; already-installed `Package`s are unaffected unless explicitly deleted. No migration is required. Rollback means dropping the new subcommands — cluster state is defined by the same CRDs and stays valid. |
There was a problem hiding this comment.
The statement that 'already-installed Packages are unaffected' when removing a tap might not be entirely accurate. Since the Package controller relies on the PackageSource to resolve variants, dependencies, and components to generate the underlying HelmRelease, deleting the PackageSource (via untap) will likely break the reconciliation loop of any active Packages referencing it. It would be safer to block or strongly warn against untap if there are active Package resources depending on that PackageSource, rather than assuming they remain unaffected.
1 participant
Adds a design proposal for a community package ecosystem on top of the existing
PackageSource/Package/OCI machinery.It introduces
cozypkg tap/init/pushplus a metadata-only community index, so third-party packages can be published over OCI, discovered, and installed the same way official packages are — analogous to Homebrew taps, Cargo, or Nix flakes. Artifacts stay in ordinary OCI registries; no new hosted registry is operated.The proposal is purely additive: the official package source keeps working as the "core tap", and existing
PackageSource/Packageresources are untouched.Proposal:
design-proposals/community-package-index/README.mdOpening as a draft for community feedback.