支持控制台（Console）开发人员开始试用联系人

5.7. 使用捆绑包镜像

您可以使用 Operator SDK 在 Operator Lifecycle Manager（OLM）中以捆绑格式（Bundle Format）打包、部署和升级 Operator。

重要

红帽支持的 Operator SDK CLI 工具版本，包括 Operator 项目的相关构建和测试工具已被弃用，计划在以后的 OpenShift Dedicated 发行版本中删除。红帽将在当前发行生命周期中提供对这个功能的程序错误修复和支持，但此功能将不再获得改进，并将在以后的 OpenShift Dedicated 版本中删除。

对于创建新 Operator 项目，不建议使用红帽支持的 Operator SDK 版本。现有 Operator 项目的 Operator 作者可使用 OpenShift Dedicated 4 发布的 Operator SDK CLI 工具版本来维护其项目，并创建针对较新版本的 OpenShift Dedicated 的 Operator 发行版本。

以下与 Operator 项目相关的基础镜像 没有被弃用。这些基础镜像的运行时功能和配置 API 仍然会有程序错误修复和并提供对相关 CVE 的解决方案。

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

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

5.7.1. 捆绑 Operator

Operator 捆绑包格式是 Operator SDK 和 Operator Lifecycle Manager（OLM）的默认打包方法。您可以使用 Operator SDK 来构建和推送 Operator 项目作为捆绑包镜像，使 Operator 可供 OLM 使用。

先决条件

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

流程

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

    1. 构建镜像： 

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

      由 SDK 为 Operator 生成的 Dockerfile 需要为 go build 明确引用 GOARCH=amd64。这可以在非 AMD64 构架中使用 GOARCH=$TARGETARCH。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 项目中创建以下文件和目录：

    • 包含 ClusterServiceVersion 对象的捆绑包清单目录，名为 bundle/manifests
    • 名为 bundle/metadata 的捆绑包元数据目录
    • config/crd 目录中的所有自定义资源定义（CRD）
    • 一个 Dockerfile bundle.Dockerfile

    然后，使用 operator-sdk bundle validate 自动验证这些文件，以确保磁盘上的捆绑包的格式是正确的。

  3. 运行以下命令来构建和推送捆绑包镜像。OLM 使用索引镜像来消耗 Operator 捆绑包，该镜像引用一个或多个捆绑包镜像。

    1. 构建捆绑包镜像。使用您要推送镜像的 registry、用户命名空间和镜像标签的详情，设置 BUNDLE_IMG： 

      $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>

    2. 推送捆绑包镜像： 

      $ docker push <registry>/<user>/<bundle_image_name>:<tag>

5.7.2. 使用 Operator Lifecycle Manager 部署 Operator

Operator Lifecycle Manager（OLM）可帮助您在 Kubernetes 集群中安装、更新和管理 Operator 及其相关服务的生命周期。OLM 在 OpenShift Dedicated 上默认安装，并作为 Kubernetes 扩展运行，以便您可以在没有任何额外工具的情况下将 Web 控制台和 OpenShift CLI（oc）用于所有 Operator 生命周期管理功能。

Operator Bundle Format 是 Operator SDK 和 OLM 的默认打包方法。您可以使用 Operator SDK 在 OLM 上快速运行捆绑包镜像，以确保它正确运行。

先决条件

  • 在开发工作站上安装 operator SDK CLI
  • 构建并推送到 registry 的 Operator 捆绑包镜像
  • OLM安装在一个基于 Kubernetes 的集群上（如果使用 apiextensions.k8s.io/v1 CRD，则为 v1.16.0 或更新版本，如 OpenShift Dedicated 4）
  • 使用具有 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 部署到集群中。

其他资源

5.7.3. 发布包含捆绑 Operator 的目录

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

注意

Operator SDK 使用 opm CLI 来简化索引镜像的创建。不要求具备 opm 命令相关经验。对于高级用例，可以直接使用 opm 命令，而不是 Operator SDK。

先决条件

  • 在开发工作站上安装 operator SDK CLI
  • 构建并推送到 registry 的 Operator 捆绑包镜像
  • OLM安装在一个基于 Kubernetes 的集群上（如果使用 apiextensions.k8s.io/v1 CRD，则为 v1.16.0 或更新版本，如 OpenShift Dedicated 4）
  • 使用具有 dedicated-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 Dedicated 发行版本中，计划默认值为 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

其他资源

  • 如需了解更多高级用例，请参阅管理自定义目录以了解有关 opm CLI 直接使用的详情。

5.7.4. 在 Operator Lifecycle Manager 中测试 Operator 升级

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

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

先决条件

  • 使用 run bundle 子命令或传统的 OLM 安装安装 OLM 的 operator
  • 代表已安装 Operator 的更新版本的捆绑包镜像

流程

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

    注意

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

    例如，您可以通过指定更早的捆绑包镜像，为 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. 清理已安装的 Operator： 

    $ operator-sdk cleanup memcached-operator

其他资源

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

重要

Kubernetes 定期弃用后续版本中删除的某些 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 Extended Update Support (EUS) 发行版本中删除的 API。

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

以下流程可帮助管理员在不兼容的 OpenShift Dedicated 版本上安装 Operator 版本。这些步骤还可防止管理员升级到与当前在集群中安装的 Operator 版本不兼容的 OpenShift Dedicated 的更新版本。

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

重要

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

先决条件

  • 现有 Operator 项目

流程

  1. 如果您知道特定 Operator 捆绑包不受支持，且早于特定集群版本无法在 OpenShift Dedicated 上正常工作，请配置 Operator 兼容的最大 OpenShift Dedicated 版本。在 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 Dedicated 集群版本。例如，当在集群中安装这个捆绑包时，将 value 设为 4.9 可防止集群升级到 4.9 之后的 OpenShift Dedicated 版本。

  2. 如果您的捆绑包旨在在红帽提供的 Operator 目录中发布，请通过设置以下属性为 Operator 配置兼容版本的 OpenShift Dedicated。此配置可确保您的 Operator 只包含在以兼容 OpenShift Dedicated 版本为目标的目录中：

    注意

    仅当在红帽提供的目录中发布 Operator 时，才需要这个步骤。如果您的捆绑包只用于在自定义目录中分发，您可以跳过这一步。如需了解更多详细信息，请参阅"红帽提供的 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 Dedicated 版本，请确保索引镜像使用 Operator 捆绑包镜像中的正确 com.redhat.openshift.versions 标签生成。例如，如果您的项目是使用 Operator SDK 生成的，请更新 bundle.Dockerfile 文件：

      与兼容版本的 bundle.Dockerfile 示例

      LABEL com.redhat.openshift.versions="<versions>" 1

      1
      设置为范围或单个版本，如 v4.7-v4.9。通过这个设置，您可以定义应分发 Operator 的集群版本，Operator 不会出现在范围之外的集群版本目录中。

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

其他资源

5.7.6. 其他资源

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

© 2024 Red Hat, Inc.