Record the progress of the OSPP 2023 hgctl project #453
Conversation
Codecov Report
Additional details and impacted files@@ Coverage Diff @@
## main #453 +/- ##
==========================================
- Coverage 37.46% 35.74% -1.72%
==========================================
Files 65 70 +5
Lines 9215 10114 +899
==========================================
+ Hits 3452 3615 +163
- Misses 5497 6213 +716
- Partials 266 286 +20
|
WeixinX
changed the title
|
The conflicts have been resolved. |
pkg/cmd/hgctl/plugin/build/build.go
Outdated
| md.Close() | ||
| return errors.Wrap(err, "failed to execute README.md or README_{lang}.md template") | ||
| } | ||
| md.Close() |
pkg/cmd/hgctl/plugin/ls/ls.go
Outdated
| for _, item := range list.Items { | ||
| fmt.Fprintf(printer, "%s\t%s\n", item.GetName(), getAge(item.GetCreationTimestamp().Time)) | ||
| } | ||
| printer.Flush() |
WeixinX
requested review from
SpecialYang,
johnlanni and
Charlie17Li
as code owners
|
@WeixinX hgctl plugin init 可以生成 option.yml，是否在init时让用户输入镜像仓库地址，这样无需再修改option.yml |
|
@johnlanni 因为我的想法是默认构建产物为文件形式，所以 option.yaml 里的 output.type 默认为 files, output.dest 也就是本地目录，而不是镜像仓库地址了。或者考虑把这两个选项分开也可以的 |
我的出发点是希望plugin install时不需要再去修改option.yaml，延伸开来看，其实是希望80%的普通简单场景，可以在plugin init时基于的输入参数生成option.yaml后，都不需要再调整这份自动生成的option.yaml。从而简化用户使用。 另外，我建议命令行参数和option.yaml不要一一对应，有了option.yaml后，应该简化命令行参数，让命令行参数专注于action（例如 build to image 或 build to file），其他配置都让option.yaml来做 |
|
现在 hgctl plugin init 生成代码中的 model config 的名称是根据插件名自动生成的么，例如 hello-world 变成 HelloWorldConfig ,这里我建议 model config 的名称可以是固定的，例如 PluginConfig，这样 -s 这个参数可以有默认值，无需用户配置。 |
1. 简介
该 PR 作为 Draft，用于追踪 OSPP 2023 hgctl 项目进展、审查和修订。
欢迎大家提出修改意见 ~ 👏🏻 ❤️
2. 进度
[√]tinygo 0.28.1 #462
[√]需要支持 init 得到的 option.yaml
[√]无需指定插件配置文件，而是直接指定插件代码目录，并完成build（镜像仓库信息可以读取本地配置），install时需要的配置根据schema让用户交互式输入
[√]需要支持 init 得到的 option.yaml
3. hgctl plugin 使用指南
hgctl plugin 相关命令目前可以辅助用户完成 Golang WASM 插件的开发、构建、测试和安装，减轻用户重复复制/粘贴模板的上下文切换负担。
推荐的使用方式（顺序）为：
hgctl plugin init: 初始化 Golang WASM 插件项目；hgctl plugin build --output-type files: 构建 WASM 插件，在本地输出构建产物；hgctl plugin test: 使用 docker compose 在本地测试 WASM 插件，如需修改插件逻辑，则返回第 2 步；hgctl plugin build --output-type image: 构建 WASM 插件作为 OCI 镜像上传至镜像仓库；hgctl plugin install: 安装 WASM 插件，可以通过本地的 yaml 文件或插件项目进行安装。另外，若需要查看已安装的插件，则使用
hgctl plugin ls；若需要操作插件配置，则使用hgctl plugin config相关命令。下面分点对上述命令进行说明。
3.1. 使用示例
1. init 初始化插件项目
2. build 构建插件
3. test 本地测试插件
4. install 安装插件
5. config 编辑配置
3.2. hgctl plugin init
init 命令类似于脚手架工具，可以根据用户的输入生成 Golang WASM 模板项目，该模板项目可以很容易让用户上手插件开发。
3.2.1. 命令选项
3.2.2. 使用示例
生成的 main.go 文件包含了一个 Hello World 示例，里边形如
@Name的注解可以用于生成 spec.yaml 作为插件配置校验信息（JSON Schema）：生成的 option.yaml 文件非常重要，可以为 build, test, install 命令提供选项，因此不需要用户反复输入很长的命令：
3.3. hgctl plugin build
build 命令使用容器的方式构建用户编写好的 WASM 插件。
目前支持两种产物输出形式：
files: 将构建产物输出到本地image: 将构建产物作为 OCI 镜像上传到镜像仓库3.3.1. 命令选项
3.3.2. 使用示例
以 init 命令生成的 Hello World 模板项目为例，介绍目前支持的两种构建输出形式：
1. files: 将构建产物输出至本地（用于测试）
由于 option.yaml 中默认为 files 输出形式，并且指定了输出目录为 ./out 以及配置模型（即 HelloWorldConfig 结构体）所在的目录 ./，因此我们只需通过命令行选项指定模型名称
--model HelloWorldConfig（将该选项写入 option.yaml 也是可以的）：查看构建产物：
(1) spec.yaml
spec.yaml 作为插件的 metadata，其中
spec.configSchema.openAPIV3Schema用于校验配置参数，在 install 命令中会用到：(2) README.md
2. image: 将构建产物作为 OCI 镜像上传到镜像仓库（用于安装）
首先使用
docker login登录，构建容器中会复用这个登录凭证。再使用--output-type image --output-dest docker.io/weixinx/hello-world:v0.1.0覆盖 option.yaml 的选项：3.4. hgctl plugin test
test 命令拥有 5 个子命令：
create: 创建测试环境，即生成 docker-compose.yaml, envoy.yaml 和 plugin-conf.yaml；start: 启动测试环境，类似于docker compose up；stop: 关停测试环境，类似于docker compose down；clean：清理测试环境，除了关停测试环境外，还将生成的测试文件目录删除；ls: 查看已启动的测试环境。3.4.1. 命令选项
1. hgctl plugin test create
2. hgctl plugin test start
3. hgctl plugin test stop
4. hgctl plugin test clean
5. hgctl plugin test ls
3.4.2. 使用示例
以前文 Hello World 插件为例：
$ pwd /home/ubuntu/hello-world $ ls go.mod go.sum main.go option.yaml out1. create: 创建测试环境
由于前面已经将构建产物输出到本地，因此只需依赖 option.yaml 的默认选项便可创建测试环境：
这些生成的配置文件均使用 spec.yaml 文件中对应参数进行填充：
(1) docker-compose.yaml
(2) envoy.yaml
(3) plugin-conf.yaml
实际上在启动测试环境中并没有使用到该文件，该文件交由用户在测试集群中按需使用：
2. start & ls: 启动并查看测试环境
在此以后台运行的方式（
--detach）启动测试环境：查看已启动的测试环境：
$ hgctl plugin test ls NAME STATUS CONFIG FILES wasm-test running(2) /home/ubuntu/hello-world/test/docker-compose.yaml测试 Hello World 插件：
3. stop: 关停测试环境
4. clean: 清理测试环境
由于上面已经关停了测试环境，因此清理命令只是移除了 test 目录
3.5. hgctl plugin install/uninstall/ls
install: 用于安装 WASM 插件，支持使用 yaml 文件和 WASM 项目源文件两种安装方式。uninstall: 卸载 WASM 插件。ls: 查看已安装的 WASM 插件。3.5.1. 命令选项
1. hgctl plugin install
2. hgctl plugin uninstall
3. hgctl plugin ls
$ hgctl plugin ls -h List all installed WASM plugins Usage: hgctl plugin ls [flags] Aliases: ls, l Examples: hgctl plugin ls Flags: --context string The name of the kubeconfig context to use. -h, --help help for ls --kubeconfig string Path to the kubeconfig file to use for CLI requests. -n, --namespace string Namespace where Higress was installed (default "higress-system")3.5.2. 使用示例
1. install: 安装插件
依然使用上述的 Hello World 插件为例，介绍两种安装方式：
(2)
--from-yaml: 根据 yaml 文件安装首先还原前面清除的测试环境：
修改 test/plugin-conf.yaml 文件的 OCI 镜像 URL 为 build 命令处的镜像目标：
依赖 option.yaml 默认选项进行安装：
$ hgctl plugin install Installed wasm plugin "higress-system/hello-world"(2)
--from-go-project: 根据项目源文件安装这种方式会首先构建插件项目文件，并将构建结果作为 OCI 镜像上传，再通过命令行交互让用户输入插件配置，最终根据配置进行安装。
该方式实际上就是 build 命令将产物以 OCI 镜像输出，再利用自动生成 plugin-conf.yaml 进行安装，因此需要修改 option.yaml 文件的 build 和 install 选项：
执行安装命令（前面已经安装过同样的插件了，所以会报告已存在）：
$ hgctl plugin install [-] pull the builder image ... {"status":"Pulling from plugins/wasm-go-builder","id":"go1.19-tinygo0.28.1-oras1.0.0"} {"status":"Digest: sha256:9b5a104f4e6bca9fc102a3efc835a2136a8eaa4b76cafbbf93a71098570896c1"} {"status":"Status: Image is up to date for higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/wasm-go-builder:go1.19-tinygo0.28.1-oras1.0.0"} [√] pull the builder image: higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/wasm-go-builder:go1.19-tinygo0.28.1-oras1.0.0 [-] create the builder container ... [√] create the builder container: b0ee40cfad0fee05b7330acdab536a6f74afb49cf629d42cdbd52ecf5eba885b [-] start the builder container ... go: downloading github.com/tidwall/gjson v1.14.3 go: downloading github.com/alibaba/higress/plugins/wasm-go v0.0.0-20230829022308-8747e1ddadf0 go: downloading github.com/tetratelabs/proxy-wasm-go-sdk v0.22.0 go: downloading github.com/tidwall/match v1.1.1 go: downloading github.com/tidwall/pretty v1.2.0 go: downloading github.com/google/uuid v1.3.0 go: downloading github.com/wasilibs/nottinygc v0.3.0 go: downloading github.com/stretchr/testify v1.8.0 go: downloading github.com/magefile/mage v1.14.0 go: downloading github.com/davecgh/go-spew v1.1.1 go: downloading github.com/pmezard/go-difflib v1.0.0 go: downloading gopkg.in/yaml.v3 v3.0.1 Uploading bb05515f156c plugin.tar.gz Uploaded bb05515f156c plugin.tar.gz Exists 39e6ef91f5a3 README.md Exists a2b3ef03bd79 spec.yaml Pushed [registry] docker.io/weixinx/hello-world:v0.1.0 Digest: sha256:d4edde2080841749b7ac625ad460826e66531dc7aab6155fdec644426948db49 [√] finish building and pushing! Please enter the configurations for the WASM plugin you want to install: Configuration example: firstField: hello secondField: world ? Choose a configuration effective scope or complete: INSTANCE ? Choose Ingress or Domain: Ingress ? Enter the matched ingress: foo ? continue? No Ingress: HelloWorldConfig(object, required) ? firstField(string, required) ni ? secondField(string, required) hao √ Successful to add configuration. ? Choose a configuration effective scope or complete: Complete The complete configuration is as follows: matchRules: - ingress: - foo config: firstField: ni secondField: hao wasm plugin "higress-system/hello-world" already exists2. ls: 查看已安装插件
3. uninstall: 卸载插件
$ hgctl plugin uninstall --name hello-world Uninstalled wasm plugin "higress-system/hello-world" $ hgctl plugin ls NAME AGE3.6. hgctl plugin config
config 命令有两个子命令：
create: 创建 plugin-conf.yaml 插件配置模板文件；edit: 编辑以安装的插件配置3.6.1. 命令选项
3.6.2. 使用示例
为了编辑已安装的插件配置，我们还原上面被卸载的 Hello World 插件。
$ hgctl plugin install -y test/plugin-conf.yaml Installed wasm plugin "higress-system/hello-world" $ hgctl plugin ls NAME AGE hello-world 10s执行 edit 命令修改配置，与
kubectl edit类似，通过编辑器编辑配置后退出即可：$ hgctl plugin config edit --name hello-world apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: annotations: higress.io/wasm-plugin-description: This is a demo plugin higress.io/wasm-plugin-icon: https://img.alicdn.com/imgextra/i1/O1CN018iKKih1iVx287RltL_!!6000000004419-2-tps-42-42.png higress.io/wasm-plugin-title: Hello World creationTimestamp: "2023-09-07T08:06:08Z" generation: 1 labels: higress.io/resource-definer: higress higress.io/wasm-plugin-built-in: "false" higress.io/wasm-plugin-category: custom higress.io/wasm-plugin-name: hello-world higress.io/wasm-plugin-version: 0.1.0 name: hello-world namespace: higress-system resourceVersion: "235519" uid: 8f74e9dc-868f-44d5-a219-c18ee8baa733 spec: defaultConfig: firstField: ni secondField: hao phase: UNSPECIFIED_PHASE priority: 10 url: docker.io/weixinx/hello-world:v0.1.0 ~ ~ ~ :wq Edited wasm plugin "higress-system/hello-world"