Alauda Container Platform
  • 简体中文

    • 升级 global 集群

    Upgrade Path

    本页面介绍 global 集群的传统操作系统路径。如果您的 global 集群运行在 Immutable Infrastructure（Huawei DCS、VMware vSphere 或 Huawei Cloud Stack 上的 Alauda OS）上，Kubernetes 步骤请参阅 Immutable Infrastructure 文档 — 在 Immutable Infrastructure 上升级 global 集群。本页面介绍的 Core、Aligned 和 Agnostic 步骤仍适用于 immutable-OS 集群；区别仅在于 Kubernetes 的推出方式不同。

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

    升级 global 集群也会升级 MySQL operator。如果您有 PXC 实例，则这些实例将在 operator 升级后变为非托管状态。请在升级前参阅 MySQL Operator 升级指南，了解迁移说明。

    由一个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，此 Compatible Versions 先决条件均适用。Global DR 会改变升级 global 层所使用的操作步骤，但不会改变以下要求：在将 global 层升级到目标 Distribution Version 之前，业务集群必须保持在兼容的 Kubernetes 版本范围内。

    Global 集群升级遵循本页面记录的、基于 upgrade.sh 的经过验证的操作步骤。您可以通过 Web Console 请求升级 global 集群，也可以通过更新 ClusterVersionShadow.spec.desiredUpdate 来请求升级，或者使用 ACP CLI 和 --cluster=global 请求升级。有关完整的 AC CLI 工作流和输出说明，请参阅升级集群。有关完整的命令和标志语法，请参阅 AC CLI 管理员命令参考。

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

    目录

    标准工作流升级后Global DR 操作步骤相关文档

    标准工作流

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

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

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

    同步升级制品

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

    从提取的 Core 软件包目录中，以仅同步模式运行 upgrade.sh：

    bash upgrade.sh --only-sync-image

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

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

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

    upgrade.sh 涵盖 Core。upgrade.sh 不会推送 Aligned 和 Agnostic 插件；请在请求升级之前，使用从升级前准备下载的软件包，通过 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 插件的目标软件包。对于未安装的 Aligned 插件，CVO 不要求其软件包。如果已安装的 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

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

    升级前检查会返回两部分内容：

    输出用途
    Summary显示总体结果、当前版本、期望版本和期望镜像。
    Checks显示每个单独验证项的结果。

    默认检查集包括：

    • 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=<target-version> \
  --overwrite

    豁免项按主版本和次版本匹配，因此，为某个补丁版本记录的豁免也适用于同一次版本发布中的其他补丁版本。

    豁免某个补丁表示升级会保留该自定义内容。这不会验证该自定义内容在目标版本上是否仍然有效 — 请向提供该自定义内容的技术支持联系人确认。

    解决其他常见的升级前检查阻塞项

    默认检查集还会验证其他多个条件。列出所有不是 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 版本处于目标版本发布所支持的范围内。如果低于支持范围，请先将集群的 Kubernetes 升级到该范围内 — 请参阅Kubernetes 支持矩阵。
    VersionUpgradePath当前版本可以通过受支持的升级路径到达请求的目标版本。确认当前版本是目标版本发布所支持的源版本；如果不是，请先升级到受支持的中间版本。
    ClusterRunning集群运行正常且已完成调谐。使用 kubectl get clusterview global 检查集群，并在重试之前解决任何运行不正常的节点或组件。
    DockerRuntimeUnsupported没有节点仍在使用不受支持的 Docker 运行时。在升级之前，将受影响的节点迁移到 containerd。
    ClusterModuleStable、ModuleInfoStable已安装的 Core 和 Aligned 模块处于稳定状态（Running），而非正在部署或升级。请参阅升级前验证模块稳定性。

    不要强制绕过失败的检查执行升级。VersionUpgradePath 和 KubernetesVersionSupported 会控制受支持的升级路径本身，绕过它们的升级会使系统进入平台尚未验证的状态。如果无法根据本页内容解决阻塞项，请在继续操作之前联系技术支持。

    部署集群版本 operator

    时间：维护窗口开始时。

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

    bash upgrade.sh --skip-sync-image

    此操作会部署或更新集群版本 operator（CVO），并完成剩余准备工作。在下一步请求升级后，CVO 会驱动 Core 和 Aligned 插件升级。

    请求升级

    部署集群版本 operator 后，通过以下入口之一请求升级。这三个入口是等效的；请选择符合你操作模式的入口。

    Web Console
    ACP CLI
    kubectl

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

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

    观察执行情况

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

    kubectl get cvsh -n cpaas-system

    重要状态字段：

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

    首先关注以下条件：

    条件解释
    PreflightReadyTrue 表示升级前检查已通过。
    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 操作步骤

    当环境同时包含主 global 集群和备用 global 集群时，请使用此操作步骤。以下 DR 专属步骤是在标准 CVO 工作流的基础上执行的。

    升级前验证 DR 环境

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

    如果检测到不一致，请勿在下一步卸载 etcd 同步插件，并在继续操作前联系技术支持。如果备用 global 集群缺少主集群中的数据，卸载插件可能会导致 owner 引用解析错误，并可能删除业务集群节点 Machine 对象；对于 immutable-OS 集群，删除这些节点对象会销毁其底层虚拟机。

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

    kubectl get machines.platform.tkestack.io

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

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

    1. 通过 IP 或 VIP 访问备用 global 集群的 Web Console。
    2. 切换到 Administrator 视图。
    3. 导航到 Marketplace > Cluster Plugins 并选择 global 集群。
    4. 找到 Global Cluster Disaster Recovery（重命名前发布的软件包显示为 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. 部署集群版本 operator
    3. 请求升级
    4. 观察执行情况，直到备用 global 集群达到目标版本

    升级主 global 集群

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

    1. 运行预检
    2. 部署集群版本 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 集群获取用于访问其 API server 的 bearer token。然后复制命令输出，并在创建 Secret 时使用该值。Secret 使用数据键 token 存储此令牌。通过 Active Global Cluster Token Secret 使用此 Secret。旧版明文令牌配置仅作为兼容性回退方案保留，不建议在运维中使用。

      # 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. 通过 VIP 访问备用 global 集群的 Web Console，并切换到 Administrator 视图。

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

    4. 找到 Global Cluster Disaster Recovery（重命名前发布的软件包显示为 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-bootstrap Job，然后启动 etcd-sync Deployment。只有 Job 完成 remote-etcd-ca、remote-etcd-issuer 和 remote-etcd-client 的准备工作后，版本发布才会继续。

    验证引导 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}' 返回非空值。

    验证备用 global 集群上的同步 Pod 正在运行，并确认当前 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：主 global 集群中存在这些键，但备用集群中缺少。通常，重启当前 etcd-sync leader Pod 后即可解决。
    • LOCAL ETCD surplus keys：备用 global 集群中存在这些键，但主集群中没有。删除前请与运维团队一起审核这些键。

    相关文档