基于 Operator SDK 构建 Ansible Operator:提案设计、包结构、命令与 Watches 配置全解析
基于 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 → 构建部署"的完整链路。
背景与目标:为什么 Operator SDK 需要 Ansible
提案开篇点明了引入 Ansible Operator 的两个核心原因:
- 开发者门槛:并非所有人都是 Go 开发者,Operator SDK 的采用率受限于 Go 开发者数量。而 Kubernetes 生态中其他语言(如 Python、Ruby)在 informer、cache、lister 等机制上的工具链支持较弱,直接复刻 controller-runtime 的能力成本极高。
- 运维范式契合: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 命令在底层触发一系列生成动作:
- 在
roles目录下创建新的 Ansible Role; - 创建
watchers.yaml文件,Role 与 GVK 的映射按命令入参默认生成; - 生成不带任何校验规则的 CRD;
- 基于 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,仓库内还有三份配套提案可以延伸阅读:
- proposals/ansible-operator-status.md:探讨 Ansible Operator 中 CR status 的通用管理模型(即 watches 表中
manageStatus的由来); - proposals/ansible-operator-testing.md:为 Ansible 型 Operator 设计测试与验证方案;
- proposals/ansible-helm-addapi.md:在 Ansible/Helm 型项目中扩展
add api的能力。
若你同时关注以 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 参考文档、脚手架参考 与 信息流文档 即可完整掌握这门技术。
