升级 Alauda Container Platform Connectors operator

本文介绍如何使用集群中的 Marketplace/OperatorHub 界面,将 Alauda Container Platform Connectors operator 升级到较新版本。升级过程经过专门设计,操作简单,同时确保对现有资源的影响最小。

升级概述

升级 Alauda Container Platform Connectors operator 后,您可以使用其组件的新功能、错误修复和改进。Alauda Container Platform Connectors operator 会根据您的配置处理所有组件的升级。

开始之前

在升级 Alauda Container Platform Connectors operator 之前,请确保您:

  • 具有集群的管理员访问权限
  • 查看新版本的 release notes,了解任何不兼容变更
  • 验证现有 Connector 组件配置与新版本兼容
  • 确认所有当前组件均处于就绪状态

迁移到 ConnectorsConfig

早期版本的 Connectors 要求管理员直接创建每个组件 CR(ConnectorsCore、ConnectorsGit、……)。从提供 ConnectorsConfig 的版本开始,单个集群范围的 ConnectorsConfig 将取代所有这些 CR。当此类集群升级时,operator 会将每个现有的独立 CR 吸收到新的 ConnectorsConfig 中,并删除原始 CR —— 此过程会自动完成,无需手动操作。如果源集群从未存在独立组件 CR,则本节不适用。

迁移是单向的

引导过程会在吸收原始独立组件 CR 的 spec 后将其删除。不存在自动回滚机制——降级需要根据您自己的备份重新创建独立 CR。在执行升级前,务必备份每个独立 CR:

kubectl get connectorscore,connectorsgit,connectorsgithub,connectorsgitlab,\
connectorsoci,connectorsharbor,connectorsk8s,connectorsmaven,connectorsnpm,\
connectorspypi,connectorssonarqube,connectorsnexus,connectorsjfrog \
  -A -o yaml > connectors-standalone-backup.yaml

升级前决策

迁移会自动运行,且无法暂停。在 operator 升级推出之前,请查看以下内容:

  • 目标命名空间。 新的 ConnectorsConfig 会创建在现有 ConnectorsCore 所在的命名空间中;如果不存在 ConnectorsCore,则会创建在 operator 的安装命名空间中。有关完整规则,请参阅自动创建命名空间优先级。
  • 跨命名空间整合。 如果独立 CR 分布在多个命名空间中,则每个受管理的子组件都会整合到 ConnectorsCore 命名空间中:原始对象会被删除,受管理的子组件会在该命名空间中重新创建。请确认独立 CR 的布局符合预期的升级后拓扑结构。

验证迁移

operator 升级报告 Succeeded 后,请监视新的 ConnectorsConfig:

kubectl get connectorsconfig -A
kubectl describe connectorsconfig connectors-config -n <namespace>

BootstrapCompleted 事件表示迁移已完成,而 status.conditions[Ready]=True 表示所有组件都已重新达到一致状态。在 operator 仍在清理原始独立 CR 期间,您可能会短暂看到组件处于 Migrating 阶段——这是正常的临时状态,与 Failed 不同。

如果组件持续处于 Failed,原因几乎总是存在引导过程无法删除的过时独立 CR。请按照组件卡在 Failed中的诊断和恢复步骤操作。

Pipeline 集成兼容性

如果您使用 Pipeline Integration,且您的 Tekton 版本低于升级后 operator 所提供的版本,请在 pipeline-integration 安装标志中限制已安装的 schema-version,以便只安装 Tekton 能够呈现的版本。有关配置语法,请参阅工作原理。

升级过程

