云原生后端开发工具微服务【免费下载链接】operator-sdkSDK for building Kubernetes applications. Provides high level APIs, useful abstractions, and project scaffolding.项目地址https://gitcode.com/gh_mirrors/op/operator-sdk点击查看免费下载本指南以 proposals/ansible-operator-status.md 提案为骨架结合 Operator SDK 仓库中的开发者指南development-tips.md、watches 配置参考reference/watches.md与升级指南version-upgrade-guide.md等文档系统讲解 Ansible Operator 如何将自定义状态写入 Custom ResourceCR的status字段。读完本文你将掌握k8s_statusAnsible 模块的完整用法、watches.yaml中manageStatus字段的语义、operator 内置状态管理Running/Successful/Failed 条件的工作原理以及 CRD 未启用 status 子资源时的两种处理策略。该提案状态标记为implemented已实现提案中的设计已全部落地为真实功能Ansible Operator 能够以通用方式从 Ansible 代码中向上层暴露基本信息——既可以设置conditions也可以在运行失败时暴露失败信息。问题背景Ansible 侧为何无法管理 status在提案提出之前Ansible Operator 存在一个明显的能力缺口没有一种受支持的方式让用户在 Ansible 侧主动向 CR 的status对象写入自定义信息。默认情况下Operator 会在每次 Ansible 运行结束后将本次运行的通用输出成功/失败任务数量、错误信息等写入 CR 的status子资源。如果用户希望把自己的自定义信息暴露到 status 中唯一的办法是修改 operator 的 Go 代码——这对于以 Ansible 为主要开发语言的用户来说门槛过高也违背了 Ansible Operator以 Ansible 为主的设计初衷。提案将用户的诉求归纳为两种典型的使用场景approach混合模式用户希望在一次 Ansible 调和reconciliation运行过程中修改 CR 的 status但同时仍然希望复用 operator 内置的状态管理工具来设置特定的conditions与失败信息failure messages。完全托管模式用户希望完全从 Ansible 侧手动管理整个 status而 Ansible Operator 的 Go 侧对 status 不做任何处理。这两种场景对应两种不同的配置与编码方式下文将分别展开。提案核心两项设计针对上述问题提案给出了两项配套设计二者组合使用即可覆盖两种使用场景在watches.yaml条目中新增一个字段用于告知 operator 是否允许它管理 status即manageStatus新增一个名为k8s_status的 Ansible 模块可在 Ansible Operator 运行时环境内直接使用。其中k8s_status模块接收apiVersion、kind、name、namespace以及一段 status 内容status blob和一组 conditions 列表随后模块将这段内容写入指定资源的 status并在写入前对 conditions 进行校验使其符合 Kubernetes API 约定typical status properties中关于 conditions 字段的规范如type、status、reason、message、lastTransitionTime等字段的语义。完成校验后模块调用 status 子资源的更新接口写入该资源——被更新的资源应当就是正在被调和的 CR。设计备注提案中明确指出k8s_status模块很可能继承自k8s_common并复用与其他 k8s 模块相同的一套通用认证authentication等选项。这一推断后来成为现实——在 version-upgrade-guide.md 中记录了k8s_status最终被抽取并交由operator_sdk.utilAnsible collection 提供用户可通过operator_sdk.util.k8s_status全限定集合名FQCN直接调用。默认状态管理operator 写入的 status 长什么样在深入了解自定义状态之前先看 operator 默认写入的 status 结构。根据 development-tips.md 的Custom Resource Status Management一节默认情况下 Ansible Operator 会把上一次 Ansible 运行的通用输出写入 CR 的status子资源内容包括成功/失败任务数量与相关错误信息status: conditions: - ansibleResult: changed: 3 completion: 2018-12-03T13:45:57.13329 failures: 1 ok: 6 skipped: 0 lastTransitionTime: 2018-12-03T13:45:57Z message: Status code was -1 and not [200]: Request failed: urlopen error [Errno 113] No route to host reason: Failed status: True type: Failure - lastTransitionTime: 2018-12-03T13:46:13Z message: Running reconciliation reason: Running status: True type: Running从上面的示例可以看到默认 status 由一组conditions组成其中ansibleResult记录了最近一次运行的任务统计changed变更任务数、ok成功任务数、failures失败任务数、skipped跳过任务数以及completion完成时间戳每个 condition 均遵循 Kubernetes conditions 惯例包含type、status、reason、message、lastTransitionTime字段。在 tutorial.md 中可以看到一个真实的运行结果调和成功后status: conditions: - ansibleResult: changed: 0 completion: 2021-03-17T19:54:54.890394 failures: 0 ok: 1 skipped: 0 lastTransitionTime: 2021-03-17T19:54:42Z message: Awaiting next reconciliation reason: Successful status: True type: Running这说明 operator 在调和成功后以reason: Successful、message: Awaiting next reconciliation标记当前状态并等待下一次调和reconcile period、依赖资源 watch 触发或资源被更新。Operator 使用的三类核心 conditions根据 development-tips.mdAnsible Operator 在调和过程中使用的主要 conditions 只有少数几类RunningAnsible Operator 当前正在为调和运行 AnsibleSuccessful本次运行结束且没有错误时operator 被标记为 Successful随后等待下一次调和动作——触发来源可以是调和周期reconcile period、依赖资源 watch 触发或资源被更新Failed调和运行过程中出现任何错误时operator 被标记为 Failed并携带导致该条件的错误信息错误信息是本次调和 Ansible 运行的原始输出。如果失败是间歇性的通常在 operator 重新运行调和循环后即可恢复。自定义状态写入k8s_status模块使用详解development-tips.md 中详细说明了k8s_status模块的用法。该模块随operator_sdk.utilcollection 一并提供允许你在 Ansible 中按任意键值对更新 CR 的status。方式一使用全限定集合名FQCN调用最直接的调用方式是使用全限定集合名operator_sdk.util.k8s_status。下面的例子向status子资源写入键memcached、值bar- operator_sdk.util.k8s_status: api_version: app.example.com/v1 kind: Memcached name: {{ ansible_operator_meta.name }} namespace: {{ ansible_operator_meta.namespace }} status: foo: bar注意这里的name与namespace均取自ansible_operator_meta变量——这是 operator 自动注入每个 Ansible 运行环境的一组元数据变量。方式二在 role 的 meta 中声明 collection 后直接调用Collections 可以在 role 的meta/main.yml中声明新脚手架生成的 Ansible operator 默认包含该声明collections: - operator_sdk.util在 role meta 中声明 collection 后即可直接调用k8s_status模块- k8s_status: snip status: foo: bar方式三在 playbook 中使用version-upgrade-guide.md 补充了在 playbook 中的用法——在 play 级别声明 collection- hosts: all collections: - operator_sdk.util tasks: - k8s_status: api_version: app.example.com/v1 kind: Foo name: {{ meta.name }} namespace: {{ meta.namespace }} status: foo: bar或者不声明 collection直接使用全限定名- operator_sdk.util.k8s_status: api_version: app.example.com/v1 kind: Foo name: {{ meta.name }} namespace: {{ meta.namespace }} status: foo: bar参数速览参数必填说明api_version是目标 CR 的 API 版本如app.example.com/v1kind是目标 CR 的 Kind如Memcachedname是目标 CR 的名称通常取自ansible_operator_meta.namenamespace是目标 CR 所在的命名空间通常取自ansible_operator_meta.namespacestatus是要写入 status 子资源的任意键值对status blobconditions否符合 Kubernetes API 约定的 conditions 列表写入前会经过校验关于ansible_operator_meta与 extra vars要正确使用上述模块理解 operator 向 Ansible 注入的变量结构很重要。根据 development-tips.md 的Extra vars sent to Ansible一节operator 会把 CR 的spec部分按键值对作为 extra vars 传给 Ansible等价于向ansible-playbook传入 extra vars并在ansible_operator_meta字段下注入 CR 的名称与命名空间。对于如下 CRapiVersion: cache.example.com/v1alpha1 kind: Memcached metadata: name: memcached-sample spec: message: Hello world 2 newParameter: newParamAnsible 收到的 extra vars 结构为{ ansible_operator_meta: { name: cr-name, namespace: cr-namespace, }, message: Hello world 2, new_parameter: newParam, _app_example_com_database: { Full CR }, _app_example_com_database_spec: { Full CR .spec }, }其中message、newParameter作为顶层额外变量传入camelCase默认被转换为snake_case即new_parameter可通过snakeCaseParameters配置关闭ansible_operator_meta提供 CR 的元数据可通过点号dot notation在 Ansible 中访问--- - debug: msg: name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}在 tutorial.md 与 testing-guide.md 中可以看到ansible_operator_meta.name/ansible_operator_meta.namespace在真实任务与测试中的典型用法例如创建以 CR 命名的 Deployment 或 ConfigMap。关闭内置状态管理manageStatus配置详解如果不想让 operator 用 Ansible 运行输出去更新 status而是希望由你的应用role/playbook 或独立 controller完全手动维护 CR 的 status可以在watches.yaml中为该 GVK 设置manageStatus- version: v1 group: api.example.com kind: Memcached role: memcached manageStatus: false字段语义与默认值根据 reference/watches.md 的说明manageStatus可选为true默认值时operator 以通用方式管理 CR 的 status设为false时CR 的 status 由其他地方管理——即由指定的 role/playbook 或独立的 controller 负责。该文档还以表格形式汇总了各可配置特性Feature及其默认值其中 Manage Status 一栏为FeatureYaml KeyDescriptionAnnotation for overridedefaultManage StatusmanageStatus允许 ansible operator 管理每个资源 status 部分中的 conditions 段无true注意与reconcilePeriod可用ansible.sdk.operatorframework.io/reconcile-period注解按 CR 覆盖不同manageStatus没有提供注解级的按资源覆盖能力只能在watches.yaml中按 GVK 配置。watches.yaml 完整示例reference/watches.md 给出了一个综合示例其中Baz类型关闭了状态管理并在 playbook 中自行处理 status同时携带额外变量--- # Simple example mapping Foo to the Foo role - version: v1alpha1 group: foo.example.com kind: Foo role: Foo # Simple example mapping Bar to a playbook - version: v1alpha1 group: bar.example.com kind: Bar playbook: playbook.yml # More complex example for our Baz kind # Here we will disable requeuing and be managing the CR status in the playbook, # and specify additional variables. - version: v1alpha1 group: baz.example.com kind: Baz playbook: baz.yml manageStatus: False vars: foo: bar # ConfigMaps owned by a Memcached CR will not be watched or cached. - version: v1alpha1 group: cache.example.com kind: Memcached role: /opt/ansible/roles/memcached blacklist: - group: version: v1 kind: ConfigMap在同时管理多个 API 类型时可以为不同的 GVK 配置不同的状态管理策略例如AppService关闭、Database保持开启--- - 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: Truewatches 文件中每条映射还支持selector基于标签的对象筛选等高级配置详情见 reference/watches.md 与 reference/dependent-watches.md。Go 侧的两处必要改动提案要求 Ansible Operator 的 Go 侧做出两处调整这两处改动是保证托管/非托管两种模式正确性的关键当watches.yaml指示不管理 status 时Go 侧不得尝试管理 status——即manageStatus: false时operator 跳过内置的 status 写入逻辑把 status 完全交给 Ansible role/playbook 或外部 controller在每次 Ansible 调和运行结束后更新 status 之前先GET对象的最新状态——这是为了避免写入对象的过期版本stale version。由于调和过程可能耗时较长期间对象可能已被其他组件更新如 resourceVersion 变化若直接基于调和开始时缓存的旧对象写回 status可能覆盖其他变更或触发冲突先 GET 再更新可确保基于最新 resourceVersion 写入。边界情况CRD 未启用 status 子资源时怎么办提案还讨论了兼容性边界并非所有集群和所有 CRD 都启用了 status 子资源。对于 CRD 未启用 status 子资源的情况可以采取两种策略之一直接报错Error out如果用户试图管理一个未启用子资源的对象的 status将其视为配置错误misconfiguration不做任何更新尝试并直接失败。该策略的好处是行为明确、易于排查——配置错误会立即暴露而不是静默失败回退到整对象 PUT如果资源未启用 status 子资源status 字段仍然可以更新只是不能走子资源路径。此时应GET资源的当前状态手动更新其中的 status 字段然后PUT整个对象写回。实操提示由于kubectl、client-go 等工具对启用了 status 子资源的资源默认只允许通过status子资源更新 status因此在实际项目中建议优先确认 CRD 是否启用了subresources.status若未启用则需要采用整对象 PUT 的方式或先在 CRD 上启用 status 子资源。这一取舍在提案中保留为Complications / Further Discussion章节属于需要按集群实际环境决策的运维细节。提案落地情况与升级注意事项如前所述该提案状态为implemented提案中的设计已在后续版本中全面落地。对于从旧版本升级的用户version-upgrade-guide.md 记录了关键的破坏性变更k8s_status模块被抽取改由operator_sdk.utilAnsible collection 提供。升级后旧的直接调用方式例如不带集合名的k8s_status需要改为新用法在 role 的meta/main.yaml根级声明集合collections: - operator_sdk.util在 playbook 的 play 级声明集合或直接使用全限定名operator_sdk.util.k8s_status。此外为支持 collectionsinit 项目中的 Ansible 版本也从2.6升级到了2.9升级时需同步更新meta/main.yaml。总结如何选择适合你的状态管理模式综合提案与仓库文档Ansible Operator 的状态管理能力可以归纳为一条清晰的使用决策路径默认模式manageStatus: true默认值operator 自动把 Ansible 运行结果任务统计 Running/Successful/Failed 条件写入 status若希望在默认基础上补充自定义信息在 role/playbook 中调用operator_sdk.util.k8s_status或声明 collection 后直接调用k8s_status即可在调和过程中写入任意键值对完全托管模式manageStatus: falseoperator 不触碰 status由你的 Ansible 代码配合k8s_status模块或独立 controller 全权负责 status 的写入与更新边界处理当目标 CRD 未启用 status 子资源时要么将这种情况视为配置错误直接失败要么退化为GET 整对象 → 改 status → PUT 整对象的方式写回正确性保障无论哪种模式operator 都会在调和结束后先 GET 最新对象再写回 status避免覆盖并发变更导致的陈旧写入。相关文档与源码索引提案原文proposals/ansible-operator-status.md开发者指南状态管理章节website/content/en/docs/building-operators/ansible/development-tips.mdwatches 配置参考website/content/en/docs/building-operators/ansible/reference/watches.md依赖资源 watch 参考website/content/en/docs/building-operators/ansible/reference/dependent-watches.md升级指南operator_sdk.utilcollection 变更website/content/en/docs/upgrading-sdk-version/version-upgrade-guide.mdAnsible 教程真实 status 输出示例website/content/en/docs/building-operators/ansible/tutorial.md赞分享云原生后端开发工具微服务【免费下载链接】operator-sdkSDK for building Kubernetes applications. Provides high level APIs, useful abstractions, and project scaffolding.项目地址https://gitcode.com/gh_mirrors/op/operator-sdk点击查看免费下载相关推荐BitcoinCoreBrute部署指南在Windows、Mac和Linux上安装配置终极教程 BitcoinCoreBrute部署指南在Windows、Mac和Linux上安装配置终极教程 想要恢复丢失的比特币钱包密码BitcoinCoreBr云原生后端开发工具微服务如何快速部署ComfyUI-WanVideoWrapper终极AI视频生成插件实战指南如何快速部署ComfyUI WanVideoWrapper终极AI视频生成插件实战指南 ComfyUI WanVideoWrapper是WanVideo系列模云原生后端开发工具微服务如何使用CocoaPods-Rome快速生成动态框架完整安装与配置指南如何使用CocoaPods Rome快速生成动态框架完整安装与配置指南 CocoaPods Rome是一款强大的CocoaPods插件能够帮助开发者轻松生成上一篇OpCore-Simplify200 配置项自动决策从 0 到首次引导下一篇Flet flet-ads 广告同意参数解析ConsentRequestParameters 的字段、调试设置与 UMP 接入实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考