Version: v1.8

Build your Own Registry

An addon registry can be used for discovering and distributing addons. Currently, KubeVela supports two kinds of registries:

  • Git Repo, you just need to push addon artifacts to any git repository to work. This kind relies on git to manage addon version while kubevela can only recognize the latest version.
  • Helm repo, addon registry can share the same infrastructure with your helm charts, the format are strictly aligned. But addon can’s be installed by helm, it need render for special files such as CUE. The package version management is aligned with Helm and KubeVela can recognize versions and install with a specified one.

A directory with some subdirectories stored in a git repository can be used as an addon registry.

The git type registry type supports GitHub, GitLab, and Gitee.

A typical git addon registry is like catalog. You can clone this repo to your local path and then push to your own git repository.

  1. $ git clone https://github.com/kubevela/catalog/tree/master/addons
  2. $ git remote add <repoName> <you git server address>
  3. $ git push -u <repoName> master

If your repository type is GitHub, you can use this command to add your addon registry.

  1. vela addon registry add my-repo --type git --endpoint=<URL> --path=<ptah> --gitToken=<git token>

If your type is Gitee, you can use:

  1. vela addon registry add my-repo --type gitee --endpoint=<URL> --path=<ptah> --gitToken=<git token>

If your type is GitLab, you can use:

  1. vela addon registry add my-repo --type gitlab --gitRepoName=<repoName> --endpoint=<URL> --path=<ptah> --gitToken=<git token>

Push new addons just like checking code into your git repository.

A Helm Chart repository can be used to store versioned addon packages. ChartMuseum is an open-source and easy-to-deploy Helm Chart Repository server.

In this tutorial, we are going to use ChartMuseum to build our repository. If you don’t have ChartMuseum but already have some helm registries, you can re-use your registry with the following guide. The only exception for not having ChartMuseum is that you cannot utilize vela addon push command and will have to manually upload your addon.

Note: you can also use registries that are compatible with ChartMuseum (e.g. Harbor). They will have the same capabilities.

You can skip this step if you already have ChartMuseum.

We have provided a ChartMuseum addon, you can also create your own ChartMuseum instance or re-use exist one.

To enable it, run:

  1. vela addon enable chartmuseum

If you don’t have access to the default registry, refer to the air gap installation of chartmuseum.

To customize addon parameters, either:

  • use VelaUX and fill out the form when enabling addon
  • or check out what parameters are available using vela addon status chartmuseum -v, and specify it using vela addon enable chartmuseum externalPort=80

This tutorial will assume you used the default parameters.

After successfully enabling the addon, we need to make sure ChartMuseum is accessible to you by forwarding the default port (8080):

  1. vela port-forward -n vela-system addon-chartmuseum 8080:8080 --address 0.0.0.0

Typically, you would configure ingress (achievable using addon parameters) to make the addon accessible to the outside.

Use your newly created ChartMuseum repository (or any other Helm Chart repository) as an addon registry. We will name it localcm:

  1. $ vela addon registry add localcm --type helm --endpoint=http://localhost:8080 
  2. # If username and password is required, you can specify them with --username and --password
  3. # If the repo setup with self-signed certificate, you can use flag `--insecureSkipTLS` to add it.

You should see it in the list now:

  1. $ vela addon registry list
  2. Name        Type    URL                        
  3. ...
  4. localcm     helm    http://localhost:8080

Note: you need to upgrade your CLI to v1.5.0+ for this feature.

Prepare your addon. We will create a new one named sample-addon here:

  1. $ vela addon init sample-addon
  2. # A conventional addon directory will be created
  3. # ./sample-addon
  4. # ├── definitions
  5. # ├── metadata.yaml
  6. # ├── readme.md
  7. # ├── resources
  8. # ├── schemas
  9. # └── template.yaml

(Optional) Package your addon:

Feel free to skip ahead. We will do this automatically for you if you don’t want to package it manually.

  1. $ vela addon package sample-addon
  2. # You should see a package named sample-addon-1.0.0.tgz

