自定义 Addon 仓库

Addon registry 可以用来发现和分发 addon。 目前,KubeVela 支持两种类型的 registry:

  • Git 仓库,只需要将你的配置上传到任意一个 Git 服务地址就可以使用,依赖 Git 做版本管理,Addon 体系只能安装最新的版本。
  • Helm Chart 仓库,KubeVela 的 Addon 仓库可以与 Helm Chart 共用仓库,格式完全兼容。区别是 Addon 安装只能通过 Vela 体系。版本管理与 Helm Chart 相同,Addon 体系可以识别多版本并指定版本安装。

Git 类型的 registry 目前支持 GitHub 、 GitLab 和 Gitee。

一个典型的 addon registry 为 catalog 。 你可以克隆这个仓库到本地目录然后推到你自己的 git 仓库上。

  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

假如你的仓库类型是 GitHub,你可以用这个命令添加为 addon registry。

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

假如你的仓库类型是 Gitee :

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

假如你的仓库类型是 Gitlab :

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

上传 Addon 等价于向 Git 仓库提交代码。

Helm Chart 仓库 可以用来存储 addon,并带有版本管理。 ChartMuseum 是一个开源的容易部署的 Helm Chart 仓库服务器。

在这个教程中,我们将使用 ChartMuseum 来构建我们的仓库。假如你已经有 Helm 仓库而非 ChartMuseum,不用担心,除了你不能使用 vela addon push 命令需要手动上传你的 addon 之外,下列文档中的其他功能均可以正常使用。

注:你也可以使用兼容 ChartMuseum 的仓库 (例如 Harbor ),它们具有类似的功能。

为了方便用户使用,KubeVela 提供了开箱即用的 ChartMuseum addon,你完全可以用其他任意方式创建你自己的 ChartMuseum 实例或者直接复用已经部署好的。

使用该 addon ,运行命令:

  1. vela addon enable chartmuseum

如果这一步你不能访问默认的官方插件仓库,你可以参考下面的离线安装文档。

如果要自定义 addon 的参数,任选其一:

  • 使用 VelaUX 并且在启用 addon 时填写相应的参数
  • 或者查看通过命令 vela addon status chartmuseum -v 查看可用的参数,并通过命令 vela addon enable chartmuseum externalPort=80 来指定相应的参数。

在这个教程中将假设你使用默认的参数。

在成功安装 addon 之后,为了保证你能够访问 ChartMuseum ,我们将转发默认端口(8080):

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

一般来说,你可能需要配置 ingress(可以通过 addon 的参数来实现)来实现外界的访问。

使用你刚刚创建的 ChartMuseum (或者其他 Helm Chart 仓库 )作为 addon registry ,我们将其命名为 localcm :

  1. $ vela addon registry add localcm --type helm --endpoint=http://localhost:8080
  2. # 假如需要提供用户名和密码,你可以用 --username 和 --password 来分别指定它们

你现在可以在 registry 列表中看到自建的 addon registry 了:

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

请注意: 你需要升级 CLI 版本到 v1.5.0+ 来使用这个特性。

准备你的 addon。 我们将在这里创建一个名为 sample-addon 的 addon:

  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

(可选)打包 addon:

你可以略过这一步。 假如你不想手动打包 addon ,我们将会自动为你完成这一步骤。

  1. $ vela addon package sample-addon
  2. # 你将看到名为 sample-addon-1.0.0.tgz 的包

