Publish policies to Artifact Hub
Artifact Hub is a website where users can find, install, and publish packages and configurations for CNCF projects.
Kubewarden policies can be published on Artifact Hub and made discoverable to the wide audience of CNCF users.
Artifact Hub is a content aggregation platform and doesn't actually host the artifacts that are published on it.
Artifact Hub requires you to physically host container image repositories on a container registry or a web server. Refer to the distributing policies section for more information on how to host your policies.
This document focuses on the steps required to make a Kubewarden policy discoverable on Artifact Hub.
Prepare your Git repository​
Artifact Hub crawls Git repositories looking for special metadata files.
There are different kind of layouts the Git repository can have. They are all documented in depth in the official Artifact Hub documentation.
Artifact Hub is pretty flexible and allows you to organize your code in these ways:
- Have a Git repository dedicated to Artifact Hub: this repository will not contain any policy source code. It will be a collection of the YAML files required by Artifact Hub.
- Add a Artifact Hub directory inside of the Git repository that holds the source of your policy. This is an iteration of the previous approach, the only difference is that it focuses just on one policy: the one defined inside of the Git repository. This approach allows to keep multiple versions of the policy published on Artifact Hub.
- Add the
artifacthub-pkg.yml
and theartifacthub-repo.yml
files to the root of the Git repository that holds the policy source code. This approach is the simplest one. The only limitation is that only the latest version of the policy will be visible on Artifact Hub.
The last approach is what we used inside of our official policy templates.
The Git repository that is scaffolded includes the artifacthub-pkg.yml
and artifacthub-repo.yml
files.
Publishing Steps​
Before publishing a policy to Artifact Hub, you must create an account on the website.
Before publishing the policy, ensure your Git repository has the proper layout.
The artifacthub-pkg.yml
contains fields such as version:
, createdAt:
,
that need to match specific format, and be up-to-date. The format of the
artifacthub-pkg.yml
is described
here.
If you created the policy using one of our templates, then you have a make artifacthub-pkg.yml
target. Execute that target to generate the
artifacthub-pkg.yml
file programmatically from metadata.yml
and other
inputs. This target gets called as part as a normal build of a policy, so
your task is to commit the resulting changes to artifacthub-pkg.yml
.
The policy templates make use of our GitHub Actions at github.com/kubewarden/github-actions:
- If you are using our GitHub Actions >=
v3.1.0
, the workflows provide by default automated checking of theartifacthub-pkg.yml
file. - After a successful release, that is, after the policy has been successfully
built, signed, and pushed, our GitHub Actions have a last job that pushes the
files needed by Artifact Hub to an orphan
artifacthub
branch. The canonical files are always the ones in themain
branch, and the GHA job overwrites the ones inartifacthub
branch every time.
Finally, ensure your policy is published inside of a container registry or on a web server.
Right now the contents of the artifacthub-repo.yml
file are not relevant.
Once everything is in place, log into Artifact Hub and go to your control plane.
Decide whether you want to publish the policy as a user or under an Artifact Hub organization you belong to. This is done by choosing the correct "control panel context".
Then press the "Add" button and fill the form:
- Choose "Kubewarden policies" as kind.
- Enter a "Name" and "Display name" of your choice.
- Enter the URL to your Git repository.
- Enter
artifacthub
as the branch to track.
Finally, press the "Add" button. This will bring you back to the "Repositories" page, where you will see your freshly created repository.
Each repository has several information fields. Find the "ID" property of the repository you just created and copy it.
Go back to your Git repository and edit the artifacthub-repo.yml
. Ensure the
repositoryID
key found inside of the document has the value you just copied from the
Artifact Hub web page.
The format of the artifacthub-repo.yml
file is defined
here.
Now it's a good time to do some further customizations to this file.
Once you are done with the changes, commit the updated artifacthub-repo.yml
file and push it. During the next scan, Artifact Hub will find this file and
it will add the
"Verified Publisher" badge
to you Artifact Hub repository.
Keeping Artifact Hub in Sync​
Do not forget to update the contents of the artifacthub-pkg.yml
file
every time you release a new version of your policy.
The contents of the artifacthub-repo.yml
file do not need to be changed.