#升级集群

AC CLI 提供管理员命令，用于准备升级元数据、查看集群升级状态，以及请求集群升级。

当你需要执行以下操作时，请使用这些命令：

• 为目标版本创建一个 ProductManifest
• 检查当前集群版本和可用更新
• 请求升级到最新版本
• 请求升级到特定版本
• 查看预检结果和升级执行进度

#开始之前

在 ACP 中，availableUpdates 不是一个需要你手动维护的静态列表。升级控制器必须先看到目标版本的 ProductManifest，才能为集群发布可用的升级目标。

如果你没有先创建 ProductManifest，常见症状包括：

• ac adm upgrade 不显示任何 availableUpdates
• ac adm upgrade --to-latest 立即失败
• 你只能使用 --allow-explicit-upgrade 手动请求某个版本

建议的流程如下：

1. 确定你要发布或升级到哪个版本。
2. 为该版本创建一个 ProductManifest。
3. 等待升级元数据被处理。
4. 运行 ac adm upgrade，确认 availableUpdates 已填充。
5. 请求升级。

#前提条件

在运行与升级相关的命令之前，请确保：

• 你已登录到 ACP 平台。
• 你拥有集群管理员或等效权限。
• 你知道目标集群名称。如果省略，ac adm upgrade 默认使用 global。
• 目标环境已经安装了 ProductManifest CRD 和升级控制器。

你可以先确认当前上下文：

ac config current-context

当前上下文仍然决定 AC 在命令中使用哪些凭据和 endpoint。

• 对于 ac adm upgrade 和 ac adm upgrade status，目标集群仍通过 --cluster 显式选择，默认值为 global。
• 对于 ac adm release import-manifest，AC 会先检查当前上下文的 REST URL。如果它指向 ACP workload 路径，AC 会自动将请求重写为对应的 global 路径。如果当前上下文不是 ACP workload/global URL，AC 会按原样使用当前上下文，并且不需要 kubeconfig session extension。

如有需要，先切换到另一个 ACP session：

# Switch to another ACP session
ac config use-session production

#创建 ProductManifest

使用以下命令为目标版本创建一个 ProductManifest：

ac adm release import-manifest --version 4.20.0

此命令会创建控制器所需的最小升级元数据对象：

• metadata.name 使用带前缀 v 的版本名，例如 v4.20.0
• spec.version 使用你传入的版本，例如 4.20.0

如果你希望命令等待对象变为 Ready，请添加 --wait：

ac adm release import-manifest --version 4.20.0 --wait

你也可以覆盖等待超时时间：

ac adm release import-manifest --version 4.20.0 --wait --timeout=10m

命令行为：

• 必须提供 --version。
• 如果 ProductManifest 不存在，AC 会创建它。
• 如果 ProductManifest 已存在且版本相同，命令会成功，但不会修改它。
• 如果 ProductManifest 已存在但版本不同，命令会失败，不会覆盖现有对象。
• 默认情况下，命令不会等待 Ready。只有显式传入 --wait 时才会等待。

#查看升级状态和可用更新

在创建 ProductManifest 之后，使用以下命令查看默认 global 集群的升级摘要：

ac adm upgrade

此命令通常会显示：

• 当前集群版本
• 期望版本（如果已经请求了升级）
• 当前可用更新列表
• 整体升级条件

当你想快速回答以下问题时，可以使用它：

• 集群当前运行的是什么版本？
• 是否已经请求了目标版本？
• 现在是否有新的升级目标可用？
• 集群当前是 Ready、Reconciling 还是 Degraded？

如需查询特定集群，请添加 --cluster：

ac adm upgrade --cluster=workload-a

如果你刚创建了 ProductManifest，但仍然看不到 availableUpdates，控制器可能还在处理元数据。稍等片刻后再次运行 ac adm upgrade。

#升级到最新版本

当 availableUpdates 存在时，使用以下命令请求升级到最新版本：

ac adm upgrade --to-latest

AC 会从 availableUpdates 中选择最高版本并提交升级请求。

--to-latest 是一个布尔标志，默认值为 false，这意味着：

• 如果你不指定它，AC 的行为等同于使用了 --to-latest=false。
• 如果你单独指定 --to-latest，AC 会将其视为 true。
• 你也可以显式写成 --to-latest=true 或 --to-latest=false。

如果不存在任何 availableUpdates，命令会失败，不会提交新的目标版本。

请求升级后，再次查看摘要：

ac adm upgrade

#升级到特定版本

如果你想升级到特定版本，请运行：

ac adm upgrade --to=<version>

示例：

ac adm upgrade --to=4.20.0

典型场景包括：

• 你不想使用最新的可用版本
• 你正在遵循发布流程中批准的发布目标
• 你想重试一个已知目标版本

默认情况下，请求的版本必须已经出现在 availableUpdates 中。否则，命令会失败。

如果你确实需要请求一个未列在 availableUpdates 中的版本，请添加：