使用 Marketplace/OperatorHub

  1. 访问 Marketplace/OperatorHub

    • 登录集群的管理控制台
    • 导航到 Marketplace 或 OperatorHub 部分
  2. 找到 Alauda Container Platform Connectors Operator

    • 在搜索栏中搜索 Alauda Container Platform Connectors
    • 点击 Alauda Container Platform Connectors 卡片
  3. 查看可用版本

    • 在 Alauda Container Platform Connectors Operator 详情页上,您会看到当前已安装版本的信息
    • 界面会指示是否有更新版本可用
    • 您可以点击不同的 Channels 查看所有可用版本
  4. 启动升级

    • 如果目标版本位于不同的 Channel 中,请先在 Subscription 中切换到相应的 Channel
    • 如果当前 Channel 有更新版本可用,您会看到以下提示:
      • 检测到新版本
        • 若只升级当前 Operator,请点击 Confirm 进行升级。
  5. 配置升级设置(如果适用)

    • 某些升级可能会显示配置选项
    • 在大多数情况下,默认设置会保留您现有的配置
  6. 确认并开始升级

    • 点击 Confirm 开始操作
    • 查看升级详细信息并确认您的选择
    • 系统会更新 Alauda Container Platform Connectors Operator,同时保留您的自定义资源
  7. 监视升级

    • 升级进度会显示在 OperatorHub 界面中
    • 您也可以在 connectors-operator 命名空间中检查状态:
      $ kubectl get pods -n connectors-operator
      当所有 pod 都处于 Running 状态时,operator 升级完成。 随后,operator 会协调 ConnectorsConfig,并自动升级每个受管理的组件(ConnectorsCore、ConnectorsGit、ConnectorsOCI 等)。
    • 检查组件升级状态:
      $ kubectl get connectorsconfig -A
      $ kubectl describe connectorsconfig connectors-config -n <namespace>
      当 ConnectorsConfig 上报告 status.conditions[Ready]=True 时,所有受管理的组件都已完成重新达到一致状态。
  8. 验证升级

    • 检查 Alauda Container Platform Connectors Operator 版本是否已更新:
      $ kubectl get csv -n connectors-operator
      
      NAME                         DISPLAY                                VERSION   REPLACES                     PHASE
      connectors-operator.v1.y.z   Alauda Container Platform Connectors   1.y.z     connectors-operator.v1.y.z   Succeeded
      当 VERSION 与新版本匹配时,升级完成。
    • 验证所有 Connector 组件是否正常运行

升级后步骤

升级成功完成后:

  1. 验证组件状态

    • 检查 ConnectorsConfig 汇总状态,确认每个受管理的组件都已达到新版本:
      kubectl get connectorsconfig -A
      kubectl describe connectorsconfig connectors-config -n <namespace>
      有关每个组件阶段含义的说明,请参阅状态和阶段。
  2. 测试功能

    • 使用 connector csi 运行作业,或部署一个通过 oci connector 拉取镜像的应用,以验证系统正常运行
    • 确保所有现有集成继续正常运行
  3. 根据需要更新自定义资源

    • 如果新版本引入了 CRD 变更,您可能需要更新自定义资源
    • 有关具体迁移步骤,请参阅 release notes

回滚操作步骤

跨越 ConnectorsConfig 迁移边界

如果升级是从 ConnectorsConfig 之前的版本升级到包含 ConnectorsConfig 的版本,则降级不只是卸载 — 请参阅迁移是单向的。您还需要在旧版本 operator 重新接管这些资源之前,从升级前的备份中恢复独立组件 CR。

如果新版本出现问题,您可以回滚到上一版本:

  1. 返回 Marketplace/OperatorHub 界面
  2. 选择 Alauda Container Platform Connectors Operator
  3. Uninstall 当前版本
  4. 从版本列表中选择上一版本
  5. 按照该版本的安装流程操作
NOTE

降级可能需要执行其他步骤,以确保资源与旧版本兼容。

这取决于您升级前版本与升级到的版本之间的差异。如果差异较大,您可能需要手动迁移资源。

故障排除

如果您在升级期间或升级后遇到问题:

  • 升级后 Pipeline Integration 资源无法渲染 — 您的 Tekton 版本可能早于 operator 所提供的 schema-version。请在 pipeline-integration 安装标志中限制已安装的 schema-version。

  • 检查 Alauda Container Platform Connectors Operator pod 日志:

    $ kubectl logs -l control-plane=connectors-operator -n connectors-operator
  • 验证 ConnectorsConfig 的状态,以确定哪个组件出现故障:

    $ kubectl get connectorsconfig -A
    $ kubectl describe connectorsconfig connectors-config -n <namespace>

    status.components.<name>.message 指向出现故障的组件。如果组件一直处于 Failed 状态,请按照组件卡在 Failed 状态中的诊断和恢复步骤操作。

后续步骤

成功升级 Alauda Container Platform Connectors Operator 后:

  • 探索最新版本中引入的新功能
  • 考虑启用新版本中可能提供的其他组件