#升级 Alauda DevOps Pipelines Operator

本文档提供了在集群中使用 Marketplace/OperatorHub 界面对 Alauda DevOps Pipelines Operator 升级到新版本的说明。升级过程旨在尽可能简洁，同时将对现有 Tekton 资源的影响降到最低。

#升级概述

升级 Alauda DevOps Pipelines Operator 后，您可以使用 Tekton 生态系统中的新功能、问题修复和改进。Alauda DevOps Pipelines Operator 会根据您的配置处理所有 Tekton 组件（Pipelines、Triggers、Hub 等）的升级。

#开始之前

在升级 Alauda DevOps Pipelines Operator 之前，请确保您：

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

#先确认目标 Channel

在批准升级之前，请先确认您的 Subscription 使用的是哪个 channel：

• stable（默认）：仅跟踪 LTS release，推荐用于生产环境。
• latest：跟踪所有 release，包括非 LTS。
• pipelines-4.14：仅跟踪 v4.14 LTS 线中的补丁更新。每个 LTS 版本都有一个 pipelines-x.y channel，因此 pipelines-4.10 仍会跟踪上一条 LTS 线。

#升级过程

#使用 Marketplace/OperatorHub

1. 访问 Marketplace/OperatorHub

   • 登录到集群的管理控制台
   • 进入 Marketplace 或 OperatorHub 视图

2. 定位 Alauda DevOps Pipelines Operator

   • 在搜索框中搜索 Alauda DevOps Pipelines
   • 点击 Alauda DevOps Pipelines 卡片

3. 查看可用版本

   • 在 Alauda DevOps Pipelines Operator 详情页中，您将看到当前已安装版本的信息
   • 如果有更新的版本可用，界面会显示提示
   • 您可以点击不同的 Channels 查看所有可用版本

4. 启动升级

   • 如果目标版本位于不同的 Channel，请先在 Subscription 中切换到相应的 Channel
   • 如果当前 Channel 中有可用的新版本，您会看到提示：
     • 检测到新版本
       • 如果只想升级当前 Operator，请点击 Confirm 开始升级。

5. 配置升级设置（如适用）

   • 某些升级可能会提供配置选项
   • 在大多数情况下，默认设置会保留您现有的配置

6. 确认并开始升级

   • 点击 Confirm 开始升级过程
   • 检查升级详情并确认您的选择
   • 系统会在保留您自定义资源的同时更新 Alauda DevOps 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 DevOps Pipelines Operator 版本是否已更新：

     $ kubectl get csv -n tekton-operator
     
     NAME                        DISPLAY                   VERSION   REPLACES   PHASE
     tektoncd-operator.v4.x.x    Alauda DevOps Pipelines   4.x.x     x          Succeeded
     当 VERSION 与新版本一致时，升级完成。
   • 验证您的 Tekton 组件是否正常运行
     • 测试您的 pipelines 是否可以成功运行

#使用 kubectl CLI

您也可以使用命令行界面升级 Alauda DevOps 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 中的版本，请先 patch 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 状态，直到其变为 ready：

     $ 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 DevOps Pipelines   4.x.x     x          Succeeded

7. 监控组件升级

   • operator 会自动升级 Tekton 组件。监控其进度：

     $ kubectl get tektoninstallerset -A
     $ kubectl get pods -n tekton-pipelines
     确保所有组件和 pod 都达到 Ready 状态。

#升级后的步骤

升级成功完成后：

1. 验证组件状态

   • 检查所有 Tekton 组件是否已更新：

     kubectl get tektonconfig,tektonpipeline,tektontrigger -A
     kubectl get tektoninstallerset -A

2. 测试功能

   • 运行一个简单的 pipeline，以验证系统是否正常工作
   • 确保所有现有集成都继续正常运行

3. 如有需要，更新自定义资源

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

#验证已迁移的 TektonHub 自定义 catalogs

如果集群中旧的 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 仓库。

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

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

如果旧的 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 catalog，但不会设置 credentialRef。随后，ArtifactHub Shim source 会在刷新时报告 Git 凭证问题。

operator 会跳过与现有 ArtifactHub Shim repository 或别名冲突的条目，并且不会覆盖未由此次迁移生成的同名 ConfigMap 或 Secret。如果缺少预期的已迁移 catalog，请检查 operator 日志。

#回滚操作步骤

如果您在新版本中遇到问题，可以回滚到先前版本：

1. 返回 Marketplace/OperatorHub 界面
2. 选择 Alauda DevOps Pipelines Operator
3. Uninstall 当前版本
4. 从版本列表中选择先前版本
5. 按照该版本的安装流程执行

#故障排除

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

• 检查 Alauda DevOps Pipelines Operator pod 日志：

  $ kubectl logs -l name=tekton-operator -n tekton-operator

• 验证 Tekton 资源的状态：

  $ kubectl get tektonconfig config -o yaml

• 确保所有组件都具有预期状态：

  $ kubectl get tektoninstallerset

#下一步

成功升级 Alauda DevOps Pipelines Operator 后：

• 探索最新版本引入的新功能
• 更新您的 CI/CD pipelines 以利用新能力
• 考虑启用新版本中可能提供的其他组件