为 Ansible/Helm Operator 扩展 `add api` 命令:Operator SDK 的 API 脚手架设计提案解读
为 Ansible/Helm Operator 扩展 add api 命令:Operator SDK 的 API 脚手架设计提案解读
Operator SDK 的 CLI 曾长期只支持为 Go 类型 Operator 在项目创建后追加 API;Ansible/Helm Operator 开发者只能手工往脚手架里塞 CRD、CR、Role 和 watches 配置。本文基于仓库中 proposals/ansible-helm-addapi.md 这份设计提案,完整梳理其背景动机、用户故事与验收标准、目标与非目标、命令与参数设计、脚手架产物目录结构,并结合当前仓库中 Helm/Ansible 插件的源码实现,说明该能力最终是如何落地的、底层关键调用链与约束条件。
1. 提案背景与动机:为什么需要"追加 API"
在提案提出时(2020 年),operator-sdk new 可以在创建项目的同时指定首个 API——例如:
operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached --type=ansible
底层会依据 --type 判断 Operator 类型,并调用对应的脚手架函数(提案中的伪代码):
case projutil.OperatorTypeAnsible:
if err := doAnsibleScaffold(); err != nil {
return err
}
case projutil.OperatorTypeHelm:
if err := doHelmScaffold(); err != nil {
return err
}
但项目创建之后,operator-sdk add api 却只允许 Go 项目继续追加 API,代码中直接做了硬性拦截:
// Only Go projects can add apis.
if err := projutil.CheckGoProjectCmd(cmd); err != nil {
return err
}
这带来的直接问题是:Ansible/Helm Operator 开发者想要为已创建的项目增加第二个 API 时,没有 CLI 通道可用,只能手工创建 roles/helm-charts 目录、手写 CRD 与 CR、手工修改 deploy/role.yaml 和 watches.yaml。提案的动机正是要消除这种手工维护的负担,把"追加 API"的体验统一到 SDK CLI 上。
2. 目标与非目标
提案明确划定了能力边界:
Goals(要做的事)
- Ansible/Helm Operator 开发者可以使用现有 SDK CLI 命令按需创建额外 API;
operator-sdk new中与 Ansible/Helm 相关的 flags,在operator-sdk add api中同样可用;- 为同一能力补齐用户文档(SDK CLI 参考、
operator-sdk add api使用说明)。
Non-Goals(明确不做,标注 TBD)
- 不为 Ansible 新增 API 更新 Molecule 测试;
- 不为 Ansible 新增 API 生成/更新 Playbook。
这两条"非目标"值得注意:它说明提案聚焦的是"脚手架静态资源生成"这一件事,而测试与 Playbook 的联动被刻意推迟,避免把范围无限扩大。
3. 用户故事与验收标准
Story 1:Ansible Operator 追加 API
核心命令:
operator-sdk add api --kind <kind> --api-version <group/version> [flags]
验收标准:
- 通过上述命令能脚手架出新增 API 所需的全部资源;
operator-sdk new的 flags 同步开放给operator-sdk add api,包括:
--api-version string CRD APIVersion,格式 $GROUP_NAME/$VERSION(如 app.example.com/v1alpha1)
--kind string CRD Kind(如 AppService)
--generate-playbook 生成 playbook 骨架(仅 --type ansible 时使用)[TBD]
- SDK CLI 参考文档与
operator-sdk add api文档中补充 Ansible 追加 API 的步骤。
Story 2:Helm Operator 追加 API
核心命令与 Ansible 相同,但 flags 侧重 Helm chart 来源:
--api-version string CRD APIVersion,格式 $GROUP_NAME/$VERSION(如 app.example.com/v1alpha1)
--kind string CRD Kind(如 AppService)
--helm-chart string 以已有 helm chart 初始化 operator(<URL>、<repo>/<name> 或本地路径)
--helm-chart-repo string 所请求 chart 的仓库 URL
--helm-chart-version string chart 的具体版本(默认取最新版)
验收标准同样包含:命令可脚手架全部所需资源、flags 与 operator-sdk new 对齐、两类文档更新到位。
4. 提案的核心实现思路
提案给出的关键设计是:复用 operator-sdk new 中已有的类型判断与脚手架函数,而不是为 add api 另写一套。具体做法是增强 apiRun(cmd *cobra.Command, args []string):
- 移除或放宽 "Only Go projects can add apis" 的
CheckGoProjectCmd限制; - 在
apiRun中按--type(或项目类型配置)分派到doAnsibleScaffold/doHelmScaffold对应的资源级脚手架逻辑; - 为 Ansible/Helm 分别补充相应的 flag 绑定。
4.1 配套 PoC 验证
提案作者通过两个演示仓库完成了手工 PoC(本地用 make install / make uninstall 验证),并给出了追加 API 后的项目布局,这份目录结构也是理解"追加 API 到底生成什么"的最佳参考。
Ansible roles 布局:每个 Kind 对应 roles/<kind> 标准 Ansible role 骨架:
roles
├── memcached
│ ├── README.md
│ ├── defaults/main.yml
│ ├── files
│ ├── handlers/main.yml
│ ├── meta/main.yml
│ ├── tasks/main.yml
│ ├── templates
│ └── vars/main.yml
└── myapp (新增 API 的 role)
├── README.md
├── defaults/main.yml
├── files
├── handlers/main.yml
├── meta/main.yml
├── tasks/main.yml
├── templates
└── vars/main.yml
Helm charts 布局:每个 Kind 对应 helm-charts/<chart> 目录(既有手工脚手架的新 chart,也有来自外部仓库的完整 chart):
helm-charts
├── memcached
│ ├── Chart.yaml
│ ├── README.md
│ ├── templates/{NOTES.txt,_helpers.tpl,pdb.yaml,statefulset.yaml,svc.yaml}
│ └── values.yaml
├── mongodb
│ ├── Chart.yaml
│ ├── OWNERS
│ ├── files/docker-entrypoint-initdb.d/README.md
│ ├── templates/{...}
│ ├── values-production.yaml
│ ├── values.schema.json
│ └── values.yaml
└── nginx
├── Chart.yaml
├── charts
├── templates/{NOTES.txt,_helpers.tpl,deployment.yaml,ingress.yaml,service.yaml,serviceaccount.yaml,tests/test-connection.yaml}
└── values.yaml
4.2 追加 API 时的四处联动修改
提案明确列出追加 API 后需要同步更新的文件:
① RBAC——/deploy/role.yaml 追加新的 apiGroups 条目:
- apiGroups:
- cache.example.com
resources:
- '*'
verbs:
- create
- delete
- get
- list
- patch
- update
- watch
- apiGroups:
- app.example.com
resources:
- '*'
verbs:
- create
- delete
- get
- list
- patch
- update
- watch
② CRD 与 CR——/deploy/crds 下按 $group_$kind 生成 CRD、按 $group_$version_$kind 生成 CR:
deploy/crds
├── cache.example.com_memcacheds_crd.yaml
├── cache.example.com_v1alpha1_memcached_cr.yaml
├── charts.helm.k8s.io_mongodbs_crd.yaml
├── charts.helm.k8s.io_v1alpha1_mongodb_cr.yaml
├── example.com_nginxes_crd.yaml
└── example.com_v1alpha1_nginx_cr.yaml
③ watches.yaml——追加新 API 的 watch 条目(Ansible 指向 role 路径,Helm 指向 chart 路径):
- version: v1alpha1
group: cache.example.com
kind: Memcached
role: /opt/ansible/roles/memcached
- version: v1alpha1
group: cache.example.com
kind: Mykind
role: /opt/ansible/roles/mykind
5. 落地验证:提案能力在仓库源码中的实现
从当前仓库源码结构看,该提案已落地为独立的插件化实现:internal/plugins/helm/v1/ 与 internal/plugins/manifests/v2/(Ansible 方向)分别承载创建与追加 API 的能力,统一暴露为 create api 子命令。
5.1 Helm 插件的 Create API 入口
internal/plugins/helm/v1/api.go 实现了 plugin.CreateAPISubcommand 接口,其子命令描述为 "Scaffold a Kubernetes API that is backed by a Helm chart",并声明了完整的示例用法,覆盖提案中的全部 chart 来源:
$ operator-sdk create api --group=apps --version=v1alpha1 --kind=AppService
$ operator-sdk create api --group=apps --version=v1alpha1 --kind=AppService --helm-chart=myrepo/app
$ operator-sdk create api --helm-chart=myrepo/app
$ operator-sdk create api --helm-chart=myrepo/app --helm-chart-version=1.2.3
$ operator-sdk create api --helm-chart=app --helm-chart-repo=https://charts.mycompany.com/
$ operator-sdk create api --helm-chart=/path/to/local/chart-directories/app/
$ operator-sdk create api --helm-chart=/path/to/local/chart-archives/app-1.2.3.tgz
$ operator-sdk create api --helm-chart=oci://charts.mycompany.com/example-namespace/app:1.2.3
对应 flags 绑定(api.go#L118-L129):
fs.StringVar(&p.options.chartOptions.Chart, helmChartFlag, "", "helm chart")
fs.StringVar(&p.options.chartOptions.Repo, helmChartRepoFlag, "", "helm chart repository")
fs.StringVar(&p.options.chartOptions.Version, helmChartVersionFlag, "", "helm chart version (default: latest)")
fs.StringVar(&p.options.CRDVersion, crdVersionFlag, defaultCrdVersion, "crd version to generate")
其中 helm-chart、helm-chart-repo、helm-chart-version 正是提案 Story 2 验收标准里要求的三个 flag。
5.2 资源注入与校验规则(比提案更细的约束)
在 InjectResource(api.go#L144-L216)中,插件补充了几条提案未展开的约束,实战中必须注意:
--helm-chart-repo/--helm-chart-version只能与--helm-chart搭配使用,否则报错;--kind与--helm-chart至少要提供其一:不提供 chart 时,以 Kind 小写化作为新 chart 名;提供 chart 时,未指定的 Group/Version/Kind 会被默认值填充(Group 默认charts,Version 默认v1alpha1,Kind 默认由 chart 名转 CamelCase);- API 已存在时拒绝重复脚手架(
the API resource already exists); - 多 group 限制:默认项目不允许引入第二个 group,除非在 PROJECT 文件中设置
multigroup: true; - CRD 版本一致性:项目内所有资源只能使用同一个 CRD 版本(默认
v1,v1beta1已标记废弃并打印移除警告)。
5.3 追加 API 的 scaffold 执行链
Scaffold 方法(api.go#L218-L234)依次执行:
util.RemoveKustomizeCRDManifests()清理旧的 CRD kustomize 清单;util.UpdateKustomizationsCreateAPI()更新各kustomization.yaml;- 构造
scaffolds.NewAPIScaffolder并执行真正的文件生成。
在 internal/plugins/helm/v1/scaffolds/api.go 中,apiScaffolder.Scaffold() 会:
- 调用
chartutil.ScaffoldChart把 chart 落盘到helm-charts/目录; - 通过
machinery.NewScaffold批量执行四个模板/更新器,这正是提案"四处联动修改"的工程化对应:
scaffold.Execute(
&templates.WatchesUpdater{ChartPath: chartPath}, // 更新 watches.yaml
&crd.CRD{}, // 生成 CRD
&crd.Kustomization{}, // 更新 CRD kustomization
&rbac.ManagerRoleUpdater{Chart: s.chrt}, // 更新 manager Role(新 apiGroups)
&samples.CustomResource{ChartPath: chartPath, Chart: s.chrt}, // 生成 CR 示例
)
5.4 watches.yaml 的插入机制
watches 文件的更新由 internal/plugins/helm/v1/scaffolds/internal/templates/watches.go 中的 WatchesUpdater 实现:它作为 machinery Inserter 工作,在文件内的 # +kubebuilder:scaffold:watch 标记处插入新条目,片段格式为:
- group: %s
version: %s
kind: %s
chart: %s
当前仓库的 Helm 测试样例 testdata/helm/memcached-operator/watches.yaml 展示了模板化之后的形态(Helm 用 chart 字段而非 Ansible 的 role 字段):
# Use the 'create api' subcommand to add watches to this file.
- group: cache.example.com
version: v1alpha1
kind: Memcached
chart: helm-charts/memcached
# +kubebuilder:scaffold:watch
文件头部的注释 "Use the 'create api' subcommand to add watches to this file" 与提案"通过 CLI 追加 API"的目标完全一致。
5.5 init 与 create api 的联动
internal/plugins/helm/v1/init.go 显示:init(即 operator-sdk new 的等价物)在绑定 group/version/kind/chart 等 flag 后,若检测到这些参数,会在 PostScaffold 阶段自动以自身二进制重新执行 create api 子命令(init.go#L143-L177),把首 API 的脚手架统一收敛到同一套 Create API 逻辑——这与提案"复用已有脚手架函数"的设计一脉相承:初始化与追加 API 走的是同一条代码路径。
6. 从提案到现状:能力的演进要点
对比提案与当前源码,可以梳理出以下几点演进:
| 维度 | 提案(2020-03) | 当前仓库实现 |
|---|---|---|
| 命令形态 | operator-sdk add api |
operator-sdk create api(插件化子命令) |
| Ansible 方向 | 手工 PoC + TBD | 由 internal/plugins/manifests/v2/ 承载 |
| Helm 方向 | 手工 PoC | internal/plugins/helm/v1/ 完整实现 Create API 插件 |
| chart 来源 | <URL>、<repo>/<name>、本地路径 |
额外支持本地目录、.tgz 归档、oci:// 仓库 |
| watches 更新 | 手工追加条目 | WatchesUpdater 在 scaffold 标记处自动插入 |
| 约束校验 | 未展开 | 已存在性检查、多 group 限制、CRD 版本一致性校验 |
7. 实战要点小结
基于提案与源码,为 Ansible/Helm Operator 追加 API 时需要注意:
- 命令与 flag:核心是
--kind+--api-version($GROUP/$VERSION);Helm 侧额外支持--helm-chart、--helm-chart-repo、--helm-chart-version指定 chart 来源; - 生成产物:Ansible 生成
roles/<kind>/role 骨架;Helm 生成helm-charts/<chart>/;两者都会联动产出 CRD、CR 示例、RBAC 的 apiGroups 条目以及watches.yaml新条目; - 运行前提:必须在已初始化的 Operator 项目目录内执行;项目若非 multigroup 配置则不能跨 group 追加;
- 验证方式:提案作者在 PoC 阶段使用
make install/make uninstall本地验证脚手架产物。