基于 Operator SDK 构建 Ansible Operator:提案设计、包结构、命令与 Watches 配置全解析

原创2026-09-27 10:23:411,616 阅读
文章标签:云原生后端开发工具微服务

基于 Operator SDK 构建 Ansible Operator:提案设计、包结构、命令与 Watches 配置全解析

Ansible 早已是 IT 自动化领域的事实标准,而 Kubernetes Operator 的本质正是把应用的运维知识"代码化"。Operator SDK 团队在 proposals/ansible-operator.md 中正式提出并实现了 Ansible 型 Operator:让不熟悉 Go 的运维与开发人员,也能用 Ansible Role / Playbook 编写控制器逻辑。本篇以该提案为骨架,结合本仓库中现存的源码、脚手架、watches 配置与信息流文档,完整讲解 Ansible Operator 的动机、包结构设计、生成命令、项目布局、watches 文件字段与底层运行原理,读完你即可掌握"初始化一个 Ansible Operator 项目 → 编写 Role → 配置 Watch → 构建部署"的完整链路。

Ansible Operator 信息流架构图

背景与目标:为什么 Operator SDK 需要 Ansible

提案开篇点明了引入 Ansible Operator 的两个核心原因:

  1. 开发者门槛:并非所有人都是 Go 开发者,Operator SDK 的采用率受限于 Go 开发者数量。而 Kubernetes 生态中其他语言(如 Python、Ruby)在 informer、cache、lister 等机制上的工具链支持较弱,直接复刻 controller-runtime 的能力成本极高。
  2. 运维范式契合:Operator 的职责是把应用在 Kubernetes 上的运维操作"代码化",而这恰好是 Ansible 深耕多年的领域。Ansible 作为行业标准自动化工具,天然适合承载 Operator 的调谐(reconcile)逻辑。

因此提案确立了两个并行的目标(见 proposals/ansible-operator.md):

  • 为 Ansible 开发者打造一个开箱即用的 Operator 框架,让他们无需编写 Go 代码即可创建、运行、打包 Operator;
  • 向 Go 用户暴露一个可在其 Operator 中直接调用 Ansible 的公开库,让两种技术栈可以按需混用。

这两个目标共同作用,使用户能够按项目特性或自身技能栈选择最合适的技术路线。提案状态已标记为 implemented(已实现),后续完整用户文档沉淀在仓库的 website/content/en/docs/building-operators/ansible/ 目录下。

新的 Operator 类型:ansible

提案创建了一种新的 Operator 类型 ansible,用于告知工具链"按 Ansible 型 Operator 来处理该项目"。这一设计在当前仓库源码中得到了保留与印证:

  • internal/util/projutil/project_util.go 中定义了四类 Operator 类型常量:OperatorTypeGo = "go"、OperatorTypeAnsible = "ansible"、OperatorTypeHelm = "helm"、OperatorTypeUnknown = "unknown";
  • 同一文件中的 PluginChainToOperatorType 函数(project_util.go)通过扫描 kubebuilder PROJECT 文件里的插件链,凡是以 ansible 前缀开头的插件键即判定为 Ansible 型 Operator;
  • internal/plugins/util/legacy_keys.go 将 ansible.sdk.operatorframework.io/v1 列为历史兼容插件键,说明早期版本正是以该插件键在 PROJECT 文件中标记项目类型的。

可见,所谓"新的 Operator 类型",在工程落地时即体现为 kubebuilder 插件体系中的一个插件键(plugin key),后续的脚手架、构建、部署命令都围绕它进行分支判断。

包结构设计:为公开 API 而生的五个包

提案为 Ansible Operator 规划了五个公开包,并强调它们"设计上可供最终用户直接使用,应具有文档完善的公开 API":

