AWS CLI `autoscaling rollback-instance-refresh` 实例刷新回滚命令实战指南

AWS CLIautoscaling rollback-instance-refresh实例刷新回滚命令实战指南

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

导读

aws autoscaling rollback-instance-refresh是 AWS CLI 中用于**回滚正在进行的实例刷新（Instance Refresh）**的核心命令：当 Auto Scaling 组（ASG）在滚动更新实例过程中出现健康问题或配置错误时，它可以立即撤销刷新已做的更改，将实例恢复到刷新前的状态。本文以仓库内的官方示例文档 rollback-instance-refresh.rst 为骨架，结合 AWS CLI 内置的 Auto Scaling 服务模型源码，完整讲解命令用法、参数约束、底层 API 映射、异常场景与限制条件，让你能够在生产环境中安全、精准地执行回滚操作。

命令概览：什么场景需要回滚实例刷新

实例刷新（Instance Refresh）是 Amazon EC2 Auto Scaling 提供的能力，用于在修改 ASG 的启动模板、AMI 等配置后，以滚动方式逐批替换组内实例而不中断服务。但在以下场景中，刷新可能失败或导致业务受损：

• 新启动模板或新 AMI 中的软件存在缺陷，实例无法通过健康检查；
• 新配置导致应用启动失败，实例进入不健康状态；
• 运维人员希望放弃本次变更，恢复到刷新开始前的旧配置。

此时rollback-instance-refresh会取消正在进行中的刷新，并回滚刷新已做出的所有替换：Auto Scaling 会重新用刷新前的旧配置替换那些在刷新期间被替换的实例，从而将 ASG 恢复到刷新开始前的状态。它是与 start-instance-refresh.rst、cancel-instance-refresh.rst 并列的实例刷新命令族成员，区别在于：

完整命令示例与输出解析

官方示例文档 rollback-instance-refresh.rst 给出了最小可用示例：对名为my-asg的 Auto Scaling 组执行回滚。

aws autoscaling rollback-instance-refresh \ --auto-scaling-group-name my-asg

输出示例：

{ "InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b" }

输出解析：

• InstanceRefreshId：与本次回滚关联的实例刷新 ID。根据服务模型 service-2.json 中RollbackInstanceRefreshAnswer的字段定义，这是该实例刷新在启动时被分配的唯一 ID，也是后续通过describe-instance-refreshes查询回滚进度的关键标识。

命令成功后，Auto Scaling 会立即开始替换实例，整个回滚是异步执行的，需要持续观察刷新状态确认回滚完成（详见下文"验证回滚结果"）。

参数详解：输入输出模型与约束

从服务模型源码RollbackInstanceRefreshType（见 service-2.json）可以看到，该命令的请求结构定义如下：

"RollbackInstanceRefreshType": { "type": "structure", "required": ["AutoScalingGroupName"], "members": { "AutoScalingGroupName": { "shape": "XmlStringMaxLen255", "documentation": "<p>The name of the Auto Scaling group.</p>" } } }

由此可以确认两个关键约束：

• --auto-scaling-group-name是唯一且必需的参数，类型为字符串，最长 255 个字符，值为 Auto Scaling 组的名称；
• 该命令不接受其他任何参数（没有可选的偏好设置、实例数量等选项），回滚策略由 Auto Scaling 组既有的实例刷新上下文决定。

返回结构RollbackInstanceRefreshAnswer仅包含一个成员InstanceRefreshId（XmlStringMaxLen255），即上面输出示例中的字段。

底层原理：从 CLI 命令到 API 调用的映射

在 AWS CLI 仓库中，Auto Scaling 的服务模型文件位于 awscli/botocore/data/autoscaling/2011-01-01/service-2.json，CLI 的所有autoscaling子命令都由该模型驱动生成。其中RollbackInstanceRefresh操作的元数据如下：

"RollbackInstanceRefresh": { "name": "RollbackInstanceRefresh", "http": { "method": "POST", "requestUri": "/" }, "input": {"shape": "RollbackInstanceRefreshType"}, "output": { "shape": "RollbackInstanceRefreshAnswer", "resultWrapper": "RollbackInstanceRefreshResult" }, "errors": [ {"shape": "LimitExceededFault"}, {"shape": "ResourceContentionFault"}, {"shape": "ActiveInstanceRefreshNotFoundFault"}, {"shape": "IrreversibleInstanceRefreshFault"} ] }

从源码结构可以推断出以下实现事实：

