#升级 global 集群

#准备升级工件

在解压后的核心包目录中运行 bash upgrade.sh。

upgrade.sh 会准备基于 CVO 的工作流所需的资源，包括：

Registry 行为取决于环境配置方式：

常用参数：

bash upgrade.sh

#运行预检

在请求升级之前先运行预检：

bash upgrade.sh --preflight

预检返回两部分：

默认检查集包括：

• ResourcePatchUpgradeable
• ClusterVersionUpgradeable
• VersionUpgradePath
• KubernetesVersionSupported
• DockerRuntimeUnsupported
• ClusterRunning
• ClusterModuleStable
• ControlPlaneStaticPodsPresent
• CustomEtcdBackupCronJobsAbsent
• CRIUpgradePodsAbsent
• ModuleInfoStable
• PlatformLicense

#在需要时处理预检阻塞

如果 ResourcePatchUpgradeable 因 reason=UnexemptResourcePatches 而失败，请检查阻塞的 ResourcePatch，并添加所需的豁免注解：

kubectl -n cpaas-system get cvsh global \
  -o jsonpath='{range .status.preflight.checks[?(@.name=="ResourcePatchUpgradeable")]}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl get resourcepatches <rp-name> -o yaml

默认注解键为 config.cpaas.io/exempt-for-ver。

kubectl annotate resourcepatches <rp-name> \
  config.cpaas.io/exempt-for-ver=4.3.0 \
  --overwrite

如果临时排障需要禁用特定检查，请配置 cpaas-system/cvo-config：

apiVersion: v1
kind: ConfigMap
metadata:
  name: cvo-config
  namespace: cpaas-system
data:
  preflight: |
    disabled:
      - ResourcePatchUpgradeable
      - VersionUpgradePath

#请求升级

准备阶段完成后，选择以下入口之一：

• 在目标版本对该集群可用后，使用 Web Console。
• 当你需要操作底层 CVO 资源时，直接 patch ClusterVersionShadow.spec.desiredUpdate。
• 使用 ACP CLI 显式请求 global 的升级。

如果你使用 Web Console，请求流程分为两步：

• 在 步骤 1 中，检查 RPCH 列表。
• 单击 确认 以继续到 步骤 2。
• 在 步骤 2 中，检查 当前版本 和 目标版本。此阶段页面不会显示插件列表或警告图表。
• 目标版本由已准备好的升级工件决定，无法在 Web Console 中手动选择。
• 单击 开始升级。
• 在对话框中确认操作。
• 确认后，页面会显示升级请求已提交，且操作进入进行中状态。

kubectl 示例：

kubectl patch cvsh global -n cpaas-system --type merge -p '{
  "spec": {
    "desiredUpdate": {
      "version": "4.3.0"
    }
  }
}'

你也可以直接编辑资源：

kubectl edit cvsh global -n cpaas-system

最小配置：

spec:
  desiredUpdate:
    version: 4.3.0

ACP CLI 示例：

# 请求升级到当前已发布在 availableUpdates 中的最高版本
ac adm upgrade --cluster=global --to-latest

# 请求升级到指定目标版本
ac adm upgrade --cluster=global --to=4.3.0

# 显示 global 集群升级的摘要、预检和阶段进度
ac adm upgrade status --cluster=global

#观察执行情况

使用以下命令检查总体状态：

kubectl get cvsh -n cpaas-system

重要状态字段：

首先重点关注以下条件：

有用的诊断命令：

kubectl -n cpaas-system get cvsh global \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl -n cpaas-system get cvsh global \
  -o jsonpath='{.status.preflight.observedAt}{"\n"}{range .status.preflight.checks[*]}{.name}{"\t"}{.policy}{"\t"}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl -n cpaas-system get cvsh global \
  -o jsonpath='{range .status.history[*]}{.version}{"\t"}{.state}{"\t"}{.startedTime}{"\t"}{.completionTime}{"\n"}{end}'

#（条件）升级 Service Mesh Essentials

如果已安装 Service Mesh v1，请在升级业务集群之前先参考 Alauda Service Mesh Essentials 集群插件 文档。

#在升级前验证 DR 环境

