📚 课程目录第4章回滚基础

4. 回滚基础：kubectl rollout undo 命令详解、回滚到指定版本、回滚历史查看

在 Kubernetes 的日常运维中，kubectl rollout undo 是最核心的故障恢复命令之一。它允许运维人员将 Deployment、DaemonSet 或 StatefulSet 快速回退到上一个稳定版本，从而在发布故障时实现秒级止血。本章将深入剖析该命令的完整用法、回滚历史查看机制以及版本控制原理。

4.1 回滚核心命令：kubectl rollout undo

kubectl rollout undo 的基本语法如下：

kubectl rollout undo <资源类型>/<资源名称> [--to-revision=<版本号>] [-n <命名空间>]

该命令的核心行为是：将 Pod 模板（PodTemplate）替换为指定历史版本（Revision）的模板，并触发新一轮滚动更新。下表列出了常用参数及其作用：

参数	默认值	说明
`--to-revision`	无（回滚到上一个版本）	指定要回滚到的目标版本号，可通过 `rollout history` 查看
`--dry-run`	none	支持 `client` 或 `server` 模式，用于预检回滚操作
`-n / --namespace`	default	指定目标资源所在的命名空间
`--timeout`	5m	回滚操作等待 Pod 就绪的超时时间

最佳实践：在生产环境中执行回滚前，始终先使用 --dry-run=client 验证命令语法，再使用 --dry-run=server 检查 API Server 是否接受该操作，最后才执行实际回滚。

4.2 回滚到指定版本：版本号与 Revision 机制

Kubernetes 的 Deployment 控制器会自动为每次 Pod 模板变更生成一个递增的 Revision（修订版本号）。Revision 存储在 Deployment 的 .metadata.annotations 中，键为 deployment.kubernetes.io/revision。回滚到指定版本的本质是：将当前 Deployment 的 Pod 模板替换为对应 Revision 的历史模板。

以下是一个典型的回滚到指定版本的操作流程：

查看历史版本列表：使用 kubectl rollout history 获取所有 Revision 及其对应的镜像版本。
确认目标版本：根据输出确定要回滚到的 Revision 编号。
执行回滚：使用 --to-revision 参数指定目标版本。
验证回滚状态：使用 kubectl rollout status 监控回滚进度。

# 步骤1：查看历史版本
kubectl rollout history deployment/nginx-deployment

# 步骤2：回滚到 Revision 3
kubectl rollout undo deployment/nginx-deployment --to-revision=3

# 步骤3：监控回滚状态
kubectl rollout status deployment/nginx-deployment --watch

注意：Revision 编号是单调递增的，但回滚操作本身也会生成一个新的 Revision。例如，从 Revision 5 回滚到 Revision 3 后，当前版本会变成 Revision 6（其模板内容与 Revision 3 相同）。因此，Revision 编号不代表版本的新旧顺序，只代表变更发生的先后顺序。

4.3 回滚历史查看：rollout history 详解

kubectl rollout history 命令用于查看 Deployment、DaemonSet 或 StatefulSet 的变更历史。其输出包含每个 Revision 的变更原因（如果有）以及对应的 Pod 模板摘要。

基本用法：

# 查看所有历史版本列表
kubectl rollout history deployment/nginx-deployment

# 查看指定版本的详细信息（包括完整的 Pod 模板 YAML）
kubectl rollout history deployment/nginx-deployment --revision=3

默认情况下，Kubernetes 会保留最近 10 个 Revision（可通过 Deployment 的 .spec.revisionHistoryLimit 字段调整）。当 Revision 数量超过该限制时，最旧的 Revision 会被自动清理。

字段	位置	说明
`revisionHistoryLimit`	`.spec.revisionHistoryLimit`	保留的历史版本数量，默认 10，设置为 0 则关闭历史记录
`change-cause`	`.metadata.annotations.kubernetes.io/change-cause`	每次 `kubectl apply` 或 `kubectl set image` 时记录的变更原因

  故障排查技巧：当回滚失败时，首先使用 kubectl rollout history deployment/<名称> --revision=<版本号> 检查目标版本的 Pod 模板是否包含正确的镜像标签、环境变量和资源限制。常见失败原因包括：目标版本引用了不存在的镜像、镜像拉取策略导致权限错误、或资源请求超出集群容量。

4.4 回滚流程与状态转换

下图展示了从执行 kubectl rollout undo 到回滚完成的完整状态转换流程：

4.5 回滚操作对比：undo vs 手动修改模板

下表对比了 kubectl rollout undo 与手动编辑 Deployment 模板两种回滚方式的差异：

对比维度	kubectl rollout undo	手动修改模板（kubectl edit / apply）
操作复杂度	一行命令，自动匹配历史版本	需要手动查找并复制历史模板内容
版本追溯	基于 Revision 历史，可精确回滚	依赖操作者记忆或外部版本管理
变更记录	自动生成新的 Revision	覆盖当前 Revision，不产生新记录
回滚速度	与正常滚动更新速度一致	与正常滚动更新速度一致
适用场景	快速止血、标准回滚流程	需要同时修改多个字段或执行非标准回滚

推荐做法：在自动化回滚护栏中，优先使用 kubectl rollout undo 作为默认回滚策略。仅在需要同时调整资源配额、环境变量或挂载卷等非模板字段时，才考虑手动编辑 Deployment 模板。

4.6 回滚历史查看与版本清理策略

为了有效管理回滚历史，建议遵循以下策略：

设置合理的 revisionHistoryLimit：根据集群规模和发布频率调整。对于频繁发布的服务，建议保留 20-30 个版本；对于稳定服务，保留 5-10 个版本即可。
记录 change-cause：在每次 kubectl apply 时使用 --record 参数或手动添加 kubernetes.io/change-cause 注解，便于在历史列表中快速识别每个版本的变更内容。
定期清理旧版本：如果 revisionHistoryLimit 设置过大，旧版本的 ReplicaSet 会占用 etcd 存储空间。可通过 kubectl delete replicaset <名称> 手动清理不再需要的旧 ReplicaSet。

# 使用 --record 记录变更原因（K8s v1.22+ 已弃用，建议手动添加注解）
kubectl apply -f deployment.yaml --record

# 手动添加 change-cause 注解
kubectl annotate deployment/nginx-deployment kubernetes.io/change-cause="升级到 nginx:1.25.3"

注意：从 Kubernetes v1.22 开始，--record 参数已被弃用。建议在 CI/CD 流水线中通过 kubectl annotate 命令显式设置 kubernetes.io/change-cause 注解，以确保回滚历史可追溯。