#升级 global 集群

#同步升级制品

时间： 维护窗口之前的任意时间。此步骤会将制品上传到 registry，不会改变集群状态。

在解压后的 core package 目录中，以仅同步模式运行 upgrade.sh：

bash upgrade.sh --only-sync-image

--only-sync-image 会上传镜像和插件制品，但不会部署 cluster version operator。CVO 会在稍后维护窗口内部署 — 请参见 部署 cluster version operator。

upgrade.sh 会同步基于 CVO 的工作流所需的制品，包括：

upgrade.sh 覆盖 Core。Aligned 和 Agnostic plugins 不会由 upgrade.sh 推送；请在发起升级请求之前，使用在 升级前准备 中下载的软件包通过 violet 推送它们。

# Push Aligned plugins (cluster plugins) — global only
violet push <path/to/aligned-cluster-plugin-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>"

# Push Aligned or Agnostic operators — to global, and to each workload cluster that runs the operator
violet push <path/to/operator-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --clusters "global,<workload-cluster-1>,<workload-cluster-2>"

建议在 global 窗口中将每个 operator package 推送到每个 集群。如果 global 窗口已经过去，而您发现某个业务集群缺少 operator package，仍然可以在业务升级之前推送到该业务集群 — 请参见 升级业务集群。

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

当目标 registry 不是平台默认值时，请添加 registry 参数：

如果已知制品校验是冗余的，可添加 --skip-check-artifacts 以跳过它。

#运行 preflight 检查

时间： 维护窗口前 1–2 周，以便在窗口开启前有时间解决任何阻塞项。

以 preflight 模式运行 upgrade.sh：

bash upgrade.sh --preflight

Preflight 为只读模式 — 它会验证升级就绪状态，但不会改变集群状态。

Preflight 返回两部分：

默认检查集包括：

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

#在需要时处理 preflight 阻塞项

时间： 维护窗口之前。请解决 preflight 发现的每个阻塞项，以免把维护窗口时间消耗在排障上。

如果 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

#解决其他常见的 preflight 阻塞项

默认检查集还会验证更多条件。请列出所有不是 Passed 的检查，然后使用下表逐一解决：

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

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

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

#部署 cluster version operator

时间： 维护窗口开始时。

以 skip-sync 模式运行 upgrade.sh。由于制品已在 同步升级制品 中上传，因此会跳过同步：

bash upgrade.sh --skip-sync-image

这会部署或更新 cluster version operator (CVO) 并完成其余准备工作。CVO 会在下一步发起升级后驱动 Core 和 Aligned plugin 的升级。

#发起升级

在 cluster version operator 部署完成后，请通过以下任一入口发起升级。这三个入口等价；请选择最符合您的运维模式的入口。

# Request upgrade to the highest version currently published in availableUpdates
ac adm upgrade --cluster=global --to-latest

# Request upgrade to a specific target version
ac adm upgrade --cluster=global --to=4.3.0

# Show summary, preflight, and stage progress for the global cluster upgrade
ac adm upgrade status --cluster=global

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

#观察执行情况

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

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}'

上述命令跟踪的是集群级别（Core 和 Aligned）的升级。要观察单个插件或 operator module — 例如在升级 Agnostic plugin 时 — 请改为读取其 ModuleInfo：

# Current version, target, next available version, and phase per installed module on this cluster
kubectl get moduleinfo -l cpaas.io/cluster-name=global \
  -o custom-columns='MODULE:.metadata.labels.cpaas\.io/module-name,CURRENT:.status.version,TARGET:.spec.version,NEW:.status.availableVersions[0].version,PHASE:.status.phase'

# Conditions and any block reasons for one module
kubectl get moduleinfo <name> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

当 status.phase 为 Running 且 status.version 等于目标版本时，表示该 module 已达到目标状态。

#（条件）升级 Service Mesh Essentials

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

#从 Marketplace 升级 Agnostic plugins

