升级 Alauda Container Platform Pipelines Operator

本文档介绍如何在集群中使用 Marketplace/OperatorHub 界面,将 Alauda Container Platform Pipelines Operator 升级到较新版本。升级过程经过设计,可在确保现有 Tekton 资源受到最小影响的同时顺利完成。

升级概述

升级 Alauda Container Platform Pipelines Operator 后,您可以使用 Tekton 生态系统中的新功能、错误修复和改进。Alauda Container Platform Pipelines Operator 会根据您的配置处理所有 Tekton 组件(Pipelines、Triggers、Hub 等)的升级。

开始之前

升级 Alauda Container Platform Pipelines Operator 前,请确保您:

  • 具有集群的管理员访问权限
  • 查看新版本的 release notes,了解任何不兼容变更
  • 验证现有 Tekton 组件配置是否与新版本兼容
  • 确认所有 Tekton 组件均处于就绪状态
  • 上传新版本的 Operator,请参阅安装指南中的 operator 上传说明 。
WARNING

从 v4.12.0 开始,内置的 Tekton Hub 默认不再部署;升级到 v4.12.0 或更高版本会删除现有的内置 Tekton Hub 部署。从 v4.14.0 开始,内置的 Tekton Hub runtime 将完全不再提供:operator 不再包含任何 Tekton Hub manifest,并且 AUTOINSTALL_TEKTONHUB 开关已移除,因此升级后无法重新启用该 runtime。升级到 v4.14.0 或更高版本时,operator 会在升级期间自动将旧版 TektonHub 自定义 catalog 设置迁移到 ArtifactHub Shim,因此您无需提前手动迁移这些设置。升级到早于 v4.14.0 的版本时,请遵循该版本的迁移指南。有关 catalog 的详细信息,请参阅 ArtifactHub Shim Catalog。

NOTE

升级到 v4.14.0 或更高版本期间,operator 会读取 TektonHub.spec.catalogs[] 以及旧版 tekton-hub-api ConfigMap 的 CATALOGS 数据,然后在清理旧版 Tekton Hub runtime 之前,于 ArtifactHub Shim 命名空间中创建 artifacthub-shim-legacy-tekton-hub-catalogs。迁移不会获取 TektonHub.spec.api.hubConfigUrl。有关迁移后的 repository 配置的详细信息,请参阅 Configure Custom Git Repositories。

首先确认目标 channel

批准升级前,请确认 Subscription 使用的 channel:

  • stable(默认):仅跟踪 LTS 版本,建议用于生产环境。
  • latest:跟踪所有版本,包括非 LTS 版本。
  • pipelines-4.14:仅跟踪 v4.14 LTS 系列中的补丁更新。每个 LTS 版本都存在一个 pipelines-x.y channel,因此 pipelines-4.10 仍会跟踪之前的 LTS 系列。
WARNING

如果您当前使用的是 latest 中的非 LTS 版本,切换到 stable 不会执行降级。您可能会停留在当前版本,直到发布更新的 LTS 版本后才会出现新的升级提示。

升级过程

使用 Marketplace/OperatorHub

  1. 访问 Marketplace/OperatorHub

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

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

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

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

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

    • 单击 Confirm 开始该过程
    • 查看升级详细信息并确认您的选择
    • 系统将在保留自定义资源的同时更新 Alauda Container Platform Pipelines Operator
  7. 监控升级

    • 升级进度将显示在 OperatorHub 界面中
    • 您还可以在 tekton-operator 命名空间中检查状态:
      $ kubectl get pods -n tekton-operator
      当所有 pod 均处于 Running 状态时,Operator 升级完成。 随后,Operator 将自动升级 Pipelines、Triggers、Chains 等组件(如果您已启用内置的 Tekton Hub,还会升级 Hub)。
    • 检查组件升级状态:
      $ kubectl get tektoninstallerset -A
      $ kubectl get pods -n tekton-pipelines
      当所有组件和 pod 均处于 Ready 状态时,组件升级完成。
  8. 验证升级

    • 检查 Alauda Container Platform Pipelines Operator 版本是否已更新:
      $ kubectl get csv -n tekton-operator
      
      NAME                        DISPLAY                   VERSION   REPLACES   PHASE
      tektoncd-operator.v4.x.x    Alauda Container Platform Pipelines   4.x.x     x          Succeeded
      当 VERSION 与新版本匹配时,升级完成。
    • 验证 Tekton 组件是否正常运行
      • 测试您的 pipeline 是否可以成功运行

使用 kubectl CLI

