企业官网建设流程全解析

aws autoscaling start-instance-refresh 实战指南：用 AWS CLI 滚动更新 Auto Scaling 组的实例

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

导读

aws autoscaling start-instance-refresh是 AWS CLI 中启动 Amazon EC2 Auto Scaling 组**实例刷新（Instance Refresh）**的核心命令。当你更换了 AMI、修改了用户数据脚本或更新了启动模板后，无需手动逐台替换实例，只需一条命令即可让 Auto Scaling 服务按照滚动（Rolling）策略分批替换组内实例，并在刷新过程中通过健康检查与最小健康比例等偏好设置保障业务可用性。阅读本文后，你将掌握该命令的两种调用方式（命令行参数与 JSON 文件）、preferences全部核心参数的取值与默认行为，以及结合describe-instance-refreshes、rollback-instance-refresh、cancel-instance-refresh进行状态跟踪与故障处置的完整实战方案。

一、命令概览与适用场景

实例刷新功能用于在 Auto Scaling 组完成配置变更后（例如创建了指定新 AMI 或新用户数据脚本的启动模板），自动更新组内实例。从当前仓库的服务模型 service-2.json 可以看到，StartInstanceRefresh属于 autoscaling 服务 API 家族，与DescribeInstanceRefreshes、CancelInstanceRefresh、RollbackInstanceRefresh共同构成完整的实例刷新操作闭环。

调用成功时，请求返回一个唯一 ID（InstanceRefreshId），用于后续跟踪刷新进度——这正是官方示例输出中的关键字段。

与实例刷新相关的一组命令

仓库的 autoscaling 示例目录 中提供了配套命令的示例文档：

二、方式一：使用命令行参数启动实例刷新

官方示例中最直接的用法是纯命令行参数方式，通过--auto-scaling-group-name指定目标组，通过--preferences传入 JSON 格式的偏好配置：

aws autoscaling start-instance-refresh \ --auto-scaling-group-name my-asg \ --preferences '{"InstanceWarmup": 60, "MinHealthyPercentage": 50}'

其中：

• --auto-scaling-group-name：Auto Scaling 组的名称，必填参数。服务模型 StartInstanceRefreshType 中该字段位于required列表，是唯一必填项。
• --preferences：刷新偏好设置，本例设置了 60 秒实例预热（InstanceWarmup）与 50% 最小健康比例（MinHealthyPercentage）。

成功调用后返回如下输出，InstanceRefreshId是本次刷新的唯一标识，请妥善保存用于后续查询：

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

从源码看InstanceRefreshId的语义

服务模型中的 StartInstanceRefreshAnswer 明确该 ID 用于“跟踪实例刷新的进度（A unique ID for tracking the progress of the instance refresh）”。拿到该 ID 后，可以配合describe-instance-refreshes --instance-refresh-ids查询刷新的Pending、InProgress、Successful、Failed等状态。

三、方式二：使用 JSON 文件启动实例刷新（推荐）

当配置项较多时，官方示例推荐将 Auto Scaling 组、期望配置（DesiredConfiguration）与偏好（Preferences）统一写入 JSON 文件，通过--cli-input-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" } }

输出与方式一完全一致，同样返回InstanceRefreshId：

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

注意：官方示例中"ScaleInProtectedInstances": Ignore与"StandbyInstances": Terminate的值未加引号。在实际 JSON 文件中，这两处必须写成带引号的字符串形式（"Ignore"、"Terminate"），否则 JSON 解析会报错——上文的配置内容已做修正。

逐字段解析 JSON 配置

AutoScalingGroupName（必填）：目标 Auto Scaling 组名称，对应命令行--auto-scaling-group-name。

DesiredConfiguration：期望配置，即刷新完成后组应采用的配置。服务模型 DesiredConfiguration 规定：指定该结构时，必须在LaunchTemplate（启动模板）与MixedInstancesPolicy（混合实例策略，多实例类型 + 按需/Spot 组合）二者中指定其一。本例通过LaunchTemplateId+Version（$Default表示模板默认版本）指定新启动模板；刷新成功后，Auto Scaling 组的设置会自动更新为新的期望配置。

