教程 - 开发 Operator | Operators | OpenShift Dedicated

先决条件
创建项目
- PROJECT 文件
创建 API
修改管理器
启用代理支持
运行操作符
- 捆绑操作符并使用 Operator Lifecycle Manager 部署
创建自定义资源
其他资源

操作符开发人员可以利用 Operator SDK 中的 Ansible 支持来构建一个基于 Ansible 的 Memcached（一个分布式键值存储）操作符示例，并管理其生命周期。本教程将逐步介绍以下流程

创建 Memcached 部署
确保部署大小与 Memcached 自定义资源 (CR) 规范中指定的大小相同
使用状态写入器更新 Memcached CR 状态，其中包含 memcached Pod 的名称

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

不建议使用 Red Hat 支持的 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)。

此流程是通过使用 Operator Framework 的两个核心组件来实现的

Operator SDK: operator-sdk CLI 工具和 controller-runtime 库 API
Operator Lifecycle Manager (OLM): 在集群上安装、升级和基于角色的访问控制 (RBAC) 操作符

本教程比 OpenShift Container Platform 文档中的基于 Ansible 的操作符的 Operator SDK 入门指南提供了更详细的信息。

先决条件

已安装 Operator SDK CLI
已安装 OpenShift CLI (oc)
Ansible 2.15.0
Ansible Runner 2.3.3+
Ansible Runner HTTP 事件发射器插件 1.0.0+
Python 3.9+
Python Kubernetes 客户端
使用具有 dedicated-admin 权限的帐户通过 oc 登录到 OpenShift Dedicated 集群
要允许集群拉取镜像，您推送镜像的存储库必须设置为公共的，或者您必须配置镜像拉取密钥

其他资源

创建项目

使用 Operator SDK CLI 创建一个名为 memcached-operator 的项目。

步骤

为项目创建一个目录

$ mkdir -p $HOME/projects/memcached-operator

切换到该目录
```
$ cd $HOME/projects/memcached-operator
```

使用 ansible 插件运行 operator-sdk init 命令来初始化项目

$ operator-sdk init \
    --plugins=ansible \
    --domain=example.com

PROJECT 文件

operator-sdk init 命令生成的的文件中包含一个 Kubebuilder PROJECT 文件。从项目根目录运行的后续 operator-sdk 命令以及 help 输出都会读取此文件，并知道项目类型为 Ansible。例如

domain: example.com
layout:
- ansible.sdk.operatorframework.io/v1
plugins:
  manifests.sdk.operatorframework.io/v2: {}
  scorecard.sdk.operatorframework.io/v2: {}
  sdk.x-openshift.io/v1: {}
projectName: memcached-operator
version: "3"

创建 API

使用 Operator SDK CLI 创建一个 Memcached API。

步骤

运行以下命令创建一个具有组 cache、版本 v1 和种类 Memcached 的 API

$ operator-sdk create api \
    --group cache \
    --version v1 \
    --kind Memcached \
    --generate-role (1)

1	生成 API 的 Ansible 角色。

创建 API 后，您的 Operator 项目将更新为以下结构

Memcached CRD

包含一个 Memcached 资源示例

管理器

通过使用以下方法协调集群状态与期望状态的程序：

一个协调器，可以是 Ansible 角色或剧本
一个 watches.yaml 文件，它将 Memcached 资源连接到 memcached Ansible 角色

修改管理器

更新您的 Operator 项目以提供协调逻辑（以 Ansible 角色的形式），该逻辑在每次创建、更新或删除 Memcached 资源时都会运行。

步骤

使用以下结构更新 roles/memcached/tasks/main.yml 文件

---
- name: start memcached
  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
              command:
              - memcached
              - -m=64
              - -o
              - modern
              - -v
              image: "docker.io/memcached:1.4.36-alpine"
              ports:
                - containerPort: 11211

此 memcached 角色确保 memcached 部署存在并设置部署大小。

通过编辑 roles/memcached/defaults/main.yml 文件，为 Ansible 角色中使用的变量设置默认值
```
---
# defaults file for Memcached
size: 1
```

使用以下结构更新 config/samples/cache_v1_memcached.yaml 文件中的 Memcached 示例资源

apiVersion: cache.example.com/v1
kind: Memcached
metadata:
  labels:
    app.kubernetes.io/name: memcached
    app.kubernetes.io/instance: memcached-sample
    app.kubernetes.io/part-of: memcached-operator
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/created-by: memcached-operator
  name: memcached-sample
spec:
  size: 3

自定义资源 (CR) spec 中的键值对作为额外变量传递给 Ansible。

在运行 Ansible 之前，Operator 会将 spec 字段中所有变量的名称转换为蛇形命名法（即小写字母加下划线）。例如，spec 中的 serviceAccount 在 Ansible 中变为 service_account。

您可以通过在 watches.yaml 文件中将 snakeCaseParameters 选项设置为 false 来禁用此大小写转换。建议您在 Ansible 中对变量执行一些类型验证，以确保您的应用程序接收到的输入符合预期。