您还可以使用命令行界面升级 Alauda Container Platform Pipelines Operator。此方法适用于自动化场景,或适合偏好使用 CLI 执行操作的用户。

  1. 检查当前 Subscription

    • 首先,确定当前 Subscription 及其 channel:
      $ kubectl get subscriptions.operators.coreos.com -A | grep tektoncd-operator
      
      NAMESPACE               NAME                    PACKAGE                 SOURCE     CHANNEL
      tekton-operator         tektoncd-operator       tektoncd-operator       platform   stable
  2. 切换到目标 channel

    • 如果需要升级到其他 channel 中的版本,请修补 Subscription:
      $ kubectl patch subscriptions.operators.coreos.com tektoncd-operator --type merge -p '{"spec":{"channel": "<target-channel>"}}' -n tekton-operator
      将 <target-channel> 替换为所需的 channel(例如 stable、latest、pipelines-4.14)。
  3. 等待 UpgradePending 状态

    • 监控 Subscription 状态,直到其显示为 UpgradePending:
      $ kubectl get subscriptions.operators.coreos.com tektoncd-operator -n tekton-operator -o yaml
      
      status:
        installplan:
          apiVersion: operators.coreos.com/v1alpha1
          kind: InstallPlan
          name: install-abc123
        state: UpgradePending
      在输出中查找 state: UpgradePending。
  4. 批准 InstallPlan

    • 当 Subscription 处于 UpgradePending 状态时,查找对应的 InstallPlan:

      $ kubectl get installplan -n tekton-operator
      
      NAME            CSV                        APPROVAL   APPROVED
      install-abc123  tektoncd-operator.v4.x.x  Manual     false
    • 将 approved 字段设置为 true,以批准 InstallPlan:

      $ kubectl patch installplans.operators.coreos.com <installplan-name> --type merge -p '{"spec":{"approved":true}}' -n tekton-operator

      将 <installplan-name> 替换为上一步中的实际 InstallPlan 名称。

  5. 监控升级进度

    • 监控 Subscription 状态,直到其变为就绪:

      $ kubectl get subscriptions.operators.coreos.com tektoncd-operator -n tekton-operator -o yaml -w
    • 检查 Operator pod 状态:

      $ kubectl get pods -n tekton-operator

      等待所有 pod 均处于 Running 状态。

  6. 验证升级

    • 确认 Operator 版本已更新:
      $ kubectl get csv -n tekton-operator
      
      NAME                        DISPLAY                   VERSION   REPLACES   PHASE
      tektoncd-operator.v4.x.x    Alauda Container Platform Pipelines   4.x.x     x          Succeeded
  7. 监控组件升级

    • Operator 将自动升级 Tekton 组件。监控其进度:
      $ kubectl get tektoninstallerset -A
      $ kubectl get pods -n tekton-pipelines
      确保所有组件和 pod 均达到 Ready 状态。
NOTE

CLI 升级过程遵循与 GUI 方法相同的底层机制。主要区别在于,您需要手动控制 channel 切换和 InstallPlan 批准步骤。

升级后步骤

升级成功完成后:

  1. 验证组件状态

    • 检查所有 Tekton 组件是否已更新:
      kubectl get tektonconfig,tektonpipeline,tektontrigger -A
      kubectl get tektoninstallerset -A
  2. 测试功能

    • 运行一个简单的 pipeline,验证系统是否正常工作
    • 确保所有现有集成继续正常运行
  3. 根据需要更新自定义资源

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

验证已迁移的 TektonHub 自定义目录

如果集群在旧的 tekton-hub-api ConfigMap 中包含 TektonHub.spec.catalogs[] 或自定义 CATALOGS 数据,请验证生成的 ArtifactHub Shim 仓库 ConfigMap 是否存在:

kubectl get configmap artifacthub-shim-legacy-tekton-hub-catalogs \
  -n artifacthub-shim-system \
  -o yaml

如果 ArtifactHub Shim 安装在其他命名空间中,请使用 TektonConfig.spec.pipeline.hub-resolver-config.artifact-hub-api 中的命名空间。有关仓库 ConfigMap 格式和凭证选项,请参阅 配置自定义 Git 仓库。

生成的条目使用以下命名模式:

旧目录生成的 kind生成的 ArtifactHub Shim 仓库
<catalog>task<catalog>
<catalog>pipeline<catalog>-pipelines
<catalog>stepaction<catalog>-stepactions

生成的条目会设置 optional: true。Pipeline 和 StepAction 条目会设置 legacyCatalogAliases: ["<catalog>"],因此旧的 hub resolver 引用可以继续使用原始目录名称,而新引用应使用生成的规范仓库名称。

如果旧版 SSH Secret 存在,请验证复制的 Secret:

kubectl get secret artifacthub-shim-legacy-tekton-hub-ssh-creds \
  -n artifacthub-shim-system

复制的 Secret 已针对 ArtifactHub Shim 进行规范化,其中包含 sshPrivateKey 和 known_hosts。如果旧版 Secret 不包含 known_hosts、没有私钥,或存在多个私钥候选项(例如同时包含 id_rsa 和 id_ed25519),operator 会使迁移后的 SSH 目录缺少 credentialRef。随后,ArtifactHub Shim 源将在刷新期间报告 Git 凭证问题。

如果条目与现有 ArtifactHub Shim 仓库或别名冲突,operator 会跳过这些条目;对于并非由此次迁移生成的同名 ConfigMap 或 Secret,operator 也不会覆盖。如果预期的迁移目录缺失,请查看 operator 日志。

回滚操作步骤

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

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

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

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

故障排除

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

  • 查看 Alauda Container Platform Pipelines Operator Pod 日志:

    $ kubectl logs -l name=tekton-operator -n tekton-operator
  • 验证 Tekton 资源的状态:

    $ kubectl get tektonconfig config -o yaml
  • 确保所有组件均处于预期状态:

    $ kubectl get tektoninstallerset

后续步骤

成功升级 Alauda Container Platform Pipelines Operator 后:

  • 了解最新版本引入的新功能
  • 更新 CI/CD pipeline 以利用新功能
  • 考虑启用新版本中可能提供的其他组件