教程 - 开发 Operator | Operators | Red Hat OpenShift Service on AWS

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

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

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

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

不建议使用 Red Hat 支持的 Operator SDK 版本创建新的 Operator 项目。拥有现有 Operator 项目的 Operator 作者可以使用 Red Hat OpenShift Service on AWS 发布的 Operator SDK CLI 工具版本来维护其项目并创建针对更新版本的 Red Hat OpenShift Service on AWS 的 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) Operator

本教程比 OpenShift Container Platform 文档中的基于 Ansible 的 Operator 的 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 登录到 Red Hat OpenShift Service on AWS 集群
要允许集群拉取镜像，您推送镜像的仓库必须设置为公共仓库，或者您必须配置镜像拉取密钥

其他资源

编辑

创建项目

使用 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) 规范中的键值对作为额外变量传递给 Ansible。

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

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

编辑

启用代理支持

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

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 SDK CLI 来打包您的操作员，然后使用 Operator Lifecycle Manager (OLM) 部署到集群。

如果您希望将您的操作员部署到 OpenShift Container Platform 集群而不是 AWS 上的 Red Hat OpenShift Service 集群，则可以使用两种额外的部署选项

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

其他资源

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

编辑

打包操作员并使用 Operator Lifecycle Manager 部署

编辑

打包操作员

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

先决条件

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

步骤

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

构建镜像

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

SDK 为 Operator 生成的 Dockerfile 明确引用了用于go build的GOARCH=amd64。这可以修改为GOARCH=$TARGETARCH以用于非 AMD64 架构。Docker 将自动将环境变量设置为–platform指定的 value。对于 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 Lifecycle Manager (OLM) 可帮助您安装、更新和管理 Kubernetes 集群上操作员及其关联服务的生命周期。OLM 在 AWS 上的 Red Hat OpenShift Service 中默认安装，并作为 Kubernetes 扩展运行，因此您可以使用 Web 控制台和 OpenShift CLI (oc) 执行所有操作员生命周期管理功能，而无需任何其他工具。

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

先决条件

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

步骤

输入以下命令以在集群上运行操作员

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

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

从 AWS 上的 Red Hat OpenShift Service 4.11 开始，run bundle命令默认支持 Operator 目录的基于文件的目录格式。对 Operator 目录使用已弃用的 SQLite 数据库格式仍然受支持；但是，它将在将来的版本中删除。建议操作员作者将其工作流程迁移到基于文件的目录格式。

此命令执行以下操作

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

先决条件

创建项目

PROJECT 文件

创建 API

修改管理器

启用代理支持

运行操作员

打包操作员并使用 Operator Lifecycle Manager 部署

打包操作员

使用 Operator Lifecycle Manager 部署操作员

创建自定义资源

附加资源