ac adm upgrade --to=<version> --allow-explicit-upgrade

--allow-explicit-upgrade 的默认值为 false：

• 如果你不指定它，AC 的行为等同于使用了 --allow-explicit-upgrade=false。
• 如果你单独指定 --allow-explicit-upgrade，AC 会将其视为 true。
• 你也可以显式写成 --allow-explicit-upgrade=true 或 --allow-explicit-upgrade=false。

示例：

ac adm upgrade --to=4.20.0 --allow-explicit-upgrade=true

此标志只会更改客户端侧校验。升级控制器及其预检检查仍会决定所请求的目标是否可以继续执行。

#查看详细升级状态

如果你需要更深入的诊断，请运行：

ac adm upgrade status

如需查看特定集群：

ac adm upgrade status --cluster=workload-a

与 ac adm upgrade 相比，此命令会展开显示：

• 当前版本、期望版本和整体条件的摘要
• 当前升级目标的预检结果
• 升级阶段和操作进度

#预检结果

预检用于描述升级是否可以进入执行阶段。每项检查通常包含：

• 检查名称
• 重入策略
• 状态
• 原因
• 消息

状态含义如下：

• Passed：检查已通过。
• Retry：检查暂时无法给出最终结果。请稍后再查看。
• Failed：存在阻塞条件，必须先处理。

如果当前还没有预检数据，请将其视为“暂无结果”，而不是“所有检查都已通过”。

如果 AdminAckRequired 为 Failed，则当前升级目标适用管理员确认门控。请查看该门控，完成所需的手动检查，写入确认，然后再次运行 ac adm upgrade status --cluster=<cluster>，确认检查通过。

#升级阶段

当升级进入执行阶段后，状态输出会显示阶段和操作进度。

阶段输出可能包含：

• 阶段名称
• 优先级
• 阶段状态

操作输出可能包含：

• 操作名称
• 动作
• 当前版本
• 目标版本
• 阶段状态

阶段状态含义如下：

• Pending：该阶段尚未开始。
• Running：该阶段正在进行中。
• Finished：该阶段已完成。

如果当前还没有阶段数据，升级很可能尚未进入执行阶段。

#常见信号和故障排查

阅读升级状态时，请参考以下指导：

• Ready 通常表示集群已达到期望状态。
• Reconciling 通常表示集群仍在应用当前升级请求。
• Degraded 通常表示升级被阻塞或发生了错误。

当 ac adm upgrade 没有显示任何 availableUpdates 时，请先检查以下内容：

1. 是否已为目标版本创建 ProductManifest？
2. 如果你使用了 --wait，ProductManifest 是否已达到 Ready=True？
3. 控制器是否有足够时间处理新的元数据？

当 ac adm upgrade 显示了目标版本，但升级没有推进时：

1. 运行 ac adm upgrade status。
2. 检查是否有任何预检项处于 Retry 或 Failed。
3. 查看升级阶段是否已经开始。

当 ac adm upgrade status --cluster=<cluster> 显示 AdminAckRequired 处于 Failed 状态时：

1. 从 global 集群检查发行版提供的门控：

   kubectl -n cpaas-system get configmap admin-gates -o yaml

2. 如果目标发行版是 ACP 4.4 或更高版本，且会将集群升级到 Kubernetes 1.35 或更高版本，并且 admin-gates 报告了一个节点就绪确认键，请在目标集群的每个生产节点上完成 Kubernetes 1.35 或更高版本节点就绪检查。此要求引入的第一个门控是 ack-4.4-kubernetes-1.35-kernel-update；请将其视为示例，因为更晚的目标发行版可能会提供不同的键。

3. 完成门控要求后，从 admin-gates 复制适用的键，并将其写入 global 侧的 admin-acks ConfigMap：

   ACK_KEY='<key-from-admin-gates>'
   kubectl -n cpaas-system patch configmap admin-acks --type merge \
     -p "{\"data\":{\"${ACK_KEY}\":\"true\"}}"

4. 确认预检检查通过：

   ac adm upgrade status --cluster=<cluster>

当升级已经在进行中时：

1. 运行 ac adm upgrade status。
2. 查看当前阶段和操作状态。
3. 将当前版本与目标版本进行比较。

#示例工作流

# 1. Create a ProductManifest for the target version
ac adm release import-manifest --version 4.20.0 --wait

# 2. Review the upgrade summary for the default global cluster
ac adm upgrade

# 3. Review the summary for a specific cluster
ac adm upgrade --cluster=workload-a

# 4. Request an upgrade to the latest available version
ac adm upgrade --to-latest

# 5. Review detailed status
ac adm upgrade status --cluster=workload-a

# 6. Request an upgrade to a specific version
ac adm upgrade --cluster=workload-a --to=4.20.0

# 7. Request a version outside availableUpdates when you explicitly intend to do so
ac adm upgrade --cluster=workload-a --to=4.20.0 --allow-explicit-upgrade