为 Ansible/Helm Operator 扩展 `add api` 命令:Operator SDK 的 API 脚手架设计提案解读

原创2026-09-27 09:44:081,943 阅读
文章标签:云原生后端开发工具微服务

为 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):

  1. 移除或放宽 "Only Go projects can add apis" 的 CheckGoProjectCmd 限制;
  2. 在 apiRun 中按 --type(或项目类型配置)分派到 doAnsibleScaffold / doHelmScaffold 对应的资源级脚手架逻辑;
  3. 为 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)依次执行:

  1. util.RemoveKustomizeCRDManifests() 清理旧的 CRD kustomize 清单;
  2. util.UpdateKustomizationsCreateAPI() 更新各 kustomization.yaml;
  3. 构造 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 时需要注意:

  1. 命令与 flag:核心是 --kind + --api-version($GROUP/$VERSION);Helm 侧额外支持 --helm-chart、--helm-chart-repo、--helm-chart-version 指定 chart 来源;
  2. 生成产物:Ansible 生成 roles/<kind>/ role 骨架;Helm 生成 helm-charts/<chart>/;两者都会联动产出 CRD、CR 示例、RBAC 的 apiGroups 条目以及 watches.yaml 新条目;
  3. 运行前提:必须在已初始化的 Operator 项目目录内执行;项目若非 multigroup 配置则不能跨 group 追加;
  4. 验证方式:提案作者在 PoC 阶段使用 make install / make uninstall 本地验证脚手架产物。

参考链接

登录后查看全文
operator-sdk