Ansible 支持 - 开发 Operators | Operators | OpenShift 容器平台 4.17

自定义资源文件
watches.yaml 文件
- 高级选项
发送到 Ansible 的额外变量
Ansible Runner 目录

Red Hat 支持的 Operator SDK CLI 工具版本（包括相关的脚手架和用于 Operator 项目的测试工具）已弃用，并计划在未来版本的 OpenShift Container Platform 中删除。Red Hat 将在当前发布生命周期内为此功能提供错误修复和支持，但此功能将不再接收增强功能，并将从未来的 OpenShift Container Platform 版本中删除。

不建议使用 Red Hat 支持的 Operator SDK 版本创建新的 Operator 项目。拥有现有 Operator 项目的 Operator 作者可以使用 OpenShift Container Platform 4.17 版本中发布的 Operator SDK CLI 工具版本来维护其项目并创建针对较新版本的 OpenShift Container Platform 的 Operator 版本。

以下与 Operator 项目相关的基础镜像未被弃用。这些基础镜像的运行时功能和配置 API 仍受支持，用于错误修复和解决 CVE。

基于 Ansible 的 Operator 项目的基础镜像
基于 Helm 的 Operator 项目的基础镜像

有关 OpenShift Container Platform 中已弃用或删除的主要功能的最新列表，请参阅 OpenShift Container Platform 版本说明中的“已弃用和删除的功能”部分。

有关不受支持的社区维护的 Operator SDK 版本的信息，请参阅Operator SDK (Operator Framework)。

自定义资源文件

操作员使用 Kubernetes 扩展机制，自定义资源定义 (CRD)，因此您的自定义资源 (CR) 看起来并像内置的原生 Kubernetes 对象一样运作。

CR 文件格式是一个 Kubernetes 资源文件。该对象具有必填字段和可选字段。

表 1. 自定义资源字段
字段	描述
`apiVersion`	要创建的 CR 的版本。
`kind`	要创建的 CR 的种类。
`metadata`	要创建的 Kubernetes 特定元数据。
`spec` (可选)	传递给 Ansible 的变量的键值对列表。此字段默认为空。
`status`	总结对象的当前状态。对于基于 Ansible 的操作员，`status` 子资源默认情况下已为 CRD 启用，并由`operator_sdk.util.k8s_status` Ansible 模块管理，其中包括添加到 CR `status` 的`condition` 信息。
`annotations`	要添加到 CR 的 Kubernetes 特定注释。

以下 CR 注释列表修改了操作员的行为

表 2. 基于 Ansible 的操作员注释
注释	描述
`ansible.operator-sdk/reconcile-period`	指定 CR 的协调间隔。此值使用标准 Golang 包 `time` 解析。具体来说，使用 `ParseDuration`，它应用默认后缀`s`，以秒为单位给出值。

基于 Ansible 的操作员注释示例

apiVersion: "test1.example.com/v1alpha1"
kind: "Test1"
metadata:
  name: "example"
annotations:
  ansible.operator-sdk/reconcile-period: "30s"

watches.yaml 文件

组/版本/种类 (GVK) 是 Kubernetes API 的唯一标识符。watches.yaml 文件包含从自定义资源 (CR)（由其 GVK 标识）到 Ansible 角色或 playbook 的映射列表。操作员期望此映射文件位于预定义位置/opt/ansible/watches.yaml。

表 3. `watches.yaml` 文件映射
字段	描述
`group`	要观察的 CR 的组。
`version`	要观察的 CR 的版本。
`kind`	要观察的 CR 的种类
`role` (默认)	添加到容器的 Ansible 角色的路径。例如，如果您的`roles`目录位于`/opt/ansible/roles/`，并且您的角色名为`busybox`，则此值为`/opt/ansible/roles/busybox`。此字段与`playbook`字段互斥。
`playbook`	添加到容器的 Ansible playbook 的路径。此 playbook 预计是调用角色的一种方式。此字段与`role`字段互斥。
`reconcilePeriod` (可选)	协调间隔，给定 CR 的角色或 playbook 的运行频率。
`manageStatus` (可选)	设置为`true`（默认）时，操作员以通用方式管理 CR 的状态。设置为`false`时，CR 的状态由其他地方管理，由指定的 role 或 playbook 或在单独的控制器中管理。

