Build your Own Registry

    • 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 . You can clone this repo to your local path and then push to your own git repository.

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

    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 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 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.

    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 .

    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

    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

    Add an addon registry using Helm Repository

    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:

    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. # └── template.yaml

    (Optional) Package your addon:

    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.
    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 , 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.

    Goals

    • 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 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 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.

    Sync addon catalog to your ChartMuseum instance

    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. for i in *; do \
    3.     vela addon push $i localcm -f; \
    4. done;
    6. Pushing cert-manager-1.7.1.tgz to localcm(http://10.2.1.4:8080)... Done
    7. Pushing chartmuseum-4.0.0.tgz to localcm(http://10.2.1.4:8080)... Done
    8. Pushing cloudshell-0.2.0.tgz to localcm(http://10.2.1.4:8080)... Done
    9. ...

    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 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.         repoType: helm