Ansible 支持 - 开发 Operators | Operators | OpenShift Dedicated

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

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

不推荐使用红帽支持的 Operator SDK 版本创建新的 Operator 项目。拥有现有 Operator 项目的操作符作者可以使用 OpenShift Dedicated 发布的 Operator SDK CLI 工具版本来维护其项目并创建针对较新版本的 OpenShift Dedicated 的 Operator 发行版。

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

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

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

自定义资源文件

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

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

表 1. 自定义资源字段
字段	描述
`apiVersion`	要创建的 CR 的版本。
`kind`	要创建的 CR 的种类。
`metadata`	要创建的 Kubernetes 特定的元数据。
`spec`（可选）	传递给 Ansible 的变量的键值列表。此字段默认为空。
`status`	总结对象的当前状态。对于基于 Ansible 的操作符，`status` 子资源默认情况下由`operator_sdk.util.k8s_status` Ansible 模块启用，该模块将`condition`信息包含到 CR `status` 中。
`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 角色或剧本的映射列表。操作符期望此映射文件位于预定义位置/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 剧本的路径。此剧本应为调用角色的一种方式。此字段与`role`字段互斥。
`reconcilePeriod`（可选）	协调间隔，给定 CR 的角色或剧本运行的频率。
`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目录