watches.yaml 文件示例

- version: v1alpha1 (1)
  group: test1.example.com
  kind: Test1
  role: /opt/ansible/roles/Test1

- version: v1alpha1 (2)
  group: test2.example.com
  kind: Test2
  playbook: /opt/ansible/playbook.yml

- version: v1alpha1 (3)
  group: test3.example.com
  kind: Test3
  playbook: /opt/ansible/test3.yml
  reconcilePeriod: 0
  manageStatus: false

1	将`Test1`简单映射到`test1`角色的示例。
2	将`Test2`简单映射到 playbook 的示例。
3	`Test3`种类的更复杂示例。禁用重新排队并在 playbook 中管理 CR 状态。

高级选项

可以通过将高级功能添加到每个 GVK 的watches.yaml文件中来启用它们。它们可以在group、version、kind和playbook或role字段下方。

某些功能可以使用该 CR 上的注释按资源进行覆盖。可以覆盖的选项在下面指定了注释。

表 4. 高级 watches.yaml 文件选项
功能	YAML 键	描述	用于覆盖的注释	默认值
协调周期	`reconcilePeriod`	特定 CR 的协调运行之间的时间。	`ansible.operator-sdk/reconcile-period`	`1m`
管理状态	`manageStatus`	允许操作员管理每个 CR `status` 部分的`conditions`部分。		`true`
观察依赖资源	`watchDependentResources`	允许操作员动态观察由 Ansible 创建的资源。		`true`
观察集群范围资源	`watchClusterScopedResources`	允许操作员观察由 Ansible 创建的集群范围资源。		`false`
最大运行器工件	`maxRunnerArtifacts`	管理 Ansible Runner 为每个单独的资源保存在操作员容器中的工件目录数量。	`ansible.operator-sdk/max-runner-artifacts`	`20`

包含高级选项的 watches.yml 文件示例

- version: v1alpha1
  group: app.example.com
  kind: AppService
  playbook: /opt/ansible/playbook.yml
  maxRunnerArtifacts: 30
  reconcilePeriod: 5s
  manageStatus: False
  watchDependentResources: False

发送到 Ansible 的额外变量

可以将额外变量发送到 Ansible，然后由操作员管理。自定义资源 (CR) 的spec部分将键值对作为额外变量传递。这等效于传递到ansible-playbook命令的额外变量。

操作员还在meta字段下传递 CR 的名称和 CR 的命名空间作为附加变量。

对于以下 CR 示例

apiVersion: "app.example.com/v1alpha1"
kind: "Database"
metadata:
  name: "example"
spec:
  message: "Hello world 2"
  newParameter: "newParam"

传递到 Ansible 的额外变量的结构是

{ "meta": {
        "name": "<cr_name>",
        "namespace": "<cr_namespace>",
  },
  "message": "Hello world 2",
  "new_parameter": "newParam",
  "_app_example_com_database": {
     <full_crd>
   },
}

message和newParameter字段作为顶级额外变量设置，meta提供操作员中定义的 CR 的相关元数据。可以使用点表示法在 Ansible 中访问meta字段，例如

---
- debug:
    msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"

Ansible Runner 目录

Ansible Runner 保留有关容器中 Ansible 运行的信息。它位于/tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name>。

其他资源

要了解有关runner目录的更多信息，请参阅Ansible Runner 文档。

Operator SDK 中的 Ansible 支持

自定义资源文件

watches.yaml 文件

高级选项

发送到 Ansible 的额外变量

Ansible Runner 目录