• 该操作通过POST /发送到 Auto Scaling 服务端点（https://autoscaling.<region>.amazonaws.com/），请求与响应均使用 XML 封装（resultWrapper字段表明响应会被包装为RollbackInstanceRefreshResult元素）；
• 命令执行成功后返回 200 及InstanceRefreshId；
• 与常见的"组不存在"类错误不同，该命令专门定义了ActiveInstanceRefreshNotFoundFault（找不到正在进行的实例刷新）与IrreversibleInstanceRefreshFault（当前刷新不可回滚）两类语义明确的错误，用于提示回滚失败的具体原因。

回滚不支持的场景与错误处理

根据服务模型RollbackInstanceRefresh的官方操作文档（同见 service-2.json），以下情况不支持回滚，调用会失败并抛出IrreversibleInstanceRefreshFault：

1. 实例刷新没有指定 desired configuration（启动刷新时未提供期望配置）；
2. ASG 的启动模板使用 AWS Systems Manager（SSM）参数而不是 AMI ID作为ImageId属性；
3. ASG 使用的启动模板版本为$Latest或$Default（回滚无法确定确切的旧版本镜像）。

此外，命令可能返回的其余错误类型包括：

因此，最佳实践是在调用回滚前先用describe-instance-refreshes确认该组确实存在状态为InProgress的刷新任务，并确认刷新是通过显式 desired configuration 发起的。

实战：配合启动与状态检查命令完成一次安全回滚

步骤 1：启动实例刷新（可选，用于演示）

先发起一次带期望配置的实例刷新。官方示例 start-instance-refresh.rst 展示了通过 JSON 文件指定配置与偏好的方式：

aws autoscaling start-instance-refresh \ --cli-input-json file://config.json

config.json内容：

{ "AutoScalingGroupName": "my-asg", "DesiredConfiguration": { "LaunchTemplate": { "LaunchTemplateId": "lt-068f72b729example", "Version": "$Default" } }, "Preferences": { "InstanceWarmup": 60, "MinHealthyPercentage": 50, "AutoRollback": true, "ScaleInProtectedInstances": "Ignore", "StandbyInstances": "Terminate" } }

需要注意：示例中启动刷新使用了Version: "$Default"，而根据上文提到的回滚限制，使用$Default或$Latest版本的刷新是无法回滚的。若要确保后续可回滚，应显式指定具体的模板版本号（如"Version": "2"）或直接使用 AMI 作为 desired configuration。

AutoRollback: true是刷新自身的自动回滚开关：当刷新进度无法满足MinHealthyPercentage时，Auto Scaling 会自动回滚本次刷新，无需人工干预。手动执行rollback-instance-refresh则用于在自动回滚未触发但你需要主动放弃变更的场景。

步骤 2：确认刷新正在进行

执行 describe-instance-refreshes.rst 中的命令查看当前状态：

aws autoscaling describe-instance-refreshes \ --auto-scaling-group-name my-asg

在输出中定位目标刷新，确认其Status为InProgress：

{ "InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b", "AutoScalingGroupName": "my-asg", "Status": "InProgress", "StatusReason": "Waiting for instances to warm up before continuing. For example: 0e69cc3f05f825f4f is warming up.", "PercentageComplete": 0, "Preferences": { "MinHealthyPercentage": 100, "InstanceWarmup": 300, "CheckpointPercentages": [50], "CheckpointDelay": 3600, "SkipMatching": false, "AutoRollback": true, "ScaleInProtectedInstances": "Ignore", "StandbyInstances": "Ignore" } }

步骤 3：执行回滚并验证结果

确认刷新正在进行后，执行回滚命令：

aws autoscaling rollback-instance-refresh \ --auto-scaling-group-name my-asg

返回的InstanceRefreshId与刷新 ID 一致。随后再次运行describe-instance-refreshes观察该 ID 的状态变化：回滚开始后，Auto Scaling 会立即用旧配置替换刷新期间被替换的实例；当状态最终变为Successful、PercentageComplete达到 100 时，表示 ASG 已恢复到刷新前的状态。

小结

• rollback-instance-refresh只接受--auto-scaling-group-name一个必填参数，输出唯一的InstanceRefreshId；
• 该命令的本质是调用 Auto Scaling 的RollbackInstanceRefreshAPI（POST /），其请求/响应结构与错误类型均可在 service-2.json 中核实；
• 使用$Latest/$Default模板版本、SSM 参数型 AMI、或无 desired configuration 发起的刷新不可回滚；
• 回滚前务必用describe-instance-refreshes确认存在InProgress的刷新任务；
• 与cancel-instance-refresh（仅取消）不同，回滚会撤销已做的实例替换，是生产环境"变更回退"的最后一道保险。

仓库内相关的全部命令示例与完整服务模型均可进一步查阅：rollback-instance-refresh.rst、start-instance-refresh.rst、cancel-instance-refresh.rst、describe-instance-refreshes.rst 以及 awscli/botocore/data/autoscaling/2011-01-01/service-2.json。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli