search

artifacthub / hub

Find, install and publish Cloud Native packages
https://artifacthub.io
Apache License 2.0
1.68k stars 229 forks source link

Add support for Headlamp plugins #3575

Closed joaquimrocha closed 9 months ago

joaquimrocha commented 9 months ago

Headlamp is a Kubernetes UI that is extensible via plugins. Currently there is no easy way for users to discover plugins and we think that ArtifactHub can be that place, just like it's the source we use for listing Helm charts at the moment.

Headlamp plugins are Javascript bundles as packed by npm. So in the end we need a URL to that NPM package tarball, so we download and extract it to the right location. At the moment, Headlamp itself ships with a couple of plugins officially, and the respective tarballs are just hosted as assets in a Github releases page (headlamp-k8s/plugins).

I have looked into ArtifactHub's package formats and the Package or PackageBase looks like covering most of what we need in terms of info, I am just not sure what would be the right member to represent that URL to the tarball + checksum if we need it.

Is this interesting for ArtifactHub? Any questions, please let me know.

tegioz commented 9 months ago

Hi @joaquimrocha 👋

Headlamp plugins would be a nice addition to Artifact Hub 🙂

Let me explain a bit how Artifact Hub indexes content.

Any organization or user can add repositories of any kind to Artifact Hub. At the moment we support several repositories kinds, like Helm charts, OLM operators, etc. The tracker component polls them periodically and collects metadata as needed. Depending on the repository kind, metadata is extracted one way or another. For kinds that have already defined how a repository should be structured and served, like Helm charts or OLM operators, we have specialized tracker sources. This allowed publishers to start adding existing repositories without requiring any additional work. For other kinds, we have a generic tracker source based on our own metadata file. To keep AH as simple to maintain and extend as possible, we are trying to push this tracker as the recommended way to go whenever possible (most artifacts kinds supported use it actually). In this particular case, it could be a great fit.

The generic tracker relies on a custom metadata file and a flexible directory structure that supports one or more packages per repository, including multiple versions per package if needed. Data unique to the artifact kind can be added in the form on custom annotations.

Some examples of how other projects organize the Artifact Hub metadata for their artifacts (they can be quite helpful for inspiration😇):

If this sounds good to you we'd be happy to proceed and start working on this 🙂

Please let us know if you have any questions!

joaquimrocha commented 9 months ago

Thank you for your reply @tegioz . So IIUC, you recommend that we go with the generic tracker related metadata file. For the npm tarball URL, do you recommend we use a custom annotation? headlamp/plugin/archive for example?

BTW, do annotations get special cased somehow in the Hub's details for a package? (just thinking it may be important to show where the actual plugin's archive lives)

tegioz commented 9 months ago

No worries!

So IIUC, you recommend that we go with the generic tracker related metadata file.

Yes, that's right 👍

For the npm tarball URL, do you recommend we use a custom annotation? headlamp/plugin/archive for example?

I think that'd probably be the best, yes. Alternatively, we could also do it using a link entry with a special name, or even derive it based on some convention, if this is possible at all. But IMHO the custom annotation way looks more solid. We could add some validation to enforce that that annotation is provided.

We can use this archive url to provide some default installation instructions for Headlamp plugins if you'd like (they can always be manually overriden from the metadata file).

BTW, do annotations get special cased somehow in the Hub's details for a package? (just thinking it may be important to show where the actual plugin's archive lives)

Sure, we can display that information in a special way, that's not a problem 🙂

joaquimrocha commented 9 months ago

Hi @tegioz !

I have talked to the Headlamp team and we agreed we need more than just one annotation. Here's what we arrived at: URL for the tarball: headlamp/plugin/archive-url , e.g. "https://.../my-archive.tar.gz" Checksum for the tarball: headlamp/plugin/archive-checksum, e.g. "sha256:MY_CHECKSUM" Headlamp compatibility (optional): headlamp/plugin/version-compat , e.g. ">=1.2.3" Headlamp flavor (optional): headlamp/plugin/distro-compat , e.g. one or more of app, in-cluster, web, docker-desktop, linux, windows, mac

Sergio, we would appreciate your advice on these. Do these look good to you? We also believe having these present in the details view of the package in ArtifactHub would be useful for users browsing them.

Also, we expect to add more distribution formats for plugins, e.g. instead of plain tarballs, have plugins be pushed to an npm repository. So I'd like to ask if updating this spec to extend it with new annotations is something trivial or whether we should include as much as we can at this initial point.

Thanks again for your support!

tegioz commented 9 months ago

Hi @joaquimrocha!

The annotations look great and it's ok to add as many as you need. We can display that information on the right column of the package details view, no problem.

We can add more annotations anytime, there's no need to try to include now as many as possible. When AH processes a Headlamp plugins repository, we'll store all these annotations per plugin/version. Except for any Headlamp specific validation we may add (i.e. annotation X is required), all this information will be processed -and later exposed by the HTTP API- in a generic way. On the UI, when we display a package of kind Headlamp plugin, those annotations will have a special meaning (i.e. to display some additional information on the right column). So adding more at any time is fine. However, it's important that once we start using them for a specific purpose, we stick to it.

No worries, happy to help 🙂

joaquimrocha commented 9 months ago

That makes sense. From our side, we're happy to proceed this way. Thanks @tegioz .

tegioz commented 9 months ago

This is ready @joaquimrocha 🙂

You can see it in action in the staging environment, we'll deploy it to production soon.

https://staging.artifacthub.io/packages/search?kind=21 https://staging.artifacthub.io/docs/topics/repositories/headlamp-plugins/ https://staging.artifacthub.io/docs/topics/annotations/headlamp/ https://github.com/tegioz/headlamp/tree/main/plugins/examples

Feel free to experiment with your own repositories if you'd like 😉

Closed by #3594

headlamp1 headlamp2
joaquimrocha commented 9 months ago

Wow, that was fast! Thanks a lot @tegioz . I will play with it.

tegioz commented 9 months ago

Deployed to production! You can now add Headlamp plugins repositories on https://artifacthub.io.