升级 Alauda DevOps Connectors Operator

本文档说明如何在集群中通过 Marketplace/OperatorHub 界面将 Alauda DevOps Connectors Operator 升级到更高版本。升级过程设计得尽可能简单,同时确保对现有资源的影响最小。

升级概述

升级 Alauda DevOps Connectors Operator 后,您可以访问其组件的新功能、错误修复和改进。Alauda DevOps Connectors Operator 会根据您的配置处理所有组件的升级。

开始之前

在升级 Alauda DevOps Connectors Operator 之前,请确保您:

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

迁移到 ConnectorsConfig

早期的 Connectors 版本要求管理员直接创建每个组件 CR(ConnectorsCore、ConnectorsGit 等)。从包含 ConnectorsConfig 的版本开始,一个集群范围的 ConnectorsConfig 将替代它们全部。当此类集群升级时,operator 会将所有现有的独立 CR 吸收到一个新的 ConnectorsConfig 中,并删除原始资源——自动完成,无需任何手动步骤。如果源集群从未有过独立的组件 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 升级正式展开之前,请先审阅以下内容:

  • 目标 namespace。 新的 ConnectorsConfig 会落在现有 ConnectorsCore 所在的 namespace 中;如果不存在 ConnectorsCore,则会落在 operator 的安装 namespace 中。完整规则请参见 自动创建 namespace 优先级。
  • 跨 namespace 整合。 如果独立 CR 分布在多个 namespace 中,则所有受管理的子资源都会整合到 ConnectorsCore 所在的 namespace:原始资源会被删除,受管理的子资源会在该处重新创建。请确认您的独立 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,bootstrap 无法将其删除。请参见 组件卡在 Failed 状态 了解诊断和恢复步骤。

Pipeline Integration 兼容性

如果您使用 Pipeline Integration,并且您的 Tekton 版本早于升级后的 operator 所附带的版本,请在 pipeline-integration 安装参数上限制已安装的 schema-version,这样只会安装您的 Tekton 能够渲染的版本。配置语法请参见 工作原理。

升级流程

使用 Marketplace/OperatorHub

  1. 访问 Marketplace/OperatorHub

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

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

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

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

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

    • 点击 Confirm 开始升级过程
    • 查看升级详情并确认您的选择
    • 系统会在保留自定义资源的同时更新 Alauda DevOps Connectors Operator
  7. 监控升级

    • 升级进度会显示在 OperatorHub 界面中
    • 您也可以在 connectors-operator namespace 中检查状态:
      $ 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 DevOps Connectors Operator 版本是否已更新:
      $ kubectl get csv -n connectors-operator
      
      NAME                         DISPLAY                    VERSION   REPLACES                     PHASE
      connectors-operator.v1.y.z   Alauda DevOps 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 DevOps Connectors Operator
  3. 卸载当前版本
  4. 从版本列表中选择之前的版本
  5. 按照该版本的安装流程进行操作
NOTE

降级可能需要额外步骤,以确保您的资源与旧版本兼容。

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

故障排查

如果您在升级过程中或升级后遇到问题:

  • Pipeline Integration 资源在升级后无法渲染——您的 Tekton 版本可能早于 operator 附带的 schema-version。请在 pipeline-integration 安装参数上限制已安装的 schema-version。

  • 检查 Alauda DevOps 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 DevOps Connectors Operator 后:

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