Alauda Container Platform
  • 简体中文

    • 升级 global 集群

    升级路径

    本页介绍 global 集群的传统操作系统路径。如果你的 global 集群运行在 Immutable Infrastructure（Huawei DCS 上的 Alauda OS、VMware vSphere 或 Huawei Cloud Stack）上，Kubernetes 步骤位于 Immutable Infrastructure 文档中 — 请参见 在 Immutable Infrastructure 上升级 global 集群。本页描述的 Core、Aligned 和 Agnostic 步骤仍然适用于 immutable-OS 集群；不同之处仅在于 Kubernetes 的发布方式。

    MySQL-PXC Removed in Alauda Database Service for MySQL v4.3.0

    升级 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，此兼容版本前置条件都适用。global DR 会改变用于升级 global 层的操作步骤，但不会改变这样一个要求：在 global 层升级到目标 Distribution Version 之前，业务集群必须始终保持在兼容的 Kubernetes 版本范围内。

    global 集群升级遵循本页文档中经过验证的 upgrade.sh 方案。你可以通过 Web Console、更新 ClusterVersionShadow.spec.desiredUpdate，或者使用带 --cluster=global 的 ACP CLI 发起 global 集群升级。关于完整的 AC CLI 工作流和输出解读，请参见 升级集群。关于完整的命令和 flag 语法，请参见 AC CLI 管理员命令参考。

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

    目录

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

    标准工作流

    global 集群升级会按时间线分阶段执行。大部分工作都会在维护窗口之前完成，这样窗口本身就能保持短而可预测：

    阶段时间发生什么对集群的影响
    1. 同步制品维护窗口前的任意时间upgrade.sh --only-sync-image 会将镜像和插件制品上传到 registry；violet 会推送 Aligned 和 Agnostic 插件。无 — 仅 registry 操作，无停机。
    2. 预检维护窗口前 1–2 周upgrade.sh --preflight 验证升级准备情况。请在窗口开启前解决所有阻塞项。无 — 只读验证。
    3. 升级维护窗口期间upgrade.sh --skip-sync-image 会部署或更新集群版本 operator（CVO）；随后会发起升级并观察升级状态。集群正在升级。

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

    同步升级制品

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

    在解压后的 core package 目录中，运行仅同步模式的 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。Aligned 和 Agnostic 插件不会由 upgrade.sh 推送；请在发起升级请求之前，使用 升级前准备 中下载的包，通过 violet 推送它们。

    生命周期类型推送工具集群插件Operators
    Aligned 插件violet push向 global 层推送一次。被推送的集群插件将可在平台中的每个集群上安装和升级。推送到 global 层，同时也推送到每个运行该 operator 的业务集群。建议在 global 窗口期间将 operator 推送到每个 集群；这样业务升级窗口就可以直接继续，而无需额外的推送步骤。
    Agnostic 插件violet push同上。同上。
    # Push Aligned plugins (cluster plugins) — global only
violet push <path/to/aligned-cluster-plugin-package> \
  --target-catalog-source "platform" \
  --platform-address "https://<your-platform-domain>" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

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

    建议在 global 窗口中把每个 operator 包都推送到每个 集群。如果 global 窗口已经结束，而你后来发现某个业务集群缺少 operator 包，那么在业务升级之前仍然可以先把它推送到该业务集群 — 请参见 升级业务集群。

    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 地址。
    --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=4.3.0 \
  --overwrite

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

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

    部署集群版本 operator

    何时： 在维护窗口开始时。

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

    bash upgrade.sh --skip-sync-image

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

    请求升级

    在集群版本 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最近一次预检运行时间。
    status.preflight.checks每个预检项的详细结果。
    status.current当前已应用的版本和镜像。
    status.desired正在协调的目标版本和镜像。
    status.history升级历史，最新记录在前。
    status.stages升级阶段及每个阶段的执行状态。

    先关注以下 conditions：

    Condition含义
    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}'

    （条件）升级 Service Mesh Essentials

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

    从 Marketplace 升级 Agnostic 插件

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

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

    1. 在 Web Console 中切换到 Administrator 视图。
    2. 导航到 Marketplace > Cluster Plugins 查看 Agnostic 集群插件，或进入 Agnostic operator 的 operator 工作流。
    3. 选择目标插件或 operator 并触发升级。Marketplace 升级流程会读取先前通过 violet 推送的包。

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

    升级后

    • 升级 Alauda AI
    • 升级 Alauda DevOps

    • 在所有业务集群也都达到 ACP 4.3 之后，请按照 禁用 PKCE Plain Method 完成 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 reference 解析错误，并且业务集群的 Machine 对象 — 包括 immutable-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. 部署集群版本 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 集群获取用于访问活动 global 集群 API server 的 bearer token。然后复制命令输出，并在创建 Secret 时使用它。该 Secret 会将 token 存储在数据键 token 下。请通过 Active Global Cluster Token Secret 使用此 Secret。旧的 plain-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-bootstrap Job，然后才启动 etcd-sync Deployment。只有在该 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}' 返回非空值。

    验证同步 Pods 正在备用 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 集群中，但在主集群中不存在。请在删除之前与运维团队一起确认这些 key。

    相关文档