Add support for Headlamp plugins (#3594)

Signed-off-by: Sergio Castaño Arteaga <[email protected]> Signed-off-by: Cintia Sanchez Garcia <[email protected]> Co-authored-by: Sergio Castaño Arteaga <[email protected]> Co-authored-by: Cintia Sanchez Garcia <[email protected]>
artifacthub · Jan 10, 2024 · 7a2e090 · 7a2e090
1 parent 38071dc
commit 7a2e090
Show file tree

Hide file tree

Showing 54 changed files with 676 additions and 68 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -59,7 +59,7 @@ updates:
       interval: "weekly"
     ignore:
       - dependency-name: "node"
-        versions: ["19-alpine3.19", "20-alpine3.19"]
+        versions: ["19-alpine3.19", "20-alpine3.19", "21-alpine3.19"]
 
   - package-ecosystem: "docker"
     directory: "/cmd/scanner"

diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ At the moment, the following artifacts kinds are supported *(with plans to suppo
 - [CoreDNS plugins](https://coredns.io/)
 - [Falco configurations](https://falco.org/)
 - [Gatekeeper policies](https://open-policy-agent.github.io/gatekeeper/website/docs/)
+- [Headlamp plugins](https://headlamp.dev)
 - [Helm charts](https://helm.sh/)
 - [Helm plugins](https://helm.sh/docs/topics/plugins/)
 - [KCL modules](https://kcl-lang.io)

diff --git a/charts/artifact-hub/Chart.yaml b/charts/artifact-hub/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: artifact-hub
 description: Artifact Hub is a web-based application that enables finding, installing, and publishing Kubernetes packages.
 type: application
-version: 1.16.1-4
+version: 1.16.1-5
 appVersion: 1.16.0
 kubeVersion: ">= 1.19.0-0"
 home: https://artifacthub.io
@@ -28,6 +28,7 @@ keywords:
   - argo
   - kubearmor
   - kcl
+  - headlamp
 maintainers:
   - name: Sergio
     email: [email protected]

diff --git a/charts/artifact-hub/values.schema.json b/charts/artifact-hub/values.schema.json
@@ -1162,7 +1162,7 @@
                 },
                 "repositoriesKinds": {
                     "title": "Repositories kinds to process ([] = all)",
-                    "description": "The following kinds are supported at the moment: falco, helm, olm, opa, tbaction, krew, helm-plugin, tekton-task, keda-scaler, coredns, keptn, tekton-pipeline, container, kubewarden, gatekeeper, kyverno, knative-client-plugin, backstage, argo-template, kubearmor, kcl",
+                    "description": "The following kinds are supported at the moment: falco, helm, olm, opa, tbaction, krew, helm-plugin, tekton-task, keda-scaler, coredns, keptn, tekton-pipeline, container, kubewarden, gatekeeper, kyverno, knative-client-plugin, backstage, argo-template, kubearmor, kcl, headlamp",
                     "type": "array",
                     "items": {
                         "type": "string"

diff --git a/cmd/ah/lint.go b/cmd/ah/lint.go
@@ -90,7 +90,7 @@ func newLintCmd() *cobra.Command {
 			return lint(opts, &output{cmd.OutOrStdout()})
 		},
 	}
-	lintCmd.Flags().StringVarP(&opts.kind, "kind", "k", "helm", "repository kind: argo-template, backstage, coredns, falco, gatekeeper, helm, helm-plugin, kcl, keda-scaler, keptn, knative-client-plugin, krew, kubearmor, kubewarden, kyverno, olm, opa, tbaction, tekton-task, tekton-pipeline")
+	lintCmd.Flags().StringVarP(&opts.kind, "kind", "k", "helm", "repository kind: argo-template, backstage, coredns, falco, gatekeeper, headlamp, helm, helm-plugin, kcl, keda-scaler, keptn, knative-client-plugin, krew, kubearmor, kubewarden, kyverno, olm, opa, tbaction, tekton-task, tekton-pipeline")
 	lintCmd.Flags().StringVarP(&opts.path, "path", "p", ".", "repository's packages path")
 	return lintCmd
 }
@@ -114,6 +114,7 @@ func lint(opts *lintOptions, out *output) error {
 		hub.CoreDNS,
 		hub.Falco,
 		hub.Gatekeeper,
+		hub.Headlamp,
 		hub.KCL,
 		hub.KedaScaler,
 		hub.Keptn,
@@ -617,6 +618,7 @@ func (out *output) printPkgDetails(pkg *hub.Package) {
 		hub.CoreDNS,
 		hub.Falco,
 		hub.Gatekeeper,
+		hub.Headlamp,
 		hub.KCL,
 		hub.KedaScaler,
 		hub.Keptn,

diff --git a/database/migrations/schema/053_headlamp_plugins.sql b/database/migrations/schema/053_headlamp_plugins.sql
@@ -0,0 +1,5 @@
+insert into repository_kind values (21, 'Headlamp plugins');
+
+---- create above / drop below ----
+
+delete from repository_kind where repository_kind_id = 21;
diff --git a/database/tests/schema/schema.sql b/database/tests/schema/schema.sql
@@ -560,7 +560,8 @@ select results_eq(
         (17, 'Backstage plugins'),
         (18, 'Argo templates'),
         (19, 'KubeArmor policies'),
-        (20, 'KCL modules')
+        (20, 'KCL modules'),
+        (21, 'Headlamp plugins')
     $$,
     'Repository kinds should exist'
 );

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
@@ -1299,6 +1299,30 @@ paths:
           $ref: "#/components/responses/TooManyRequests"
         "500":
           $ref: "#/components/responses/InternalServerError"
+  "/packages/headlamp/{repoName}/{packageName}":
+    get:
+      tags:
+        - Packages
+      summary: Get package details
+      description: Get package details
+      operationId: getHeadlampPluginDetails
+      parameters:
+        - $ref: "#/components/parameters/RepoNameParam"
+        - $ref: "#/components/parameters/PackageNameParam"
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HeadlampPluginPackage"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
   "/packages/kcl/{repoName}/{packageName}":
     get:
       tags:
@@ -1790,7 +1814,31 @@ paths:
           $ref: "#/components/responses/TooManyRequests"
         "500":
           $ref: "#/components/responses/InternalServerError"
-  "/packages/KCL/{repoName}/{packageName}/{version}":
+  "/packages/headlamp/{repoName}/{packageName}/{version}":
+    get:
+      tags:
+        - Packages
+      summary: Get package version details
+      description: Get package version details
+      operationId: getHeadlampVersionDetails
+      parameters:
+        - $ref: "#/components/parameters/RepoNameParam"
+        - $ref: "#/components/parameters/PackageNameParam"
+        - $ref: "#/components/parameters/VersionParam"
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HeadlampPluginPackage"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/packages/kcl/{repoName}/{packageName}/{version}":
     get:
       tags:
         - Packages
@@ -3967,6 +4015,27 @@ components:
                         example: "http://repo.url"
     HelmPluginPackage:
       $ref: "#/components/schemas/Package"
+    HeadlampPluginPackage:
+      allOf:
+        - $ref: "#/components/schemas/Package"
+        - type: object
+          properties:
+            data:
+              type: object
+              nullable: false
+              properties:
+                headlamp/plugin/archive-url:
+                  type: string
+                  example: "https://headlamp.dev/sample-plugin-url"
+                headlamp/plugin/distro-compat:
+                  type: string
+                  example: "in-cluster,web,docker-desktop"
+                headlamp/plugin/version-compat:
+                  type: string
+                  example: ">=1.2.3"
+                headlamp/plugin/archive-checksum:
+                  type: string
+                  example: "sha256:123456..."
     KCLPackage:
       $ref: "#/components/schemas/Package"
     KedaScalerPackage:
@@ -4689,6 +4758,7 @@ components:
         - 18
         - 19
         - 20
+        - 21
       description: |
         Repository kind:
           * `0` - Helm charts
@@ -4712,6 +4782,7 @@ components:
           * `18` - Argo templates
           * `19` - KubeArmor templates
           * `20` - KCL packages
+          * `21` - Headlamp plugins
     RepositoryKindParam:
       type: string
       enum:
@@ -4736,6 +4807,7 @@ components:
         - argo-template
         - kubearmor
         - kcl
+        - headlamp
       description: |
         Repository kind name:
         * `helm` - Helm charts
@@ -4759,6 +4831,7 @@ components:
         * `argo-template` - Argo templates
         * `kubearmor` - KubeArmor policies
         * `kcl` - KCL packages
+        * `headlamp` - Headlamp plugins
     RepositorySummary:
       type: object
       required:
@@ -5299,6 +5372,7 @@ components:
           * `18` - Argo templates
           * `19` - KubeArmor templates
           * `20` - KCL packages
+          * `21` - Headlamp plugins
     PackageNameParam:
       in: path
       name: packageName

diff --git a/docs/headlamp_annotations.md b/docs/headlamp_annotations.md
@@ -0,0 +1,32 @@
+# Headlamp annotations
+
+You can provide some extra information about your Headlamp plugins by using the `annotations` field in the [Artifact Hub package metadata file](https://github.com/artifacthub/hub/blob/master/docs/metadata/artifacthub-pkg.yml).
+
+## Supported annotations
+
+- **headlamp/plugin/archive-url** *(string, required)*
+
+Plugin archive tarball URL (e.g. "https://.../my-archive.tar.gz").
+
+- **headlamp/plugin/archive-checksum** *(string, required)*
+
+Plugin archive tarball checksum (e.g. "sha256:MY_CHECKSUM").
+
+- **headlamp/plugin/version-compat** *(string, optional)*
+
+Headlamp versions this plugin is compatible with (e.g. ">=1.2.3").
+
+- **headlamp/plugin/distro-compat** *(string, optional)*
+
+Headlamp flavor this plugin is compatible with (e.g. one or more of app, in-cluster, web, docker-desktop, linux, windows, mac).
+
+## Example
+
+```yaml
+...
+annotations:
+  headlamp/plugin/archive-url: "https://.../my-archive.tar.gz"
+  headlamp/plugin/archive-checksum: "sha256:MY_CHECKSUM"
+  headlamp/plugin/version-compat: ">=1.2.3"
+  headlamp/plugin/distro-compat: "in-cluster,web,docker-desktop"
+```
diff --git a/docs/headlamp_plugins_repositories.md b/docs/headlamp_plugins_repositories.md
@@ -0,0 +1,49 @@
+## Headlamp plugins repositories
+
+Headlamp plugins repositories are expected to be hosted in GitHub, GitLab or Bitbucket repos. When adding your repository to Artifact Hub, the url used **must** follow the following format:
+
+- `https://github.com/user/repo[/path/to/packages]`
+- `https://gitlab.com/user/repo[/path/to/packages]`
+- `https://bitbucket.org/user/repo[/path/to/packages]`
+
+By default the `master` branch is used, but it's possible to specify a different one from the UI.
+
+*Please NOTE that the repository URL used when adding the repository to Artifact Hub **must NOT** contain the git hosting platform specific parts, like **tree/branch**, just the path to your packages like it would show in the filesystem.*
+
+The *path/to/packages* provided can contain metadata for one or more packages. Each package version **must** be on a separate folder, and it's up to you to decide if you want to publish one or multiple versions of your package.
+
+The structure of a repository with multiple plugins packages and versions could look something like this:
+
+```sh
+$ tree path/to/packages
+path/to/packages
+├── artifacthub-repo.yml
+├── package1
+│   ├── 1.0.0
+│   │   ├── README.md
+│   │   └── artifacthub-pkg.yml
+│   └── 2.0.0
+│       ├── README.md
+│       └── artifacthub-pkg.yml
+└── package2
+    └── 1.0.0
+        ├── README.md
+        └── artifacthub-pkg.yml
+```
+
+This structure is flexible, and in some cases where you only have a package and a version it can be greatly simplified. In the case of a single package with a single version available at a time (the publisher doesn't want to make previous ones available, for example), the structure could look like this:
+
+```sh
+$ tree path/to/packages
+path/to/packages
+├── artifacthub-repo.yml
+└── package1
+    ├── README.md
+    └── artifacthub-pkg.yml
+```
+
+In the previous case, even the `package1` directory could be omitted. The reason is that both packages names and versions are read from the `artifacthub-pkg.yml` metadata file, so directories names are not used at all.
+
+Each package version **needs** an `artifacthub-pkg.yml` metadata file. Please see the file [spec](https://github.com/artifacthub/hub/blob/master/docs/metadata/artifacthub-pkg.yml) and the [Headlamp annotations documentation](https://github.com/artifacthub/hub/blob/master/docs/headlamp_annotations.md) for more details. The [artifacthub-repo.yml](https://github.com/artifacthub/hub/blob/master/docs/metadata/artifacthub-repo.yml) repository metadata file shown above can be used to setup features like [Verified publisher](https://github.com/artifacthub/hub/blob/master/docs/repositories.md#verified-publisher) or [Ownership claim](https://github.com/artifacthub/hub/blob/master/docs/repositories.md#ownership-claim). This file must be located at `/path/to/packages`.
+
+Once you have added your repository, you are all set up. As you add new versions of your plugins packages or new packages to your git repository, they'll be automatically indexed and listed in Artifact Hub.
diff --git a/docs/repositories.md b/docs/repositories.md
@@ -9,6 +9,7 @@ The following repositories kinds are supported at the moment:
 - [Containers images repositories](https://github.com/artifacthub/hub/blob/master/docs/container_images_repositories.md)
 - [CoreDNS plugins repositories](https://github.com/artifacthub/hub/blob/master/docs/coredns_plugins_repositories.md)
 - [Falco rules repositories](https://github.com/artifacthub/hub/blob/master/docs/falco_rules_repositories.md)
+- [Headlamp plugins repositories](https://github.com/artifacthub/hub/blob/master/docs/headlamp_plugins_repositories.md)
 - [Helm charts repositories](https://github.com/artifacthub/hub/blob/master/docs/helm_charts_repositories.md)
 - [Helm plugins repositories](https://github.com/artifacthub/hub/blob/master/docs/helm_plugins_repositories.md)
 - [KCL modules repositories](https://github.com/artifacthub/hub/blob/master/docs/kcl_modules_repositories.md)

diff --git a/docs/www/content/_index.md b/docs/www/content/_index.md
@@ -13,14 +13,15 @@ The documentation is organized in the following topics:
 | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [Repositories guide](/docs/topics/repositories)               | The repositories guide explains how to add repositories to Artifact Hub, as well as other related concepts like Verified publisher or Ownership Claim.  |
 | [Argo annotations](/docs/topics/annotations/argo)             | Describes some custom annotations that allow enriching the existing metadata in Argo templates to improve users' experience in Artifact Hub.            |
+| [Headlamp annotations](/docs/topics/annotations/headlamp)     | Describes some custom annotations that allow enriching the existing metadata in Headlamp plugins to improve users' experience in Artifact Hub.          |
 | [Helm annotations](/docs/topics/annotations/helm)             | Describes some custom annotations that allow enriching the existing metadata in Helm Charts to improve users' experience in Artifact Hub.               |
 | [Keptn annotations](/docs/topics/annotations/keptn)           | Describes some custom annotations that allow enriching the existing metadata in Keptn integrations to improve users' experience in Artifact Hub.        |
 | [Krew annotations](/docs/topics/annotations/krew)             | Describes some custom annotations that allow enriching the existing metadata in Krew kubectl plugins to improve users' experience in Artifact Hub.      |
 | [Kubewarden annotations](/docs/topics/annotations/kubewarden) | Describes some custom annotations that allow enriching the existing metadata in Kubewarden policies to improve users' experience in Artifact Hub.       |
 | [Kyverno annotations](/docs/topics/annotations/kyverno)       | Describes some custom annotations that allow enriching the existing metadata in Kyverno policies to improve users' experience in Artifact Hub.          |
 | [OLM annotations](/docs/topics/annotations/olm)               | Describes some custom annotations that allow enriching the existing metadata in OLM operators to improve users' experience in Artifact Hub.             |
-| [Tekton annotations](/docs/topics/annotations/tekton)         | Describes some custom annotations that allow enriching the existing metadata in Tekton tasks to improve users' experience in Artifact Hub.
-| [Embedding artifacts](/docs/topics/embedding_artifacts)       | Explains how to embed a single artifact or a group of them in other websites.              |
+| [Tekton annotations](/docs/topics/annotations/tekton)         | Describes some custom annotations that allow enriching the existing metadata in Tekton tasks to improve users' experience in Artifact Hub.              |
+| [Embedding artifacts](/docs/topics/embedding_artifacts)       | Explains how to embed a single artifact or a group of them in other websites.                                                                           |
 | [Packages security report](/docs/topics/security_report)      | Explains how packages are scanned for security vulnerabilities and the structure of the security report.                                                |
 | [Authorization](/docs/topics/authorization)                   | Explains how the authorization mechanism that allows organizations to define what actions can be performed by their members works and how to set it up. |
 | [Architecture](/docs/topics/architecture)                     | Describes the components that form Artifact Hub, what each of them do and the layout of the source repository.                                          |

diff --git a/docs/www/headers/headlamp_annotations b/docs/www/headers/headlamp_annotations
@@ -0,0 +1,6 @@
+---
+title: "Headlamp"
+aliases: [
+  "/headlamp_annotations",
+]
+---
diff --git a/docs/www/headers/headlamp_plugins_repositories b/docs/www/headers/headlamp_plugins_repositories
@@ -0,0 +1,6 @@
+---
+title: "Headlamp plugins"
+aliases: [
+  "/headlamp_plugins_repositories",
+]
+---
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
@@ -265,7 +265,7 @@ func (h *Handlers) setupRouter() {
 			r.Get("/stats", h.Packages.GetStats)
 			r.With(corsMW).Get("/search", h.Packages.Search)
 			r.With(h.Users.RequireLogin).Get("/starred", h.Packages.GetStarredByUser)
-			r.Route("/{^helm$|^falco$|^opa$|^olm|^tbaction|^krew|^helm-plugin|^tekton-task|^keda-scaler|^coredns|^keptn|^tekton-pipeline|^container|^kubewarden|^gatekeeper|^kyverno|^knative-client-plugin|^backstage|^argo-template|^kubearmor|^kcl$}/{repoName}/{packageName}", func(r chi.Router) {
+			r.Route("/{^helm$|^falco$|^opa$|^olm|^tbaction|^krew|^helm-plugin|^tekton-task|^keda-scaler|^coredns|^keptn|^tekton-pipeline|^container|^kubewarden|^gatekeeper|^kyverno|^knative-client-plugin|^backstage|^argo-template|^kubearmor|^kcl|^headlamp$}/{repoName}/{packageName}", func(r chi.Router) {
 				r.Get("/feed/rss", h.Packages.RssFeed)
 				r.With(corsMW).Get("/summary", h.Packages.GetSummary)
 				r.Get("/{version}", h.Packages.Get)
@@ -430,7 +430,7 @@ func (h *Handlers) setupRouter() {
 
 	// Index special entry points
 	r.Route("/packages", func(r chi.Router) {
-		r.Route("/{^helm$|^falco$|^opa$|^olm|^tbaction|^krew|^helm-plugin|^tekton-task|^keda-scaler|^coredns|^keptn|^tekton-pipeline|^container|^kubewarden|^gatekeeper|^kyverno|^knative-client-plugin|^backstage|^argo-template|^kubearmor|^kcl$}/{repoName}/{packageName}", func(r chi.Router) {
+		r.Route("/{^helm$|^falco$|^opa$|^olm|^tbaction|^krew|^helm-plugin|^tekton-task|^keda-scaler|^coredns|^keptn|^tekton-pipeline|^container|^kubewarden|^gatekeeper|^kyverno|^knative-client-plugin|^backstage|^argo-template|^kubearmor|^kcl|^headlamp$}/{repoName}/{packageName}", func(r chi.Router) {
 			r.With(h.Packages.InjectIndexMeta).Get("/{version}", h.Static.Index)
 			r.With(h.Packages.InjectIndexMeta).Get("/", h.Static.Index)
 		})

diff --git a/internal/handlers/pkg/handlers_test.go b/internal/handlers/pkg/handlers_test.go
@@ -2155,6 +2155,17 @@ func TestBuildURL(t *testing.T) {
 			"2.0.0",
 			baseURL + "/packages/kcl/repo1/pkg1/2.0.0",
 		},
+		{
+			&hub.Package{
+				NormalizedName: "pkg1",
+				Repository: &hub.Repository{
+					Kind: hub.Headlamp,
+					Name: "repo1",
+				},
+			},
+			"2.0.0",
+			baseURL + "/packages/headlamp/repo1/pkg1/2.0.0",
+		},
 	}
 	for _, tc := range testCases {
 		tc := tc