启用代理支持

Operator 作者可以开发支持网络代理的 Operator。具有 dedicated-admin 角色的管理员可以为 Operator Lifecycle Manager (OLM) 处理的环境变量配置代理支持。要支持代理集群，您的 Operator 必须检查环境中是否存在以下标准代理变量并将值传递给 Operands

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

本教程使用 HTTP_PROXY 作为环境变量示例。

先决条件

启用了集群范围出站代理的集群。

步骤

通过使用以下内容更新 roles/memcached/tasks/main.yml 文件，将环境变量添加到部署中

...
env:
   - name: HTTP_PROXY
     value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
   - name: http_proxy
     value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
...

通过将以下内容添加到 config/manager/manager.yaml 文件中，在 Operator 部署中设置环境变量

containers:
 - args:
   - --leader-elect
   - --leader-election-id=ansible-proxy-demo
   image: controller:latest
   name: manager
   env:
     - name: "HTTP_PROXY"
       value: "http_proxy_test"

运行 Operator

要构建和运行您的 Operator，请使用 Operator SDK CLI 打包您的 Operator，然后使用 Operator Lifecycle Manager (OLM) 在集群上部署。

如果您希望在 OpenShift Container Platform 集群而不是 OpenShift Dedicated 集群上部署您的 Operator，则可以使用两种额外的部署选项

在集群外部作为 Go 程序本地运行。
在集群上作为部署运行。

其他资源

在集群外部本地运行（OpenShift Container Platform 文档）
在集群上作为部署运行（OpenShift Container Platform 文档）

打包 Operator 并使用 Operator Lifecycle Manager 部署

打包 Operator

Operator 包格式是 Operator SDK 和 Operator Lifecycle Manager (OLM) 的默认打包方法。您可以使用 Operator SDK 将您的 Operator 项目构建并推送为包映像，从而使其准备好在 OLM 上使用。

先决条件

在开发工作站上安装了 Operator SDK CLI
安装了 OpenShift CLI (oc) v+
使用 Operator SDK 初始化了 Operator 项目

步骤

在您的 Operator 项目目录中运行以下 make 命令来构建和推送您的 Operator 镜像。修改以下步骤中的 IMG 参数以引用您有权访问的存储库。您可以在 Quay.io 等存储库站点获取用于存储容器的帐户。

构建镜像

$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>

SDK 为 Operator 生成的 Dockerfile 明确引用了 GOARCH=amd64 用于 go build。这可以修改为 GOARCH=$TARGETARCH 以用于非 AMD64 架构。Docker 将自动将环境变量设置为 –platform 指定的值。对于 Buildah，需要使用 –build-arg 来实现此目的。有关更多信息，请参阅多架构。

将镜像推送到存储库

$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>

通过运行 make bundle 命令创建您的 Operator 包清单，该命令将调用多个命令，包括 Operator SDK generate bundle 和 bundle validate 子命令
```
$ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>
```
Operator 的包清单描述了如何显示、创建和管理应用程序。make bundle 命令会在您的 Operator 项目中创建以下文件和目录
- 一个名为 bundle/manifests 的包清单目录，其中包含一个 ClusterServiceVersion 对象
- 一个名为 bundle/metadata 的包元数据目录
- config/crd 目录中的所有自定义资源定义 (CRD)
- 一个 Dockerfile bundle.Dockerfile
然后，这些文件将使用 operator-sdk bundle validate 自动验证，以确保磁盘上的包表示正确。
通过运行以下命令构建和推送您的包镜像。OLM 使用索引镜像使用 Operator 包，这些索引镜像引用一个或多个包镜像。
1. 构建包镜像。使用注册表、用户命名空间和您打算推送镜像的镜像标签的详细信息设置 BUNDLE_IMG
  $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
2. 推送包镜像
  $ docker push <registry>/<user>/<bundle_image_name>:<tag>

使用 Operator Lifecycle Manager 部署 Operator

Operator Lifecycle Manager (OLM) 可帮助您在 Kubernetes 集群上安装、更新和管理 Operator 及其关联服务的生命周期。OLM 在 OpenShift Dedicated 上默认安装，并作为 Kubernetes 扩展运行，因此您可以使用 Web 控制台和 OpenShift CLI (oc) 完成所有 Operator 生命周期管理功能，无需任何其他工具。

Operator 包格式是 Operator SDK 和 OLM 的默认打包方法。您可以使用 Operator SDK 快速在 OLM 上运行包镜像，以确保其正常运行。

先决条件

在开发工作站上安装了 Operator SDK CLI
已构建并推送到注册表的 Operator 包镜像
在基于 Kubernetes 的集群上安装了 OLM（如果您使用 apiextensions.k8s.io/v1 CRD，例如 OpenShift Dedicated，则为 v1.16.0 或更高版本）
使用具有 dedicated-admin 权限的帐户使用 oc 登录到集群

