使用打包镜像 - 开发 Operators | Operators | OpenShift Dedicated

打包 Operator
使用 Operator Lifecycle Manager 部署 Operator
发布包含打包 Operator 的目录
测试 Operator Lifecycle Manager 上的 Operator 升级
控制 Operator 与 OpenShift Dedicated 版本的兼容性
其他资源

您可以使用 Operator SDK 以 bundle 格式打包、部署和升级 Operator，以便在 Operator Lifecycle Manager (OLM) 上使用。

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

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

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

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

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

打包 Operator

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

先决条件

在开发工作站上安装 Operator SDK CLI
安装 OpenShift CLI (oc) v+
使用 Operator SDK 初始化 Operator 项目
如果您的 Operator 是基于 Go 的，则必须更新您的项目以使用受支持的镜像在 OpenShift Dedicated 上运行

步骤

在您的 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 bundle 清单，该命令将调用多个命令，包括 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，则版本为 1.16.0 或更高版本，例如 OpenShift Dedicated）。
使用具有 dedicated-admin 权限的帐户，使用 oc 登录到集群。
如果您的 Operator 是基于 Go 的，则必须更新您的项目以使用受支持的镜像在 OpenShift Dedicated 上运行

步骤

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

$ 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` 作为默认索引镜像。如果您指定镜像，则该命令使用捆绑包镜像本身作为索引镜像。

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

此命令执行以下操作：

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

其他资源

基于文件的目录在 Operator Framework 打包格式中
基于文件的目录在管理自定义目录中
捆绑包格式

发布包含捆绑 Operator 的目录

为了安装和管理 Operator，Operator Lifecycle Manager (OLM) 要求 Operator 捆绑包列在索引镜像中，该镜像由集群上的目录引用。作为 Operator 作者，您可以使用 Operator SDK 创建一个包含您 Operator 及其所有依赖项的捆绑包的索引。这对于在远程集群上进行测试和发布到容器注册表很有用。

Operator SDK 使用 opm CLI 来促进索引镜像的创建。无需 opm 命令的使用经验。对于高级用例，可以直接使用 opm 命令，而不是 Operator SDK。

先决条件

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

步骤

在您的 Operator 项目目录中运行以下 make 命令以构建包含您的 Operator 捆绑包的索引镜像：
```
$ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>
```
其中 CATALOG_IMG 参数引用您有权访问的存储库。您可以在 Quay.io 等存储库站点获取用于存储容器的帐户。

将构建的索引镜像推送到存储库。

$ make catalog-push CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>

如果您希望一次按顺序执行多个操作，则可以一起使用 Operator SDK make 命令。例如，如果您尚未为您的 Operator 项目构建捆绑包镜像，则可以使用以下语法构建和推送捆绑包镜像和索引镜像：

$ make bundle-build bundle-push catalog-build catalog-push \
    BUNDLE_IMG=<bundle_image_pull_spec> \
    CATALOG_IMG=<index_image_pull_spec>

或者，您可以在您的 Makefile 中将 IMAGE_TAG_BASE 字段设置为现有存储库。

IMAGE_TAG_BASE=quay.io/example/my-operator

然后，您可以使用以下语法构建和推送具有自动生成的名称的镜像，例如捆绑包镜像的 quay.io/example/my-operator-bundle:v0.0.1 和索引镜像的 quay.io/example/my-operator-catalog:v0.0.1。

$ make bundle-build bundle-push catalog-build catalog-push

定义一个引用您刚刚生成的索引镜像的 CatalogSource 对象，然后使用 oc apply 命令或 Web 控制台创建该对象。

CatalogSource YAML 示例

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: cs-memcached
  namespace: <operator_namespace>
spec:
  displayName: My Test
  publisher: Company
  sourceType: grpc
  grpcPodConfig:
    securityContextConfig: <security_mode> (1)
  image: quay.io/example/memcached-catalog:v0.0.1 (2)
  updateStrategy:
    registryPoll:
      interval: 10m

1	指定 `legacy` 或 `restricted` 的值。如果未设置该字段，则默认值为 `legacy`。在未来的 OpenShift Dedicated 版本中，计划将默认值设置为 `restricted`。如果您的目录无法以 `restricted` 权限运行，建议您手动将此字段设置为 `legacy`。
2	将 `image` 设置为您之前使用 `CATALOG_IMG` 参数的镜像拉取规范。

检查目录源。

$ oc get catalogsource

示例输出

NAME           DISPLAY     TYPE   PUBLISHER   AGE
cs-memcached   My Test     grpc   Company     4h31m

验证

使用您的目录安装 Operator。

定义一个 OperatorGroup 对象，并使用 oc apply 命令或 Web 控制台创建它。

OperatorGroup YAML 示例

apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: my-test
  namespace: <operator_namespace>
spec:
  targetNamespaces:
  - <operator_namespace>

定义一个 Subscription 对象，并使用 oc apply 命令或 Web 控制台创建它。

Subscription YAML 示例

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: catalogtest
  namespace: <catalog_namespace>
spec:
  channel: "alpha"
  installPlanApproval: Manual
  name: catalog
  source: cs-memcached
  sourceNamespace: <operator_namespace>
  startingCSV: memcached-operator.v0.0.1

验证已安装的 Operator 是否正在运行。

检查 Operator 组。

$ oc get og

示例输出

NAME             AGE
my-test           4h40m

检查集群服务版本 (CSV)。

$ oc get csv

示例输出

NAME                        DISPLAY   VERSION   REPLACES   PHASE
memcached-operator.v0.0.1   Test      0.0.1                Succeeded

检查 Operator 的 Pod。

$ oc get pods

示例输出

NAME                                                              READY   STATUS      RESTARTS   AGE
9098d908802769fbde8bd45255e69710a9f8420a8f3d814abe88b68f8ervdj6   0/1     Completed   0          4h33m
catalog-controller-manager-7fd5b7b987-69s4n                       2/2     Running     0          4h32m
cs-memcached-7622r                                                1/1     Running     0          4h33m

其他资源

有关更高级用例中 opm CLI 的直接用法的详细信息，请参阅管理自定义目录。

测试 Operator Lifecycle Manager 上的 Operator 升级

您可以使用 Operator SDK 中的 Operator Lifecycle Manager (OLM) 集成快速测试升级您的 Operator，无需手动管理索引镜像和目录源。

run bundle-upgrade 子命令会自动触发已安装的 Operator 升级到更高版本，方法是指定更高版本的 bundle 镜像。

先决条件

使用 OLM 安装的 Operator，无论是使用 run bundle 子命令还是通过传统的 OLM 安装方式。
代表已安装 Operator 的更高版本的 bundle 镜像。

步骤

如果您的 Operator 尚未使用 OLM 安装，请使用 run bundle 子命令或通过传统的 OLM 安装方式安装早期版本。

如果早期版本的 bundle 是使用 OLM 传统方式安装的，则您打算升级到的较新 bundle 不得存在于目录源引用的索引镜像中。否则，运行 run bundle-upgrade 子命令将导致 registry pod 失败，因为较新的 bundle 已经被提供包和集群服务版本 (CSV) 的索引引用。

例如，您可以为 Memcached Operator 使用以下 run bundle 子命令，并指定早期 bundle 镜像。

$ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1

示例输出

INFO[0006] Creating a File-Based Catalog of the bundle "quay.io/demo/memcached-operator:v0.0.1"
INFO[0008] Generated a valid File-Based Catalog
INFO[0012] Created registry pod: quay-io-demo-memcached-operator-v1-0-1
INFO[0012] Created CatalogSource: memcached-operator-catalog
INFO[0012] OperatorGroup "operator-sdk-og" created
INFO[0012] Created Subscription: memcached-operator-v0-0-1-sub
INFO[0015] Approved InstallPlan install-h9666 for the Subscription: memcached-operator-v0-0-1-sub
INFO[0015] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase
INFO[0015] Waiting for ClusterServiceVersion ""my-project/memcached-operator.v0.0.1" to appear
INFO[0026] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Pending
INFO[0028] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Installing
INFO[0059] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
INFO[0059] OLM has successfully installed "memcached-operator.v0.0.1"

通过指定更高版本 Operator 的 bundle 镜像来升级已安装的 Operator。

$ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2

示例输出

INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project
INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project
INFO[0008] Generated a valid Upgraded File-Based Catalog
INFO[0009] Created registry pod: quay-io-demo-memcached-operator-v0-0-2
INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations
INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1"
INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub
INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase
INFO[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Pending
INFO[0042] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady
INFO[0043] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing
INFO[0044] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded
INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2"

清理已安装的 Operators。

$ operator-sdk cleanup memcached-operator

其他资源

使用 OLM 进行传统的 Operator 安装。

控制 Operator 与 OpenShift Dedicated 版本的兼容性

Kubernetes 定期弃用某些 API，这些 API 在后续版本中将被移除。如果您的 Operator 使用的是已弃用的 API，则在 OpenShift Dedicated 集群升级到已移除该 API 的 Kubernetes 版本后，它可能无法正常工作。

作为 Operator 作者，强烈建议您查看 Kubernetes 文档中的已弃用 API 迁移指南，并保持您的 Operator 项目最新，以避免使用已弃用和已移除的 API。理想情况下，您应该在未来版本的 OpenShift Dedicated 发布之前更新您的 Operator，这些版本将使 Operator 不兼容。

当从 OpenShift Dedicated 版本中移除 API 时，在该集群版本上运行且仍在使用已移除 API 的 Operator 将无法正常工作。作为 Operator 作者，您应该计划更新您的 Operator 项目以适应 API 的弃用和移除，以避免对您的 Operator 用户造成中断。

您可以检查 Operator 的事件警报，以查找是否有任何关于当前正在使用的 API 的警告。当检测到将在下一个版本中移除的 API 时，会触发以下警报。

APIRemovedInNextReleaseInUse: 将在下一个 OpenShift Dedicated 版本中移除的 API。
APIRemovedInNextEUSReleaseInUse: 将在下一个 OpenShift Dedicated 扩展更新支持 (EUS) 版本中移除的 API。

如果集群管理员已安装您的 Operator，则在他们升级到下一个 OpenShift Dedicated 版本之前，必须确保安装了与下一个集群版本兼容的 Operator 版本。虽然建议您更新您的 Operator 项目以不再使用已弃用或已移除的 API，但如果您仍然需要发布包含已移除 API 的 Operator bundle 以继续在早期版本的 OpenShift Dedicated 上使用，请确保相应地配置 bundle。

以下步骤有助于防止管理员在与 OpenShift Dedicated 版本不兼容的版本上安装您的 Operator。这些步骤还可以防止管理员升级到与当前安装在其集群上的 Operator 版本不兼容的较新版本的 OpenShift Dedicated。

当您知道当前版本的 Operator 由于任何原因在特定 OpenShift Dedicated 版本上无法正常工作时，此步骤也很有用。通过定义应分发 Operator 的集群版本，您可以确保 Operator 不出现在允许范围之外的集群版本的目录中。

使用已弃用 API 的 Operator 在集群管理员升级到不再支持该 API 的未来版本的 OpenShift Dedicated 时，可能会对关键工作负载产生不利影响。如果您的 Operator 使用的是已弃用的 API，则应尽快在您的 Operator 项目中配置以下设置。

先决条件

现有的 Operator 项目

步骤

如果您知道您的 Operator 的特定 bundle 不受支持，并且在 OpenShift Dedicated 版本高于某个特定集群版本时无法正常工作，请配置您的 Operator 兼容的 OpenShift Dedicated 的最大版本。在您的 Operator 项目的集群服务版本 (CSV) 中，设置 olm.maxOpenShiftVersion 注解以防止管理员在将已安装的 Operator 升级到兼容版本之前升级其集群。

只有当您的 Operator bundle 版本无法在更高版本中工作时，才必须使用 olm.maxOpenShiftVersion 注解。请注意，集群管理员无法升级安装了您的解决方案的集群。如果您不提供更高版本和有效的升级路径，管理员可能会卸载您的 Operator 并升级集群版本。

包含 olm.maxOpenShiftVersion 注解的 CSV 示例

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  annotations:
    "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' (1)

1	指定您的 Operator 兼容的 OpenShift Dedicated 的最大集群版本。例如，将 `value` 设置为 `4.9` 将防止在将此 bundle 安装在集群上时升级到高于 4.9 的 OpenShift Dedicated 版本。

如果您的 bundle 旨在在 Red Hat 提供的 Operator 目录中分发，请通过设置以下属性来配置您的 Operator 的兼容 OpenShift Dedicated 版本。此配置确保您的 Operator 仅包含在针对兼容版本的 OpenShift Dedicated 的目录中。

此步骤仅在 Red Hat 提供的目录中发布 Operator 时有效。如果您的 bundle 仅旨在在自定义目录中分发，则可以跳过此步骤。有关更多详细信息，请参阅“Red Hat 提供的 Operator 目录”。

在项目 bundle/metadata/annotations.yaml 文件中设置 com.redhat.openshift.versions 注解。
包含兼容版本的 bundle/metadata/annotations.yaml 文件示例
```
com.redhat.openshift.versions: "v4.7-v4.9" (1)
```
1 设置为范围或单个版本。
为了防止您的 bundle 被带到与 OpenShift Dedicated 不兼容的版本，请确保使用正确的 com.redhat.openshift.versions 标签在您的 Operator 的 bundle 镜像中生成索引镜像。例如，如果您的项目是使用 Operator SDK 生成的，请更新 bundle.Dockerfile 文件。
包含兼容版本的 bundle.Dockerfile 示例
```
LABEL com.redhat.openshift.versions="<versions>" (1)
```
1 设置为范围或单个版本，例如 v4.7-v4.9。此设置定义了应分发 Operator 的集群版本，并且 Operator 不会出现在范围之外的集群版本的目录中。

您现在可以打包您的 Operator 的新版本并将更新的版本发布到目录以进行分发。

其他资源

有关 bundle 格式的详细信息，请参阅Operator Framework 打包格式。
有关使用 opm 命令将 bundle 镜像添加到索引镜像的详细信息，请参阅管理自定义目录。
有关已安装 Operator 的升级工作方式的详细信息，请参阅Operator Lifecycle Manager 工作流程。