#升级 global 集群

#上传镜像

将核心软件包复制到 global 集群的任意控制平面节点上。解压软件包，然后进入解压后的目录。

• 如果 global 集群使用的是内置 registry，请运行：

  bash upgrade.sh --only-sync-image=true

• 如果 global 集群使用的是外部 registry，还需要提供 registry 地址：

  bash upgrade.sh --only-sync-image=true --registry <registry-address> --username <username> --password <password>

如果你计划在升级 global 集群时同时升级 Operator 和 Cluster Plugin，可以提前将它们的镜像推送到 global 集群的 registry。 批量上传说明请参见 仅从目录中的所有软件包推送镜像。

有关 violet push 子命令的详细信息，请参阅 上架软件包。

#触发升级

镜像上传完成后，运行以下命令以开始升级过程：

bash upgrade.sh --skip-sync-image

请等待脚本执行完成后再继续。

如果你已经提前将 Operator 和 Cluster Plugin 镜像推送到 global 集群的 registry，随后可以按照 仅从目录中的所有软件包创建 CR 执行。运行该命令后，请等待大约 10–15 分钟，直到功能组件出现升级通知。之后，你就可以在后续升级步骤中同时升级 Operator 和 Cluster Plugin。

#（条件）移除 TopoLVM

如果你是从 3.18 升级，并且已安装 Build of TopoLVM，则必须在继续升级之前备份并删除相关 TopoLVM 资源。

否则，集群升级将失败。

在待升级集群的任意控制平面节点上运行以下命令：

kubectl get artifactversion -n cpaas-system  $(kubectl get artifactversion -n cpaas-system -l cpaas.io/artifact-version=operatorhub-topolvm-operator --no-headers | grep 4.1 | head -1 | awk '{print $1}') -o yaml > topolvm-artifact.yaml
kubectl delete -f topolvm-artifact.yaml

然后，在global 集群的任意控制平面节点上运行以下命令：

# Replace cluster_name with the name of the cluster to be upgraded
kubectl delete minfo $(kubectl get minfo | grep topolvm-migrate-catalog-updater | grep $cluster_name | awk '{print $1}')

#升级 global 集群

1. 登录 global 集群的 Web Console，并切换到 Administrator 视图。
2. 导航到 Clusters > Clusters。
3. 单击 global 集群以打开其详情视图。
4. 转到 Functional Components 选项卡。
5. 单击 Upgrade 按钮。

在对话框中查看可用的组件更新，并确认继续。

#（条件）升级 TopoLVM

如果你是从 3.18 升级，并且已安装 Build of TopoLVM，且你已经完成了 移除 TopoLVM 步骤。

请在待升级集群的控制平面节点上继续运行以下命令，以升级 TopoLVM：

kubectl create -f topolvm-artifact.yaml

运行命令后，请等待大约 5–10 分钟。 TopoLVM 组件将自动升级，并反映在 Web Console 中。

#安装 Product Docs 插件

从 4.0 开始，内置产品文档已拆分为 Alauda Container Platform Product Docs 插件。如果你是从 3.x 升级，则需要按照以下步骤安装此插件：

1. 导航到 Administrator。

2. 在左侧边栏中，单击 Marketplace > Cluster Plugins，然后选择 global 集群。

3. 找到 Alauda Container Platform Product Docs 插件并单击 Install。

#安装 Alauda Container Platform Cluster Enhancer 插件

1. 导航到 Administrator。

2. 在左侧边栏中，单击 Marketplace > Cluster Plugins，然后选择 global 集群。

3. 找到 Alauda Container Platform Cluster Enhancer 插件并单击 Install。

#（条件）安装 Service Mesh Essentials

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

#验证数据一致性

请按照常规的 global DR 检查流程，确保 备用 global 集群 中的数据与 主 global 集群 一致。

如果检测到不一致，请不要在下一步卸载 etcd 同步插件，并在继续之前联系技术支持。如果在备用 global 集群缺少主集群持有的数据时卸载该插件，可能会导致 owner references 解析错误，并且可能会删除业务集群节点的 Machine 对象——包括 immutable-OS 集群，这会销毁其底层虚拟机。

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

kubectl get machines.platform.tkestack.io

如果存在此类节点，请先联系技术支持进行处理，然后再继续。

#卸载 etcd sync 插件

#上传镜像

在备用集群和主集群上都执行 上传镜像 步骤。

详情请参见 标准操作步骤中的上传镜像。

#升级备用集群

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

在备用集群上，按照 标准操作步骤 中的步骤完成升级。

#升级主集群

备用集群升级完成后，在主集群上继续执行 标准操作步骤。

#重新安装 etcd sync 插件

在重新安装之前，请确认端口 2379 已从两个 global 集群 VIP 正确转发到各自的控制平面节点。

重新安装步骤：

1. 通过 IP 或 VIP 访问 备用 global 集群 的 Web Console。
2. 切换到 Administrator 视图。
3. 进入 Marketplace > Cluster Plugins。
4. 选择 global 集群。
5. 找到 Alauda Container Platform etcd Synchronizer，单击 Install，并提供所需参数。

安装验证：

kubectl get po -n cpaas-system -l app=etcd-sync  # Ensure pod is 1/1 Running

kubectl logs -n cpaas-system $(kubectl get po -n cpaas-system -l app=etcd-sync --no-headers | awk '{print $1}' | head -1) | grep -i "Start Sync update"
# Wait until the logs contain "Start Sync update"

# Recreate the pod to trigger synchronization of resources with ownerReferences
kubectl delete po -n cpaas-system $(kubectl get po -n cpaas-system -l app=etcd-sync --no-headers | awk '{print $1}' | head -1)

#检查同步状态

运行以下命令以验证同步状态：

curl "$(kubectl get svc -n cpaas-system etcd-sync-monitor -ojsonpath='{.spec.clusterIP}')/check"

输出说明：

• "LOCAL ETCD missed keys:" – 这些键存在于主集群中，但在备用集群中缺失。通常在 pod 重启后可以恢复。
• "LOCAL ETCD surplus keys:" – 这些键存在于备用集群中，但在主集群中不存在。删除前请与运维团队确认。