上传 addon (sample-addon) 到你刚添加的 registry (localcm):

  1. # 请注意我们如何为你自动打包 addon。
  2. $ vela addon push sample-addon localcm
  3. Pushing sample-addon-1.0.0.tgz to localcm(http://localhost:8080)... Done
  4. # 假如你自己打包了,只需替换 `sample-addon` 为 `sample-addon-1.0.0.tgz`
  5. # 除了 registry 名(见上 localcm ), URL 也同样支持。
  6. # 假如你使用 URL, 你甚至不需要将它添加为 addon registry。
  7. $ vela addon push sample-addon-1.0.0.tgz http://localhost:8080 -f
  8. Pushing sample-addon-1.0.0.tgz to http://localhost:8080... Done
  9. # 特别留意 `-f` 选项。
  10. # 这是因为我们之前已经推送了相同的 addon 到同一个 registry。
  11. # 我们需要使用 `-f` 来覆盖旧的。

更多高级的使用方法,请参考 vela addon push -h

现在 registry 里面已经有你的 addon 了!

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

就像 Addon的离线安装 里描述的,你可以从本地文件系统安装 addon。但是有些 addon 中需要 Helm Chart ,那么你将需要为此构建 Chart 仓库,这部分内容将解决这一问题。你也可以学习到如何从 addon catalog 同步 addon 到自建的 ChartMuseum 实例上,这样你可以直接从自建 registry 安装 addon,而不用从本地文件系统来安装。

  • ChartMuseum Addon的离线安装
  • 同步 addon catalog 到你的 ChartMuseum 实例
  • 同步 Helm Chart 到你的 ChartMuseum 实例

因为安装 ChartMuseum addon 的所需文件存储在 catalog 中,你需要先下载 addon catalog

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

进入 ChartMuseum addon 目录:

  1. $ cd catalog/addons/chartmuseum

现在你需要想方设法同步 ChartMuseum 镜像到你的集群。例如,你可以预加载 ChartMuseum 镜像到你到集群中,或者同步 ChartMuseum 镜像到你的私有镜像仓库然后在 addon 中使用自定义镜像。

你可以这样找出 ChartMuseum 正在使用的默认镜像:

  1. $ cat resources/parameter.cue | grep "image"
  2. // +usage=ChartMuseum image
  3. image: *"ghcr.io/helm/chartmuseum:v0.15.0" | string
  4. # 在写这篇文章的此时,ChartMuseum 使用 ghcr.io/helm/chartmuseum:v0.15.0 镜像
  5. # 你需要下载这个镜像并同步到你的私有集群中。

使用你的自定义镜像来安装 addon:

  1. $ vela addon enable . image=your-private-repo.com/chartmuseum:v0.15.0
  2. # 因为你已经在 chartmuseum/ 目录下,可以使用 `.`

现在 ChartMuseum Addon应该已经启用了。

在你继续之前,你必须保证你可以访问你的 ChartMuseum 实例。查看之前关于如何使用 ChartMuseum 作为 addon registry 的章节。我们假设你使用与之前部分的相同配置(也就是说,你可以通过访问名为 localcm registry 来访问它)。

在你刚刚克隆的仓库里,移动到 catalog/addons,你应该可以看到一系列社区认证的 addon。

你可以同步所有在 catalog 里面的 addon 到你的 ChartMuseum 实例并在你的私有环境里使用他们。我们将利用 vela addon push 打包这些 addon 并同步到 ChartMuseum 中。

众所周知,我们可以使用以下命令推送单个 addon 到 ChartMuseum:

  1. # 推送 chartmusem/ 到 localcm registry
  2. vela addon push chartmuseum localcm

那么,我们可以利用一个循环来推送所有的 addon 到 ChartMuseum:

  1. # 你的当前工作目录应为 catalog/addons
  2. # 将 `localcm` 替换为你自己的 registry 名称
  3. for i in *; do \
  4. vela addon push $i localcm -f; \
  5. 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. ...

恭喜,现在所有社区认证的 addon 都可以在你的 ChartMuseum 实例中使用了(用命令 vela addon list 来查看,并使用命令 vela addon enable addon-name 来安装它们)。同样地,你可以类似的方法来同步 experimental 的 addon。

当你需要安装使用了 Helm Chart 的 addon,而你不能直接访问使用的 Chart 的时候,这个特别有用。

我们这里将以 dex addon 为例,这个 addon 使用了名为 dex 的 Chart。 我们可以将这个 Chart 导入到我们的 ChartMuseum 的实例并修改 dex addon 来完成安装。

查看 template.yaml 或者 resources/ 目录来了解 dex 使用了什么 Chart ,我们知道它使用了 dexidp/dex

你知道相应的 Chart 之后,拉取相应的 Chart:

  1. # 添加仓库
  2. $ helm repo add dexidp https://charts.dexidp.io
  3. # 拉取相应的 Chart
  4. $ helm pull dexidp/dex --version 0.6.5
  5. # 你应该可以看到名为 `dex-0.6.5.tgz` 的包

推送 Chart 到 ChartMuseum :

  1. $ vela addon push dex-0.6.5.tgz localcm
  2. # 假如你的 helm 安装好了 cm-push Addon, 也可以使用 helm cm-push

现在你的 ChartMuseum 实例中已经有 dex 了。 是时候使用它了:

修改 template.yaml 或者 resources/ 目录下的 Helm Component 来使用你自定义的 Chart:

  1. # dex addon 的 template.yaml
  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. # 把你的 ChartMuseum URL 填入这里
  15. url: "http://10.2.1.4:8080"
  16. repoType: helm

很好!在你安装 dex addon 时,它将尝试从你的 ChartMuseum 实例中拉取相应的 Chart 。(当然,你也应该使 Chart 中包含的镜像在你的私有集群中可用)

Last updated on 2023年8月4日 by Daniel Higuero