Preferences：刷新偏好，包含以下字段（默认值与语义以 RefreshPreferences 为准）：

ScaleInProtectedInstances与StandbyInstances的取值定义

服务模型中这两处字段均为受约束的字符串枚举：ScaleInProtectedInstances的合法值为Refresh/Ignore/Wait（见 service-2.json），StandbyInstances的合法值为Terminate/Ignore/Wait（见 service-2.json）。传入枚举之外的字符串会直接报参数校验错误。

四、刷新策略（Strategy）参数

除--preferences外，StartInstanceRefreshType还定义了可选的Strategy参数（见 service-2.json），合法值在 RefreshStrategy 中声明：

命令行调用示例：

aws autoscaling start-instance-refresh \ --auto-scaling-group-name my-asg \ --strategy Rolling \ --preferences '{"AutoRollback": true, "MinHealthyPercentage": 80}'

五、刷新失败与回滚的处理路径

何时自动回滚

从 AutoRollback 字段文档 可知，以下三种情况不支持自动回滚，即使开启AutoRollback也无济于事：

1. 实例刷新未指定DesiredConfiguration（期望配置）；
2. Auto Scaling 组的启动模板使用 AWS Systems Manager 参数（而非 AMI ID）作为ImageId；
3. Auto Scaling 组使用启动模板的$Latest或$Default版本。

手动处置命令

• 回滚：aws autoscaling rollback-instance-refresh --auto-scaling-group-name my-asg，会取消进行中的刷新并替换刷新期间被替换的实例，将组恢复到刷新前的配置（见 rollback-instance-refresh.rst）。注意：未指定期望配置的刷新不支持回滚。
• 仅取消：aws autoscaling cancel-instance-refresh --auto-scaling-group-name my-asg，只停止刷新，不回滚任何已完成的变更（见 cancel-instance-refresh.rst）。

并发与冲突

服务模型为StartInstanceRefresh声明了InstanceRefreshInProgressFault异常（错误码InstanceRefreshInProgress，见 service-2.json）：当组内已有进行中的刷新时再次调用，会返回该错误。因此在自动化脚本中建议先查询刷新状态再决定是否发起新刷新。

六、完整实战流程

将上述知识串联为一次完整的实例滚动更新流程：

# 1. 启动实例刷新（JSON 文件方式） aws autoscaling start-instance-refresh --cli-input-json file://config.json # 2. 使用返回的 InstanceRefreshId 轮询刷新状态 aws autoscaling describe-instance-refreshes \ --auto-scaling-group-name my-asg \ --instance-refresh-ids 08b91cf7-8fa6-48af-b6a6-d227f40f1b9b # 3a. 若刷新失败且未开启自动回滚，手动回滚 aws autoscaling rollback-instance-refresh --auto-scaling-group-name my-asg # 3b. 若仅需终止刷新而保留已变更，则取消 aws autoscaling cancel-instance-refresh --auto-scaling-group-name my-asg

七、FAQ 与踩坑提示

• MinHealthyPercentage设得太小会怎样？该值表示刷新期间允许同时处于不健康/不可用状态的实例上限百分比。设为 50 意味着刷新过程中最多允许一半实例被替换，风险更高但速度更快；生产环境建议保持默认 90 或更高。
• InstanceWarmup与组级DefaultInstanceWarmup的关系？两者作用相同，仅当需要覆盖组级默认预热时间时才在preferences中指定InstanceWarmup，否则自动回退到组级配置。
• JSON 文件中的字符串枚举必须加引号，Ignore、Terminate、Wait、Refresh等值要写成"Ignore"形式，这是使用官方示例时最容易踩的坑。
• 输出中的InstanceRefreshId一定要记录，它是后续查询、追踪本次刷新进度的唯一凭据。

八、进一步探索

• 完整示例文档：start-instance-refresh.rst
• 服务模型定义（输入输出结构与错误码）：service-2.json
• 配套命令示例：describe-instance-refreshes.rst、rollback-instance-refresh.rst、cancel-instance-refresh.rst
• 其他 Auto Scaling 操作示例：awscli/examples/autoscaling/

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