包路径(提案设计) 职责
/operator-sdk/pkg/ansible/controller 承载 Ansible Operator 的控制器(controller),暴露 reconciler;默认的 Add 方法即使用该 reconciler
/operator-sdk/pkg/ansible/runner 定义 Runner 类型与接口,具体实现在内部包 runner/internal 中;对外暴露 NewForWatchers、NewPlaybookRunner、NewRoleRunner 等方法,并包含从 ansible-runner 接收事件的 events API
/operator-sdk/pkg/ansible/proxy 面向 Kubernetes API 的反向代理,用于 owner reference(属主引用)注入
/operator-sdk/pkg/ansible/proxy/kubeconfig 为代理生成 kubeconfig 所需代码
/operator-sdk/pkg/ansible/events 处理来自 ansible-runner 事件的事件处理器包,默认实现仅有事件日志器

从当前仓库快照看,这些 pkg/ansible/* 路径已不再直接存在于仓库根目录(本仓库已演进为以 internal/ 为主的布局,Ansible 插件能力并入 kubebuilder 插件体系,可参考 internal/plugins/util/legacy_keys.go)。因此可以将提案中的包路径理解为"面向用户公开 API 的设计蓝图",其职责划分(controller / runner / proxy / events)至今仍是理解 Ansible Operator 内部结构的正确框架。

命令设计:从脚手架到构建部署

提案规划了四条命令的「新增 / 改造」,下表梳理了提案原始设计,并结合仓库内 quickstart.md 与 scaffolding.md 中记录的现代等价用法:

提案命令(v0.x 时代) 职责 现代等价用法(本仓库文档)
operator-sdk new <project-name> --type ansible --kind <kind> --api-version <group/version> 生成 Ansible 型项目骨架 operator-sdk init --plugins ansible --domain example.com
operator-sdk generate crd <api-version> <kind> [--defaults-file <path>] 为新增的 CRD 生成定义 operator-sdk create api --group <g> --version <v> --kind <K> --generate-role / --generate-playbook;追加 API 用 operator-sdk add api
operator-sdk up local 本地运行 Operator(以包含 Ansible Operator 代码的 operator-sdk 二进制作为 Operator 进程) make run(本地)、make deploy IMG=...(集群内)
operator-sdk build <image-name> 构建 Operator 镜像 make docker-build docker-push IMG="example.com/memcached-operator:v0.0.1"

项目生成与目录结构

提案中 operator-sdk new ... --type ansible 命令在底层触发一系列生成动作:

  1. 在 roles 目录下创建新的 Ansible Role;
  2. 创建 watchers.yaml 文件,Role 与 GVK 的映射按命令入参默认生成;
  3. 生成不带任何校验规则的 CRD;
  4. 基于 Ansible Operator 基础镜像、结合 watchers 文件与 Role 生成 Dockerfile。

提案给出的目标目录结构如下:

|- Dockerfile
|
|- roles
\ | - <kind>
|  \ | - generated ansible role
|
| - watchers.yaml
|
| - deploy
\  | - <kind>-CRD.yaml
|  | - rbac.yaml
|  | - operator.yaml
|  | - cr.yaml

在现代实现中,这份布局演化为 kubebuilder 风格的 config/ 目录体系(CRD 在 config/crd/bases/、样例 CR 在 config/samples/、部署清单在 config/manager/manager.yaml 与 config/default/),watches 文件仍保留在项目根目录,详见 scaffolding.md。Role 逻辑则放在 roles/<kind>/ 下,其中 tasks/main.yml 是每次调谐真正执行的"控制器逻辑"。

多 CRD 支持

提案指出,当用户希望让 Operator 同时 watch 多个 CRD 时,使用 operator-sdk generate crd <api-version> <kind> 即可基于 Ansible 代码生成新 CRD。其参数设计为:

  • 必填 kind:对象的 Kind;
  • 必填 api-version:CRD 的 <group>/<version>;
  • 可选 --defaults-file:指向用于生成新 CRD.yaml 的 defaults 文件路径;不指定则生成空 CRD。

在今天的 CLI 中,这一能力由 operator-sdk create api(首次)与 operator-sdk add api(追加)承担,并支持 --generate-playbook / --generate-role 两种控制器形态。多 CRD 场景下,每个 GVK 都可以在 watches.yaml 中获得独立的调谐配置,从而按单一职责原则拆分 Role/Playbook。

Watches 文件:CR 到 Ansible 逻辑的映射中枢

watches.yaml 是 Ansible Operator 的"路由表":它将一组由 Group / Version / Kind 标识的 CR 映射到对应的 Ansible Role 或 Playbook。Operator 期望该文件位于预定义路径 /opt/ansible/watches.yaml(容器内)。被映射的 CR 以及通过 owner reference 关联的子资源都会被监控并缓存。

核心字段

字段 类型/默认值 说明
group 必填 被 watch 的 CR 所属 group
version 必填 被 watch 的 CR 版本
kind 必填 被 watch 的 CR 的 kind
role 与 playbook 互斥 指定要执行的 Role,可传:Role 目录绝对路径;ANSIBLE_ROLES_PATH 或 ansible-roles-path 指定目录下的相对路径;当前工作目录(默认 /opt/ansible/roles)下的相对路径;已安装 Ansible Collection 的完整限定名(如 myNamespace.myCollection.myRole)
playbook 与 role 互斥 容器内 Playbook 名称,通常仅用于串联 Role;本地运行时需位于当前项目目录
vars map 任意键值对,作为 extra_vars 传给该 watch 对应的 playbook/role
reconcilePeriod 可选,默认 10h 即使没有收到被 watch 事件,也触发下一次调谐的最大间隔;格式为 Go 时长串(如 300ms、1.5h、2h45m)
manageStatus 可选,默认 true 为 true 时由 Operator 通用地管理 CR 的 status;为 false 时由 Role/Playbook 或其他控制器自行管理
blacklist 可选 按 GVK 列出不被 watch 与缓存的子资源

高级特性一览

watches 文件中每个 GVK 之下都可以继续追加高级配置键,部分特性还支持通过 CR 上的注解按资源覆盖(ansible.sdk.operatorframework.io/* 前缀):

特性 YAML 键 说明 可覆盖注解 默认值
调谐周期 reconcilePeriod 特定 CR 两次调谐之间的间隔 ansible.sdk.operatorframework.io/reconcile-period 10h
状态管理 manageStatus 是否由 Operator 管理资源 status 中的 conditions 段 — true
依赖资源 watch watchDependentResources 是否动态 watch Ansible 创建出的资源 — true
集群级资源 watch watchClusterScopedResources 是否 watch Ansible 创建的集群级资源 — false
Runner 产物上限 maxRunnerArtifacts 每个资源在容器内保留的 ansible-runner artifact 目录数量 ansible.sdk.operatorframework.io/max-runner-artifacts 20
Finalizer finalizer 在 CR 上设置 finalizer,将删除事件映射到 playbook/role — 无
标签选择器 selector 基于标签选择要调谐的对象集合 — 不应用
大小写转换 snakeCaseParameters 是否将 CR spec 的 camelCase 键转为 snake_case 后作为 extra_vars 传入 Ansible — true
注解变更 watch watchAnnotationsChanges 是否在 CR 注解变化时触发调谐 — false

完整示例

---
# 简单示例:将 Foo 映射到 Foo Role
- version: v1alpha1
  group: foo.example.com
  kind: Foo
  role: Foo

# 简单示例:将 Bar 映射到 playbook
- version: v1alpha1
  group: bar.example.com
  kind: Bar
  playbook: playbook.yml

# 复杂示例:禁用自动重新入队、由 playbook 管理 status,并附加变量
- version: v1alpha1
  group: baz.example.com
  kind: Baz
  playbook: baz.yml
  manageStatus: False
  vars:
    foo: bar

# 通过黑名单禁止 watch/cache 某类子资源
- version: v1alpha1
  group: cache.example.com
  kind: Memcached
  role: /opt/ansible/roles/memcached
  blacklist:
    - group: ""
      version: v1
      kind: ConfigMap

# 使用已安装 Ansible Collection 中的 Role
- version: v1alpha1
  group: bar.example.com
  kind: Bar
  role: myNamespace.myCollection.myRole

# 按标签过滤需要调谐的资源
- version: v1alpha1
  group: bar.example.com
  kind: Bar
  playbook: playbook.yml
  selector:
    matchLabels:
      foo: bar
    matchExpressions:
      - {key: foo, operator: In, values: [bar]}
      - {key: baz, operator: Exists, values: []}

# 多 CRD 项目:每个 GVK 独立配置
---
- version: v1alpha1
  group: app.example.com
  kind: AppService
  playbook: playbook.yml
  maxRunnerArtifacts: 30
  reconcilePeriod: 5s
  manageStatus: False
  watchDependentResources: False
  finalizer:
    name: app.example.com/finalizer
    vars:
      state: absent

- version: v1alpha1
  group: app.example.com
  kind: Database
  playbook: playbook.yml
  watchDependentResources: True
  manageStatus: True

当 reconcilePeriod、maxRunnerArtifacts 等被同时配置在 watches 文件与 CR 注解上时,注解按资源粒度覆盖文件级默认值。需要提示的是:watchDependentResources 等高级开关应谨慎使用——例如 reconcilePeriod 的典型适用场景是 watchDependentResources: False 且无法依赖 watch 机制(如管理不产生 Kubernetes 事件的集群外资源)时。

信息流与运行原理:Controller → Runner → Proxy → Ansible

information-flow-ansible-operator.md 完整记录了 Ansible Operator 的运行时信息流,与提案中 controller / runner / proxy / events 的包划分一一对应:

Controller / Reconciler

  • 基于 NamespacedName 通过 controller-runtime 的缓存获取主资源;
  • 依据 finalizer 与 metadata.DeletionTimeStamp 判断资源是否处于删除流程:已删除且不属于本 Operator 的 finalizer 则直接退出;需要 finalizer 但对象上缺失且未删除时,先补上 finalizer 再继续;
  • 若正在管理 status,先将 CR 状态标记为 running 并继续;
  • 创建 Proxy 所需的 kubeconfig;
  • 调用 runner 包执行 Ansible,并持续监听 results channel 上回传的事件:记录日志、跟踪失败消息以及标志 playbook/role 完成的 StatusEvent;
  • 若资源已删除且存在 finalizer,则移除 finalizer、更新对象后退出;
  • 更新资源状态,标记本次运行完成。

Runner 包

  • 创建 ansible 通信所用的 socket;
  • 将 object.Spec 翻译为 Ansible 变量(camelCase → camel_case,即 watches 表中 snakeCaseParameters 的底层实现),写入 ansible-runner 目录参数;
  • 在磁盘上创建(或更新)ansible-runner 运行目录;
  • 在 goroutine 中执行 ansible-runner 命令,退出时关闭 socket 通道。

Proxy(Kubernetes API 反向代理)

  • 所有对 k8s API 的请求都经由 Proxy;
  • 在 CR 同一命名空间内创建对象时注入 owner reference;
  • 在 CR 命名空间之外创建对象时注入 operator-sdk 注解;
  • 若某类型尚未开始 watch,Proxy 会为该 controller 动态添加依赖 watch;
  • 执行 GET 时优先尝试用 informer 缓存取资源,并尝试为带有 owner reference 的类型重新挂上依赖 watch。

Ansible Runner

  • Ansible 以独立进程运行;
  • ansible-runner-http 包让 ansible-runner 在运行过程中通过 socket 持续回传事件,Controller 端则通过 channel 实时接收处理。

该运行链路的端到端示意图可参考 ao-flow.png(本仓库 website/static/ 下的官方架构图):Kubernetes 集群将事件送入 AO 容器内的 Ansible Operator Binary,Controller 调度 Runner,Runner 驱动外部 Ansible Runner 执行 playbook/role,所有写回集群的操作经 Proxy 反向代理完成 owner reference 注入。

脚手架、部署与环境变量

初始化与 Role 编写

完整走查可参考 tutorial.md,核心链路为:

mkdir memcached-operator
cd memcached-operator
operator-sdk init --plugins=ansible --domain example.com
operator-sdk create api --group cache --version v1alpha1 --kind Memcached --generate-role

生成的项目中包含:Memcached 的 CRD 与样例 CR、一个将 Memcached 资源连接到 memcached Ansible Role 的 watches.yaml、以及一个"Manager"(其调谐器即 Ansible Role/Playbook)。Role 逻辑写入 roles/memcached/tasks/main.yml,例如:

---
- name: start memcached
  kubernetes.core.k8s:
    definition:
      kind: Deployment
      apiVersion: apps/v1
      metadata:
        name: '{{ ansible_operator_meta.name }}-memcached'
        namespace: '{{ ansible_operator_meta.namespace }}'
      spec:
        replicas: "{{size}}"
        selector:
          matchLabels:
            app: memcached
        template:
          metadata:
            labels:
              app: memcached
          spec:
            containers:
            - name: memcached
              image: "docker.io/memcached:1.4.36-alpine"
              command: [memcached, -m=64, -o, modern, -v]
              ports:
                - containerPort: 11211

变量建议在 roles/memcached/defaults/main.yml 中给出默认值(如 size: 1),并同步把样例 CR config/samples/cache_v1alpha1_memcached.yaml 更新为可用的 spec。注意:由于 Kubernetes 允许 CR 携带任意字段,Role 任务本身即定义了资源的"行为规范",但为了 UX 仍建议在 CRD 中声明这些字段并给出默认值。

部署清单与卷挂载

默认 Deployment 位于 config/manager/manager.yaml,名为 controller-manager,内含单个 manager 容器,并可通过 config/default 下的补丁注入 sidecar。其中镜像名是占位符,必须通过 make deploy IMG=<IMG>(内部经 kustomize 打补丁)才能真正部署。容器中挂载于 /tmp/ansible-operator/runner 的 EmptyDir 卷用于承载 ansible-runner 的输入目录,该挂载路径不可更改,否则 Operator 将无法与 ansible-runner 通信。

关键环境变量

环境变量 说明
WATCH_NAMESPACE 指定 watch 的命名空间:空串(默认)= 所有命名空间;foo = 仅命名空间 foo;foo,bar = 逗号分隔的多命名空间列表
ANSIBLE_DEBUG_LOGS 布尔值,为 True 时将 Ansible 调谐结果输出到标准输出
ANSIBLE_ROLES_PATH Role 的父路径(多个用 : 分隔);给定 /opt/foo 与 role 名 bar,会在 /opt/foo/bar 或 /opt/foo/roles/bar 中查找;优先于 ansible-roles-path 标志
ANSIBLE_COLLECTIONS_PATH Collection 基础路径,默认 ~/.ansible/collections 或 /usr/share/ansible/collections;设 /foo 且完整限定名 example.com.bar 时,在 /foo/ansible_collections/example/com/roles/bar 下查找;优先于 --ansible-collections-path 标志
MAX_CONCURRENT_RECONCILES_<kind>_<group> 最大并发调谐数,默认等于 CPU 核数
WORKER_<kind>_<group> 已弃用,请使用 MAX_CONCURRENT_RECONCILES_<kind>_<group>

此外,ANSIBLE_* 一族的 Ansible 引擎原生环境变量(如 ANSIBLE_DEBUG、ANSIBLE_VERBOSITY)也可用于调谐 Ansible 行为,详见 Ansible 官方文档。

配套演进:状态、测试与 Helm

围绕 Ansible Operator,仓库内还有三份配套提案可以延伸阅读:

若你同时关注以 Helm Chart 而非 Ansible 驱动调谐的 Operator,可对照阅读 proposals/helm-operator.md(Helm 型 Operator 的同类提案)与本仓库 testdata/helm/memcached-operator/watches.yaml 中 chart 字段的写法差异。

小结

从提案到实现,Ansible Operator 为 Operator SDK 补齐了一条完全绕开 Go 语言的技术路线:ansible 插件类型标记项目 → 脚手架生成 Role/Playbook 与 watches.yaml → 以 kubernetes.core.k8s 等模块编写调谐逻辑 → Controller + Runner + Proxy 三件套驱动 Ansible 执行并回写集群。其核心价值在于:运维人员可以把既有的 Ansible 自动化资产直接复用为 Operator 的调谐逻辑,而 Go 开发者也可以通过公开的 runner 包在自研 Operator 中嵌入 Ansible 能力。理解 proposals/ansible-operator.md 中规划的包结构与命令骨架,再结合本仓库 watches 参考文档、脚手架参考 与 信息流文档 即可完整掌握这门技术。

登录后查看全文
operator-sdk