Alauda Container Platform
  • 简体中文

    • 升级 global 集群

    升级路径

    本页面涵盖 global 集群的传统操作系统路径。如果你的 global 集群运行在不可变基础设施（Huawei DCS 上的 Alauda OS、VMware vSphere 或 Huawei Cloud Stack）上，Kubernetes 步骤位于不可变基础设施文档中——请参见 在不可变基础设施上升级 global Cluster。本页面中描述的 Core、Aligned 和 Agnostic 步骤仍适用于不可变 OS 集群；不同之处仅在于 Kubernetes 的发布方式。

    Alauda Database Service for MySQL v4.3.0 中已移除 MySQL-PXC

    升级 global 集群也会升级 MySQL operator。如果你有 PXC 实例，在 operator 升级后它们将变为未受管。升级前请参见 MySQL Operator Upgrade Guide 获取迁移说明。

    由一个 global 集群和一个或多个业务集群组成。要将平台迁移到新的 ACP Distribution Version，首先将 global 层升级到目标 Distribution Version，然后再将业务集群升级到相同的 Distribution Version。

    ACP 4.3 使用基于 CVO 的集群升级工作流。典型的 global 集群升级包括制品准备、预检、升级请求和状态观察。

    在将 global 集群升级到 ACP 4.3 之前，请确认每个业务集群都运行在兼容的 Kubernetes 版本上。对于 ACP 4.3，兼容版本为 1.34、1.33、1.32 和 1.31。此先决条件独立于更广泛的第三方集群管理范围。

    无论环境是否使用 global DR，此兼容版本的先决条件都适用。global DR 会改变升级 global 层所使用的操作步骤，但不会改变这样一个要求：在将 global 层升级到目标 Distribution Version 之前，业务集群必须保持在兼容的 Kubernetes 版本范围内。

    global 集群升级遵循本页面文档化的、经过验证的 upgrade.sh 操作步骤。你可以通过 Web Console、更新 ClusterVersionShadow.spec.desiredUpdate，或使用带 --cluster=global 的 ACP CLI 来发起 global 集群升级。有关完整的 AC CLI 工作流和输出解释，请参见 升级集群。有关完整命令和参数语法，请参见 AC CLI Administrator Command Reference。

    如果环境使用 global DR，请遵循 Global DR Procedure。否则，请遵循下面的标准工作流。

    目录

    标准工作流升级后Global DR Procedure相关文档

    标准工作流

    global 集群升级按时间线分阶段进行。大部分工作都会在维护窗口开始之前完成，以便让窗口本身保持短且可预测：

    阶段时间发生的内容对集群的影响
    1. 同步制品维护窗口前的任意时间upgrade.sh --only-sync-image 上传 Core 制品；violet 为已安装的 Aligned 插件以及计划在该窗口升级的 Agnostic 插件发布目标包。无 — 镜像和目录条目已发布，但未更改任何正在运行的插件；不会停机。
    2. 预检维护窗口前 1–2 周upgrade.sh --preflight 验证升级就绪情况。在窗口开启前解决所有阻塞项。无 — 只读验证。
    3. 升级维护窗口期间upgrade.sh --skip-sync-image 部署或更新 cluster version operator（CVO）；随后请求并观察升级。集群将被升级。

    阶段 1 和阶段 2 不会更改集群状态——请尽早执行，这样维护窗口中只包含阶段 3。对于较小规模或实验环境，也可以运行单个 bash upgrade.sh，它会同时执行同步和 CVO 部署，但生产环境的窗口通常会将它们分开。

    同步升级制品

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

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

    bash upgrade.sh --only-sync-image

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

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

    类型内容作用
    Product imagesproduct-image用于在 ProductManifest 和 CVO 中解析目标版本和镜像。
    CVO imagecluster-version-operator用于部署或更新 cluster version operator。
    插件制品plugins/*.tgz当升级计划需要插件制品时供升级计划使用。

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

    生命周期类型推送工具集群插件Operators
    Aligned 插件violet push对每个已安装的 Aligned 集群插件都需要。将为目标 ACP Distribution Version 选择的包向 global 层推送一次；之后该包对每个集群都可用。对每个已安装的 Aligned operator 都需要。将目标包推送到 global 层以及运行该 operator 的每个业务集群。
    Agnostic 插件violet push当你计划在同一个窗口中升级该插件时推送。缺少 Agnostic 包不会阻塞 CVO。同样如此；将包推送到你计划升级该 operator 的每个集群。
    # 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 包都推送到每个 集群。如果 global 窗口已经过去，而你发现某个业务集群缺少 operator 包，你仍然可以在业务集群升级之前将其推送到该业务集群——请参见 升级业务集群。

    WARNING

    在请求升级之前，请为集群上安装的每个 Aligned 插件发布目标包。CVO 不要求未安装的 Aligned 插件拥有对应包。如果已安装的某个 Aligned 集群插件缺少包或尚未就绪，CVO 会停滞升级并报告类似 required ModulePluginConfig "<component>-<version>" not found 或 ModulePluginConfig "<component>-<version>" is not Ready 的消息。

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

    场景行为
    已指定 --registry直接使用所提供的 registry。
    未指定 --registry从 ProductBase.spec.registry.address 读取 registry 地址。
    内置平台 registry使用 global VIP 重建访问地址。
    外部 registry自动设置 SKIP_SYNC_IMAGE=true 并跳过镜像同步。
    需要上传镜像但未提供凭据从 cpaas-system/registry-admin Secret 中读取 username 和 password。

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

    参数作用
    --registry指定目标 registry 地址。
    --username / --password指定 registry 凭据。

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

    WARNING

    在镜像和插件同步完成之前，不要开启维护窗口。

    运行预检

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

    以预检模式运行 upgrade.sh：

    bash upgrade.sh --preflight

    Preflight 为只读操作——它会验证升级就绪情况，但不会更改集群状态。

    Preflight 会返回两部分：

    输出作用
    Summary显示整体结果、当前版本、目标版本和目标镜像。
    Checks显示每个单独校验项的结果。

    默认检查集包括：

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

    在需要时处理预检阻塞

    时间： 维护窗口之前。请解决 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=<target-version> \
  --overwrite

    豁免按 major 和 minor 版本进行匹配，因此为某个 patch 版本记录的豁免也覆盖同一 minor release 的其他 patch 版本。

    对 patch 进行豁免意味着升级会保留该自定义项不变。它不会验证该自定义项在目标版本上是否仍然有效——请向提供该自定义项的技术支持联系人确认。

    解决其他常见预检阻塞

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

    kubectl -n cpaas-system get cvsh global \
  -o jsonpath='{range .status.preflight.checks[*]}{.name}{"\t"}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'
    检查验证内容解决方法
    KubernetesVersionSupported集群的 Kubernetes 版本位于目标 release 支持的范围内。如果低于支持范围，请先将集群的 Kubernetes 升级到该范围内——请参见 Kubernetes Support Matrix。
    VersionUpgradePath当前版本可以通过受支持的升级路径到达请求的目标版本。确认当前版本是该目标 release 的受支持源版本；如果不是，请先升级到一个中间受支持版本。
    ClusterRunning集群健康且已完成协调。使用 kubectl get clusterview global 检查集群，并在重试前解决任何不健康的节点或组件。
    DockerRuntimeUnsupported没有节点仍在使用不受支持的 Docker runtime。在升级前将受影响的节点迁移到 containerd。
    ClusterModuleStable, ModuleInfoStable已安装的 Core 和 Aligned 模块处于稳定（Running）状态，而不是正在部署或正在升级。请参见 在升级前验证模块稳定性。

    不要在某个检查失败后强制推进升级。VersionUpgradePath 和 KubernetesVersionSupported 约束的是受支持的升级路径本身，而绕过它们的升级会使集群进入平台未验证的状态。如果无法根据本页面解决某个阻塞项，请在继续之前联系技术支持。

    部署 cluster version operator

    时间： 维护窗口开始时。

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

    bash upgrade.sh --skip-sync-image

    这会部署或更新 cluster version operator（CVO），并完成剩余准备工作。一旦下一步请求升级，CVO 就会驱动 Core 和 Aligned 插件的升级。

    请求升级

    在部署 cluster version operator 之后，可通过以下任一入口请求升级。这三个入口是等价的；请选择最适合你操作模式的一个。

    Web Console
    ACP CLI
    kubectl

    当目标版本对集群可用后，使用此入口。请求流程分两步：

    • 在 Step 1 中，查看 RPCH 列表。
    • 点击 Acknowledge 继续到 Step 2。
    • 在 Step 2 中，查看 Current Version 和 Target Version。此阶段页面不会显示插件列表或警告面板。
    • 目标版本由已准备好的升级制品决定，无法在 Web Console 中手动选择。
    • 点击 Start Upgrade。
    • 在对话框中确认操作。
    • 确认后，页面会显示升级请求已提交，操作进入进行中状态。

    观察执行情况

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

    kubectl get cvsh -n cpaas-system

    重要状态字段：

    字段作用
    status.conditions整体状态入口。
    status.preflight.observedAt最近一次 preflight 运行时间。
    status.preflight.checks每个 preflight 项的详细结果。
    status.current当前已应用的版本和镜像。
    status.desired正在协调的目标版本和镜像。
    status.history升级历史，最新记录在前。
    status.stages升级阶段及每个阶段的执行状态。

    首先关注这些条件：

    条件解释
    PreflightReadyTrue 表示 preflight 通过。
    ReadyTrue 表示集群已达到目标版本。
    ReconcilingTrue 表示升级仍在运行中。
    StalledTrue 表示升级已被阻塞，需要介入。

    有用的诊断信息：

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

    从缺失的 Aligned 集群插件包中恢复

    如果 Stalled=True 且条件消息指明某个 ModulePluginConfig 缺失或未就绪，则表示某个已安装的 Aligned 集群插件尚未获得其目标包：

    1. 从 Stalled 条件消息中识别组件和所需版本。
    2. 下载 Customer Portal 为目标 ACP Distribution Version 提供的包。
    3. 按照 同步升级制品 中的说明使用 violet push 将该集群插件包发布到 global 层。
    4. 继续观察现有升级请求。CVO 会监视包的就绪状态，并在包就绪后自动恢复；不要清除或重新提交 desiredUpdate。

    上述命令跟踪的是集群级别（Core 和 Aligned）的升级。若要观察单个插件或 operator 模块——例如在升级 Agnostic 插件时——请改为读取其 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 等于目标版本时，表示该模块已达到目标状态。

    （条件性）升级 Service Mesh Essentials

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

    从 Marketplace 升级 Agnostic 插件

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

    对于 global 集群上每个正在使用的 Agnostic 插件：

    1. 在 Web Console 中切换到 Administrator 视图。
    2. 对于 Agnostic 集群插件，进入 Marketplace > Cluster Plugins；对于 Agnostic operator，则进入对应的 operator 工作流。
    3. 选择目标插件或 operator 并触发升级。Marketplace 升级流程会读取之前由 violet 推送的包。

    如果你在升级前跳过了 Agnostic 插件的推送，而 Marketplace 未提供目标版本，请先完成 violet push 步骤，然后重试 Marketplace 升级。

    升级后

    • 升级 Alauda AI
    • 升级 Alauda DevOps

    • 在所有业务集群也都达到 ACP 4.3 后，请按照 禁用 PKCE Plain 方法 完成 PKCE 加固。

    • ACP 4.3 修复了一个 API 认证问题：此前某些 API 可以在未认证的情况下访问。在 global 集群达到 ACP 4.3 后，请将以下 L5 插件升级到与 ACP v4.3 兼容的版本。否则，其 UI 页面可能无法打开：

      • Alauda DevOps v3
      • Alauda AI Essentials
      • Alauda Hyperflux
      • Alauda Container Platform Data Services Essentials

    • 升级插件后，请确认上述每个插件的 UI 页面都能成功打开。

    Global DR Procedure

    当环境同时包含一个主 global 集群和一个备用 global 集群时，请使用此操作步骤。下面这些 DR 特定步骤是对标准 CVO 工作流的补充。

    在升级前验证 DR 环境

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

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

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

    kubectl get machines.platform.tkestack.io

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

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

    1. 通过备用 global 集群的 IP 或 VIP 访问其 Web Console。
    2. 切换到 Administrator 视图。
    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. 部署 cluster version operator
    3. 请求升级
    4. 观察执行情况，直到备用 global 集群达到目标版本

    升级主 global 集群

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

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

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

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

    要重新安装该插件：

    4.3.1+
    4.3.0

    1. 在 cpaas-system 中创建或更新 etcd-sync-active-cluster-token Secret。首先，从活动的 global 集群获取用于访问活动 global 集群 API server 的 bearer token。然后复制命令输出，并在创建 Secret 时使用它。该 Secret 将 token 存储在 data key token 下。通过 Active Global Cluster Token Secret 使用此 Secret。旧的纯 token 配置仅作为兼容性回退保留，不是推荐的运维路径。

      # Run this command on the active cluster.
kubectl -n cpaas-system get secret k8sadmin -o jsonpath='{.data.token}' | base64 -d

      复制输出值，然后在备用集群上运行此命令：

      ACTIVE_CLUSTER_TOKEN='<paste-the-token-from-the-active-cluster>'
kubectl -n cpaas-system create secret generic etcd-sync-active-cluster-token \
  --from-literal=token="${ACTIVE_CLUSTER_TOKEN}" \
  --dry-run=client -o yaml | kubectl apply -f -

    2. 通过备用 global 集群的 VIP 访问其 Web Console，并切换到 Administrator 视图。

    3. 导航到 Marketplace > Cluster Plugins 并选择 global 集群。

    4. 找到 etcd Synchronizer，点击 Install，并配置所需参数。

    配置插件时：

    • 将 Active Global Cluster VIP 设置为活动 global 集群的 VIP。
    • 当端口 2379 未通过负载均衡器转发时，正确设置 Active Global Cluster ETCD Endpoints。
    • 将 Standby Cluster ETCD Endpoints 设置为备用集群 etcd 地址。除非本地 etcd 服务通过其他端点暴露，否则使用默认值。
    • 将 Active Global Cluster Token Secret 设置为 etcd-sync-active-cluster-token。
    • 使用 Data Check Interval 的默认值。
    • 除非正在排障，否则保持 Print detail logs 关闭。

    在重新安装期间，系统会在 etcd-sync Deployment 启动之前运行 etcd-sync-bootstrap Job。只有在该 Job 准备好 remote-etcd-ca、remote-etcd-issuer 和 remote-etcd-client 之后，发布才会继续。

    验证 bootstrap Job 和运行时资源：

    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 在备用 global 集群上运行，并识别当前 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 存在于主 global 集群，但在备用集群中缺失。通常在重启当前 etcd-sync leader Pod 后可解决。
    • LOCAL ETCD surplus keys：这些 key 存在于备用 global 集群，但不在主 global 集群中。在删除它们之前，请与运维团队一起审查。

    相关文档