按照常规的 global DR 检查操作步骤，确保 备用 global 集群 中的数据与 主 global 集群 一致。有关 DR 拓扑和同步工作流的背景信息，请参见 Global Cluster Disaster Recovery。

如果检测到不一致，请在继续之前联系技术支持。

在 两个 global 集群上运行以下命令，确保没有任何 Machine 节点处于非运行状态：

kubectl get machines.platform.tkestack.io

如果存在此类节点，请先解决再继续。

#从备用 global 集群卸载 etcd 同步插件

1. 通过 IP 或 VIP 访问 备用 global 集群 的 Web Console。
2. 切换到 管理员 视图。
3. 导航到 Marketplace > Cluster Plugins，并选择 global 集群。
4. 找到 etcd Synchronizer 并将其卸载。
5. 等待卸载完成后再继续。

#在两个 global 集群上准备升级工件

在 备用 global 集群 和 主 global 集群 上完成标准工作流中的 准备升级工件。

在两个集群上使用相同的准备模式。

#升级备用 global 集群

如果你将使用备用 global 集群上的 Web Console，请确认备用集群 ProductBase 的 spec.alternativeURLs 中包含备用 VIP：

apiVersion: product.alauda.io/v1alpha2
kind: ProductBase
metadata:
  name: base
spec:
  alternativeURLs:
    - https://<standby-cluster-vip>

准备完成后，在 备用 global 集群 上执行标准工作流中的剩余步骤：

1. 运行预检
2. 请求升级
3. 观察执行情况，直到备用 global 集群达到目标版本

#升级主 global 集群

在备用 global 集群达到目标版本后，在 主 global 集群 上执行标准工作流中的剩余步骤：

1. 运行预检
2. 请求升级
3. 观察执行情况，直到主 global 集群达到目标版本

#重新安装 etcd 同步插件并验证同步状态

在重新安装插件之前，请确认在使用该转发模式时，端口 2379 已从两个 global 集群的 VIP 正确转发到各自的控制平面节点。如果备用 global 集群可以直接访问活动 global 集群，则不需要通过负载均衡器进行端口转发。

要重新安装该插件：

1. 通过 VIP 访问 备用 global 集群 的 Web Console，并切换到 管理员 视图。
2. 导航到 Marketplace > Cluster Plugins，并选择 global 集群。
3. 找到 etcd Synchronizer，单击 Install，并配置所需参数。

配置插件时：

• 当端口 2379 没有通过负载均衡器转发时，请正确设置 Active Global Cluster ETCD Endpoints。
• 使用 Data Check Interval 的默认值。
• 除非你正在排查问题，否则保持 Print detail logs 为禁用状态。

验证同步 Pod 是否在备用 global 集群上运行：

kubectl get po -n cpaas-system -l app=etcd-sync
etcd_sync_pod=$(kubectl get po -n cpaas-system -l app=etcd-sync -o jsonpath='{.items[0].metadata.name}')
kubectl logs -n cpaas-system "$etcd_sync_pod" | grep -i "Start Sync update"

一旦出现 Start Sync update，请重新创建其中一个 Pod，以触发对具有 ownerReference 依赖关系资源的同步：

etcd_sync_pod=$(kubectl get po -n cpaas-system -l app=etcd-sync -o jsonpath='{.items[0].metadata.name}')
kubectl delete po -n cpaas-system "$etcd_sync_pod"

检查同步状态：

mirror_svc=$(kubectl get svc -n cpaas-system etcd-sync-monitor -o jsonpath='{.spec.clusterIP}')
ipv6_regex="^[0-9a-fA-F:]+$"
if [[ $mirror_svc =~ $ipv6_regex ]]; then
  mirror_host="[$mirror_svc]"
else
  mirror_host="$mirror_svc"
fi
curl -g "http://${mirror_host}/check"

输出解释：

• LOCAL ETCD missed keys：这些 Key 存在于主 global 集群中，但在备用 global 集群中缺失。通常在重启一个 etcd-sync Pod 后可以解决。
• LOCAL ETCD surplus keys：这些 Key 存在于备用 global 集群中，但不在主集群中。在删除之前，请先与运维团队确认这些 Key。