CVO 驱动 Core 和 Aligned plugins。Agnostic plugins 不在 CVO 的范围内，必须在集群达到目标 Distribution Version 后单独升级。每个 Agnostic plugin 是否需要升级，取决于其自身的 Kubernetes 兼容性 — 请参阅该 plugin 的 release notes 了解其与目标 Kubernetes 版本的兼容性。

对于 global 集群中正在使用的每个 Agnostic plugin：

1. 在 Web Console 中切换到 Administrator 视图。
2. 导航到 Marketplace > Cluster Plugins 以管理 Agnostic cluster plugins，或者进入 Agnostic operators 的 operator 工作流。
3. 选择目标 plugin 或 operator 并触发升级。Marketplace 升级流程会读取之前通过 violet 推送的 package。

如果您在升级前准备期间跳过了某个 Agnostic plugin 的推送，而 Marketplace 又没有提供目标版本，请先完成 violet push 步骤，然后重新尝试 Marketplace 升级。

#升级前验证 DR 环境

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

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

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

kubectl get machines.platform.tkestack.io

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

#从 standby global cluster 卸载 etcd 同步插件

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

#在两个 global 集群上同步升级制品

在 standby global cluster 和 primary global cluster 上都完成标准工作流中的 同步升级制品。

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

#升级 standby global cluster

如果您将在 standby global cluster 上使用 Web Console，请确认 standby cluster 的 ProductBase 在 spec.alternativeURLs 中包含 standby VIP：

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

同步完成后，在 standby global cluster 上执行标准工作流中的剩余步骤：

1. 运行 preflight 检查
2. 部署 cluster version operator
3. 发起升级
4. 观察执行情况，直到 standby global cluster 达到目标版本

#升级 primary global cluster

在 standby global cluster 达到目标版本后，在 primary global cluster 上执行标准工作流中的剩余步骤：

1. 运行 preflight 检查
2. 部署 cluster version operator
3. 发起升级
4. 观察执行情况，直到 primary global cluster 达到目标版本

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

在重新安装插件之前，如果使用的是这种转发方式，请确认端口 2379 已从两个 global-cluster VIP 正确转发到它们的 control plane 节点。如果 standby global cluster 可以直接访问 active global cluster，则不需要通过 load balancer 进行端口转发。

要重新安装该插件：

kubectl get job -n cpaas-system etcd-sync-bootstrap
kubectl logs -n cpaas-system job/etcd-sync-bootstrap
kubectl get secret -n cpaas-system remote-etcd-ca
kubectl get issuer -n cpaas-system remote-etcd-issuer
kubectl get certificate -n cpaas-system remote-etcd-client
kubectl get secret -n cpaas-system remote-etcd-client

在继续之前，请等待 kubectl get lease -n cpaas-system etcd-sync-mirror -o jsonpath='{.spec.holderIdentity}' 返回非空值。

验证同步 Pod 已在 standby global cluster 上运行，并识别当前 leader：

kubectl get po -n cpaas-system -l app=etcd-sync
kubectl get lease -n cpaas-system etcd-sync-mirror
leader_pod=$(kubectl get lease -n cpaas-system etcd-sync-mirror -o jsonpath='{.spec.holderIdentity}')
kubectl logs -n cpaas-system "$leader_pod" | grep -E "Acquired leader lease|Start Sync update"

如果具有 ownerReference 依赖的资源需要重新同步，请在 Start Sync update 出现后重建当前 leader Pod：

leader_pod=$(kubectl get lease -n cpaas-system etcd-sync-mirror -o jsonpath='{.spec.holderIdentity}')
kubectl delete po -n cpaas-system "$leader_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 存在于 primary global cluster 中，但在 standby 中缺失。重启当前 etcd-sync leader Pod 后，通常可以解决该问题。
• LOCAL ETCD surplus keys：这些 key 存在于 standby global cluster 中，但在 primary 中不存在。在删除它们之前，请先与您的运维团队一起审查这些 key。