Push your addon (sample-addon) to the registry (localcm) that you just added:

  1. # Notice how we automatically package the addon for you. 
  2. $ vela addon push sample-addon localcm
  3. Pushing sample-addon-1.0.0.tgz to localcm(http://localhost:8080)... Done
  4. # If you packaged it yourself, just replace `sample-addon` with `sample-addon-1.0.0.tgz`
  6. # In addition to registry names (localcm, as we saw earlier), URLs are also supported.
  7. # If you use URLs, you don't even have to add it as an addon registry.
  8. $ vela addon push sample-addon-1.0.0.tgz http://localhost:8080 -f
  9. Pushing sample-addon-1.0.0.tgz to http://localhost:8080... Done
  10. # Notice the `-f` option.
  11. # This is because we already pushed the exact same addon to the same registry earlier.
  12. # We need to use `-f` to overwrite it.

For more advanced usages, please refer to vela addon push -h.

Your addon is available in the registry now!

  1. $ vela addon list
  2. NAME          REGISTRY   DESCRIPTION             AVAILABLE-VERSIONS  STATUS  
  3. ...
  4. sample-addon  localcm    An addon for KubeVela.  [1.0.0]             disabled

As described in Air-gapped Installation for Addon, you can enable an addon from local filesystem. But some addons required a Helm Chart, then you will need to build a Chart repository for that. This section is to tackle that problem. You will also learn how to sync addon catalog to your ChartMuseum instance, so that you can directly enable an addon from a registry, instead of enabling it from local filesystem.

  • Air-gapped installation of ChartMuseum addon
  • Sync addon catalog to your ChartMuseum instance
  • Sync Helm Charts to your ChartMuseum instance

Since all the required files to install ChartMuseum addon are stored in the catalog, you need to download addon catalog first:

  1. $ git clone --depth=1 https://github.com/kubevela/catalog

Navigate to ChartMuseum addon directory:

  1. $ cd catalog/addons/chartmuseum

Now, you need to find a way to sync ChartMuseum image to your cluster. For example, you can pre-load the original image into your cluster or sync the image to your private image registry and use a custom image.

To find out the default image that ChartMuseum is using:

  1. $ cat resources/parameter.cue | grep "image"
  2.     // +usage=ChartMuseum image
  3.     image: *"ghcr.io/helm/chartmuseum:v0.15.0" | string
  4. # At the time of writing, ChartMuseum is using ghcr.io/helm/chartmuseum:v0.15.0
  5. # Fetch this image and make it available in your private cluster.

To use your custom image and enable the addon:

  1. $ vela addon enable . image=your-private-repo.com/chartmuseum:v0.15.0
  2. # Since you are already inside chartmuseum/ dir, we use `.`

Now ChartMuseum addon should be enabled.

Before you continue, you need to make sure you can access your ChartMuseum instance. Check out the previous section on how to use it as an addon registry. We will assume you are using the same settings as the previous section (i.e. you can properly access it, and named as localcm).

Inside the repo that you just cloned, navigate to catalog/addons. You should see a list of community-verified addons.

You can sync all of our addons in the catalog to your ChartMuseum instance and use them in your private environment. We will leverage vela addon push command (CLI v1.5 or later) to package these and sync them to ChartMuseum.

As we all know, we can push a single addon to ChartMuseum by:

  1. # push chartmusem/ to localcm registry
  2. vela addon push chartmuseum localcm

Therefore, we can use a loop to push all addons to ChartMuseum:

  1. # You PWD should be catalog/addons.
  2. # Replace `localcm` with you own registry name.
  3. for i in *; do \
  4.     vela addon push $i localcm -f; \
  5. done;
  7. Pushing cert-manager-1.7.1.tgz to localcm(http://10.2.1.4:8080)... Done
  8. Pushing chartmuseum-4.0.0.tgz to localcm(http://10.2.1.4:8080)... Done
  9. Pushing cloudshell-0.2.0.tgz to localcm(http://10.2.1.4:8080)... Done
  10. ...

Congratulations, all community-verified addons are now available in your ChartMuseum instance (check it out using vela addon list, and enable them using vela addon enable addon-name). You can do the same thing with experimental addons.

This is useful when you need to enable an addon that uses a Helm Chart inside, but you cannot access the Chart.

We will take dex addon as an example here. It originally uses a Chart named dex from dexidp. We are going to make that Chart available in our ChartMuseum instance and modify dex addon to use our custom Chart.

Check template.yaml or resources/ directory to find out what Chart is dex using.

After you know the right Chart, pull the corresponding Chart:

  1. # Add the repo
  2. $ helm repo add dexidp https://charts.dexidp.io
  3. # Pull the right Chart
  4. $ helm pull dexidp/dex --version 0.6.5
  5. # You should see a package named `dex-0.6.5.tgz`

Push the Chart to ChartMuseum:

  1. $ vela addon push dex-0.6.5.tgz localcm
  2. # You can use helm cm-push as well, if you have the Helm plugin installed.

Now you have dex inside your ChartMuseum instance. It is time to use it.

Edit template.yaml or Helm component in resources/ to use your custom Chart:

  1. # template.yaml of dex addon
  2. apiVersion: core.oam.dev/v1beta1
  3. kind: Application
  4. metadata:
  5.   name: dex
  6.   namespace: vela-system
  7. spec:
  8.   components:
  9.     - name: dex
  10.       type: helm
  11.       properties:
  12.         chart: dex
  13.         version: "0.6.5"
  14.         # Put your ChartMuseum URL here
  15.         url: "http://10.2.1.4:8080"
  16.         repoType: helm

Great! After you enable this addon, it will try to fetch the Chart from your ChartMuseum instance. (You should also consider making the images inside the Chart available to you too.)

Last updated on May 6, 2023 by Tianxin Dong