步骤

输入以下命令在集群上运行 Operator

$ operator-sdk run bundle \(1)
    -n <namespace> \(2)
    <registry>/<user>/<bundle_image_name>:<tag> (3)

1	`run bundle` 命令会创建一个有效的基于文件的目录，并使用 OLM 在您的集群上安装 Operator bundle。
2	可选：默认情况下，该命令会将 Operator 安装到您 `~/.kube/config` 文件中当前活动的项目中。您可以添加 `-n` 标志来设置安装的不同命名空间范围。
3	如果您没有指定镜像，则该命令使用 `quay.io/operator-framework/opm:latest` 作为默认索引镜像。如果您指定了镜像，则该命令使用 bundle 镜像本身作为索引镜像。

从 OpenShift Dedicated 4.11 开始，run bundle 命令默认支持 Operator 目录的基于文件的目录格式。已弃用的 Operator 目录的 SQLite 数据库格式仍然受支持；但是，它将在未来的版本中移除。建议 Operator 作者将他们的工作流程迁移到基于文件的目录格式。

此命令执行以下操作：

创建一个引用您的 bundle 镜像的索引镜像。索引镜像是不透明且短暂的，但准确地反映了如何在生产环境中将 bundle 添加到目录。
创建一个指向您的新索引镜像的目录源，这使 OperatorHub 能够发现您的 Operator。
通过创建 OperatorGroup、Subscription、InstallPlan 和所有其他必需的资源（包括 RBAC）来将您的 Operator 部署到您的集群。

创建自定义资源

安装 Operator 后，您可以通过创建现在由 Operator 在集群上提供的自定义资源 (CR) 来测试它。

先决条件

示例：在集群上安装的 Memcached Operator 提供了 Memcached CR。

步骤

切换到安装 Operator 的命名空间。例如，如果您使用 make deploy 命令部署了 Operator
```
$ oc project memcached-operator-system
```

编辑位于 config/samples/cache_v1_memcached.yaml 的示例 Memcached CR 清单，使其包含以下规范：

apiVersion: cache.example.com/v1
kind: Memcached
metadata:
  name: memcached-sample
...
spec:
...
  size: 3

创建 CR：

$ oc apply -f config/samples/cache_v1_memcached.yaml

确保 Memcached Operator 为示例 CR 创建了具有正确大小的部署。

$ oc get deployments

示例输出：

NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
memcached-operator-controller-manager   1/1     1            1           8m
memcached-sample                        3/3     3            3           1m

检查 Pod 和 CR 状态以确认状态已更新为 Memcached Pod 名称。

检查 Pod：

$ oc get pods

示例输出：

NAME                                  READY     STATUS    RESTARTS   AGE
memcached-sample-6fd7c98d8-7dqdr      1/1       Running   0          1m
memcached-sample-6fd7c98d8-g5k7v      1/1       Running   0          1m
memcached-sample-6fd7c98d8-m7vn7      1/1       Running   0          1m

检查 CR 状态：

$ oc get memcached/memcached-sample -o yaml

示例输出：

apiVersion: cache.example.com/v1
kind: Memcached
metadata:
...
  name: memcached-sample
...
spec:
  size: 3
status:
  nodes:
  - memcached-sample-6fd7c98d8-7dqdr
  - memcached-sample-6fd7c98d8-g5k7v
  - memcached-sample-6fd7c98d8-m7vn7

更新部署大小。

更新 config/samples/cache_v1_memcached.yaml 文件，将 Memcached CR 中的 spec.size 字段从 3 更改为 5。
```
$ oc patch memcached memcached-sample \
    -p '{"spec":{"size": 5}}' \
    --type=merge
```

确认 Operator 已更改部署大小。

$ oc get deployments

示例输出：

NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
memcached-operator-controller-manager   1/1     1            1           10m
memcached-sample                        5/5     5            5           3m

运行以下命令删除 CR：

$ oc delete -f config/samples/cache_v1_memcached.yaml

清理本教程中创建的资源。
- 如果您使用 make deploy 命令测试了 Operator，请运行以下命令：
  $ make undeploy
- 如果您使用 operator-sdk run bundle 命令测试了 Operator，请运行以下命令：
  $ operator-sdk cleanup <project_name>

其他资源

请参阅基于 Ansible 的 Operator 的项目布局，了解 Operator SDK 创建的目录结构。
如果配置了集群范围的出站代理，则具有 dedicated-admin 角色的管理员可以覆盖代理设置或为在 Operator Lifecycle Manager (OLM) 上运行的特定 Operator 注入自定义 CA 证书。

基于 Ansible 的操作符的 Operator SDK 教程

先决条件

创建项目

PROJECT 文件

创建 API

修改管理器

启用代理支持

运行 Operator

打包 Operator 并使用 Operator Lifecycle Manager 部署

打包 Operator

使用 Operator Lifecycle Manager 部署 Operator

创建自定义资源

其他资源