OpenShift 文档正在迁移，很快将只能在 docs.redhat.com（所有 Red Hat 产品文档的中心）访问。立即体验 新的文档体验。
  1. 文档
    2. history bug_report picture_as_pdf
×

使用捆绑镜像

您可以使用Operator SDK打包、部署和升级捆绑格式的操作符，以便在Operator Lifecycle Manager (OLM)上使用。

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项目相关的基础镜像未被弃用。这些基础镜像的运行时功能和配置API仍然支持错误修复和解决CVE。

  • 基于Ansible的操作符项目的基镜像

  • 基于Helm的操作符项目的基镜像

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

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

打包操作符

操作符捆绑格式是Operator SDK和Operator Lifecycle Manager (OLM)的默认打包方法。您可以使用Operator SDK构建和推送您的Operator项目作为捆绑镜像，从而使您的Operator准备好用于OLM。

先决条件

  • 安装在开发工作站上的Operator SDK CLI

  • 已安装OpenShift CLI (oc) v4.17+

  • 使用Operator SDK初始化的操作符项目

  • 如果您的Operator是基于Go的，则必须更新您的项目以使用受支持的镜像在OpenShift Container Platform上运行

步骤

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

    1. 构建镜像

      $ 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来实现此目的。有关更多信息，请参阅多架构。

    2. 将镜像推送到存储库

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

  2. 运行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自动验证，以确保磁盘上的包表示正确。

  3. 运行以下命令构建和推送您的包镜像。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 Container Platform 上默认安装，并作为 Kubernetes 扩展运行，因此您可以使用 Web 控制台和 OpenShift CLI (oc) 执行所有 Operator 生命周期管理功能，无需任何其他工具。

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

先决条件

  • 安装在开发工作站上的Operator SDK CLI

  • 已构建并推送到注册表的 Operator 包镜像。

  • 安装在基于 Kubernetes 的集群上的 OLM（如果您使用apiextensions.k8s.io/v1 CRD，则版本为 v1.16.0 或更高版本，例如 OpenShift Container Platform 4.17）。

  • 使用具有cluster-admin权限的帐户，使用oc登录到集群。

  • 如果您的Operator是基于Go的，则必须更新您的项目以使用受支持的镜像在OpenShift Container Platform上运行

步骤

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

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

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

    此命令执行以下操作：

    • 创建一个引用您的包镜像的索引镜像。索引镜像是不透明且短暂的，但准确地反映了在生产环境中如何将包添加到目录。

    • 创建一个指向您的新索引镜像的目录源，这使 OperatorHub 能够发现您的 Operator。

    • 通过创建OperatorGroup、Subscription、InstallPlan和所有其他必需的资源（包括 RBAC）将您的 Operator 部署到您的集群。

其他资源

发布包含打包 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，则版本为 v1.16.0 或更高版本，例如 OpenShift Container Platform 4.17）。

  • 使用具有cluster-admin权限的帐户，使用oc登录到集群。

步骤

  1. 在您的 Operator 项目目录中运行以下make命令以构建包含您的 Operator 包的索引镜像：

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

    其中CATALOG_IMG参数引用您有权访问的存储库。您可以在 Quay.io 等存储库站点获得存储容器的帐户。

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

    $ 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

  3. 定义一个引用您刚刚生成的索引镜像的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 Container Platform 版本中，默认值将为restricted。如果您的目录无法以restricted权限运行，建议您手动将此字段设置为legacy。
    2 将image设置为之前使用CATALOG_IMG参数的镜像拉取规范。

  4. 检查目录源。

    $ oc get catalogsource
    示例输出
    NAME           DISPLAY     TYPE   PUBLISHER   AGE
cs-memcached   My Test     grpc   Company     4h31m
验证

  1. 使用您的目录安装 Operator。

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

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

    2. 定义一个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

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

    1. 检查 Operator 组。

      $ oc get og
      示例输出
      NAME             AGE
my-test           4h40m

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

      $ oc get csv
      示例输出
      NAME                        DISPLAY   VERSION   REPLACES   PHASE
memcached-operator.v0.0.1   Test      0.0.1                Succeeded

    3. 检查 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
其他资源

测试 Operator Lifecycle Manager 上的 Operator 升级

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

run bundle-upgrade子命令通过为更高版本指定包镜像来自动触发已安装的 Operator 升级到更高版本。

先决条件

  • 使用run bundle子命令或使用传统的 OLM 安装安装的 Operator。

  • 代表已安装 Operator 的更高版本的捆绑镜像

步骤

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

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

    例如，您可以为 Memcached Operator 指定早期捆绑镜像，使用以下 `run 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"

  2. 通过指定更高版本 Operator 的捆绑镜像来升级已安装的 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"

  3. 清理已安装的 Operators

    $ operator-sdk cleanup memcached-operator
其他资源

控制 Operator 与 OpenShift Container Platform 版本的兼容性

Kubernetes 定期弃用某些 API，这些 API 在后续版本中将被移除。如果您的 Operator 使用了已弃用的 API，则在 OpenShift Container Platform 集群升级到已移除该 API 的 Kubernetes 版本后，它可能不再工作。

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

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

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

APIRemovedInNextReleaseInUse

将在下一个 OpenShift Container Platform 版本中移除的 API。

APIRemovedInNextEUSReleaseInUse

将在下一个 OpenShift Container Platform 扩展更新支持 (EUS) 版本中移除的 API。

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

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

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

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

  • 现有的 Operator 项目

步骤

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

    只有当您的 Operator 捆绑包版本无法在更高版本中工作时，才必须使用 `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 Container Platform 的最大集群版本。例如，将 `value` 设置为 `4.9` 将防止在将此捆绑包安装在集群上时将集群升级到高于 4.9 的 OpenShift Container Platform 版本。

  2. 如果您的捆绑包 предназначен для распространения в предоставляемом Red Hat каталоге Operator, настройте совместимые версии OpenShift Container Platform для вашего Operator, установив следующие свойства. Эта конфигурация гарантирует, что ваш Operator будет включен только в каталоги, предназначенные для совместимых версий OpenShift Container Platform

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

    1. 在项目的 `bundle/metadata/annotations.yaml` 文件中设置 `com.redhat.openshift.versions` 注解

      包含兼容版本的 `bundle/metadata/annotations.yaml` 文件示例
      com.redhat.openshift.versions: "v4.7-v4.9" (1)
      1 设置为范围或单个版本。

    2. 为防止您的捆绑包被带到与 OpenShift Container Platform 不兼容的版本，请确保使用正确的 `com.redhat.openshift.versions` 标签在 Operator 的捆绑镜像中生成索引镜像。例如，如果您的项目是使用 Operator SDK 生成的，请更新 `bundle.Dockerfile` 文件

      包含兼容版本的 `bundle.Dockerfile` 示例
      LABEL com.redhat.openshift.versions="<versions>" (1)
      1 设置为范围或单个版本，例如 `v4.7-v4.9`。此设置定义了应分发 Operator 的集群版本，并且 Operator 不会出现在范围之外的集群版本的目录中。

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

其他资源

其他资源