原文：https://dev.to/googlecloud/two-step-control-plane-upgrades-in-gke-how-minor-version-rollbacks-work-under-the-hood-i1l（作者 @olivi-eh）
Kubernetes 控制平面小版本升级过去一直是一种“要么全做、要么不做”的操作。在标准 Kubernetes 集群中，将控制平面从一个小版本升级到下一个小版本——例如从 1.33 升级到 1.34——时，存储结构变更会立即提交。如果升级 API server 后出现意外回归，在不恢复 etcd 快照的情况下，就无法回滚到上一个次版本。
为消除这一运维风险，GKE 团队推动了上游 Kubernetes Enhancement Proposal KEP-4330 (Compatibility Versions) 的贡献，并推出了两步控制平面升级。在企业客户公开预览验证之后，该能力已在所有 GKE 发布通道正式可用（GA）。
本文将解释两步升级的底层工作原理、自动化发布如何借助金丝雀分析，以及如何使用 Google Cloud CLI 和 Terraform 管理可安全回滚的升级。
小版本升级的问题
在 Kubernetes 中，小版本发布会引入存储结构变更、废弃 API 移除以及控制器行为变化。当 kube-apiserver 二进制文件以更新的小版本启动时，它会使用更新的内部结构写入资源。
由于较早版本的二进制文件无法解析以较新结构存储的数据，Kubernetes 禁止控制平面跨小版本降级。如果组织在升级后遇到问题，平台运维人员只能继续运行状态受损的控制平面，或者重建集群。
两步升级将二进制执行与 API 能力启用解耦。通过把升级拆分为两个明确阶段，GKE 提供了一个观察窗口（也称为 soak window）。在此期间，运维人员或自动化系统可以监控集群行为，并将控制平面零数据丢失地回滚到上一个次版本。
将二进制执行与模拟版本解耦
两步升级的基础，是让更新的控制平面二进制运行在模拟兼容模式下。
当两步升级开始时，GKE 会按两个连续阶段推进控制平面：
- 第 1 步：二进制升级（模拟模式）：GKE 将控制平面二进制升级到目标小版本（例如 1.34），但将 API server 配置为模拟上一个次版本（1.33）。在这种状态下，控制平面执行新的二进制逻辑，但 API 结构仍与旧版本一致。在 1.34 中被移除的 API 仍然可以访问。在这个观察期内，你可以安全回滚到 1.33。
- 第 2 步：模拟版本升级（定版）：如果观察窗口结束且没有事故，GKE 会更新模拟版本，使其与二进制版本一致。这一步会永久启用新小版本的 API 结构和功能废弃策略。此后就无法再回滚。
在观察期内，为了遵守 Kubernetes 版本偏差策略，工作节点池不能升级到超过模拟版本。
使用 CPRS 和 Canary Analysis Service 自动编排
对于配置了自动升级的集群，两步升级开箱即用，无需手动配置。GKE 的发布引擎名为 Control Plane Rollout Service（CPRS），会原生编排这个分阶段生命周期：
- CPRS 升级控制平面二进制，同时将模拟版本锁定在上一个次版本。
- CPRS 启动一个自动化的 24 小时观察窗口。
- Canary Analysis Service（CAS）在整个观察期内监控集群健康信号，包括 API 延迟、错误率和 Pod 健康指标。
- 如果 CAS 检测到意外回归，发布会暂停，以便执行自动或用户触发的回滚。
- 当集群通过所有 CAS 评估并满足观察时间后，CPRS 会触发第 2 步，完成模拟版本定版。
这套验证框架帮助 GKE 控制平面升级在全球集群范围内达到了 99.999%（五个九）的滚动 30 天成功率。
手动发起两步升级
如果你的团队手动管理升级，可以使用 Google Cloud CLI 或 Terraform 执行两步升级。
要使用 gcloud 发起带有自定义浸泡时长的两步升级：
gcloud beta container clusters upgrade my-cluster \
--location=us-central1 \
--cluster-version=1.34.1-gke.1829001 \
--control-plane-soak-duration=48h \
--master
--control-plane-soak-duration 参数定义了可回滚安全窗口，支持从 6 小时到 7 天的取值范围（例如 48h 或 2d）。
对于基础设施即代码工作流，Terraform 提供了官方支持，可以通过在 GKE 集群资源中指定目标版本和浸泡参数，以声明式方式管理两步控制平面升级。
验证升级状态并执行回滚
当集群处于模拟模式下进行浸泡时，你可以使用 CLI 检查当前的回滚状态：
gcloud container clusters describe my-cluster \
--location=us-central1 \
--format="yaml(rollbackSafeUpgradeStatus)"
输出中会包含一个 rollbackSafeUpgradeStatus 块，其中包含目标二进制版本、模拟版本、剩余浸泡时间以及 previousVersion 字符串。
如果你的监控工具在浸泡窗口期间发现了回归问题，你可以将控制平面回滚到上一个次要补丁版本：
gcloud container clusters upgrade my-cluster \
--location=us-central1 \
--cluster-version=1.33.5-gke.1080000 \
--master
由于控制平面运行在模拟模式下，新的数据格式并没有被写入 etcd。GKE 会将控制平面二进制文件降级回指定版本，而不会带来数据损坏风险。
提前完成升级
如果你的验证测试已经通过，并且希望立即解锁新次要版本的功能，而不等待浸泡时长结束，可以手动完成升级：
gcloud beta container clusters clusters complete-control-plane-upgrade my-cluster \
--location=us-central1
执行后，GKE 会将模拟版本提升为与二进制版本一致，从而完成升级。
运维要求与限制
在规划两步控制平面升级时，需要注意以下运维规则：
- 两步升级适用于目标版本为 GKE 1.33 及更高版本的次要版本升级。
- 控制平面升级必须一次只升级一个次要版本。
- 维护窗口和排除规则会被严格遵守。
- Autopilot 和区域级 Standard 集群在两个阶段期间都会保持控制平面持续可用。
下一步
两步控制平面升级消除了 Kubernetes 中不可逆次要版本更新的风险，为平台工程师提供了自动化安全机制和紧急回滚机制。
如需进一步了解如何配置两步升级，可以阅读官方 GKE 集群升级文档，并查看 KEP-4330: Compatibility Versions。
原文：https://dev.to/googlecloud/two-step-control-plane-upgrades-in-gke-how-minor-version-rollbacks-work-under-the-hood-i1l（作者 @olivi-eh）
