# aws autoscaling start-instance-refresh

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws autoscaling start-instance-refresh --auto-scaling-group-name my-asg replaces the group's instances in batches so they pick up a new launch template version, AMI or user data. Set MinHealthyPercentage and InstanceWarmup in --preferences to control how many instances are replaced at once and how long each must stay healthy before the next batch.

## What the command does

An instance refresh is EC2 Auto Scaling's built-in rolling deployment. It terminates and launches instances in batches, waiting for new ones to pass health checks and finish warming up before continuing, so the group never drops below the healthy percentage you set. It returns an `InstanceRefreshId` and runs in the background.

## Syntax

```
aws autoscaling start-instance-refresh --auto-scaling-group-name <asg> \
  [--strategy Rolling] \
  [--desired-configuration '{"LaunchTemplate":{"LaunchTemplateName":"<lt>","Version":"<v>"}}'] \
  [--preferences '{"MinHealthyPercentage":90,"InstanceWarmup":300,"SkipMatching":true}']
```

## Worked examples

**Roll out a new launch template version**, keeping 90% healthy, and skip instances already on it:

```
aws autoscaling start-instance-refresh --auto-scaling-group-name web-prod \
  --desired-configuration '{"LaunchTemplate":{"LaunchTemplateName":"web-prod","Version":"18"}}' \
  --preferences '{"MinHealthyPercentage":90,"InstanceWarmup":300,"SkipMatching":true}'
```

**Follow progress:**

```
aws autoscaling describe-instance-refreshes --auto-scaling-group-name web-prod --max-items 1 \
  --query "InstanceRefreshes[0].[InstanceRefreshId,Status,PercentageComplete,InstancesToUpdate,StatusReason]" \
  --output text
```

**Canary-style with checkpoints**: replace 10%, pause 10 minutes, then 50%, then the rest:

```
aws autoscaling start-instance-refresh --auto-scaling-group-name web-prod \
  --preferences '{"MinHealthyPercentage":90,"InstanceWarmup":300,"CheckpointPercentages":[10,50,100],"CheckpointDelay":600}'
```

**Roll back automatically** if a CloudWatch alarm fires during the refresh (needs a desired configuration):

```
aws autoscaling start-instance-refresh --auto-scaling-group-name web-prod \
  --desired-configuration '{"LaunchTemplate":{"LaunchTemplateName":"web-prod","Version":"18"}}' \
  --preferences '{"AutoRollback":true,"AlarmSpecification":{"Alarms":["web-prod-5xx-high"]},"InstanceWarmup":300}'
```

**Stop or undo** a refresh in progress:

```
aws autoscaling cancel-instance-refresh --auto-scaling-group-name web-prod
aws autoscaling rollback-instance-refresh --auto-scaling-group-name web-prod
```

## Choosing the pace

With a healthy percentage of 90 on a ten-instance group, one instance is replaced at a time; on a group of three, the refresh still has to replace at least one, which temporarily drops you to two. Small groups benefit from `MaxHealthyPercentage` above 100 so replacements launch before old instances terminate.

## Preferences that matter

| Preference | Effect |
|---|---|
| `MinHealthyPercentage` | Share of capacity that must stay healthy. Default 90. Lower is faster and riskier. |
| `MaxHealthyPercentage` | Allows launching replacements before terminating, up to this share above desired capacity. |
| `InstanceWarmup` | Seconds after an instance is healthy before it counts; set to your real boot-to-ready time. |
| `SkipMatching` | Leave instances that already match the desired configuration alone. |
| `CheckpointPercentages` / `CheckpointDelay` | Pause at these points so you can watch metrics. |
| `AutoRollback` + `AlarmSpecification` | Revert to the previous configuration on failure or alarm. |

## Gotchas

- **Only one refresh at a time** per group; a second start fails until the first finishes or is cancelled.
- **Health checks decide success.** With EC2 health checks only, a broken application can still "pass". Use ELB health checks on groups behind a load balancer.
- **Scale-in protected and standby instances** can block the refresh; the preferences `ScaleInProtectedInstances` and `StandbyInstances` control whether they are replaced, ignored or cause a wait.
- **Capacity issues stall it.** If new instances cannot launch, the refresh waits and eventually fails; check scaling activities for the launch error.
- **Cancel is not rollback.** Cancelling leaves a mix of old and new instances; rollback replaces the new ones with the previous configuration.

## Questions

### How do I roll out a new AMI to an Auto Scaling group?

Create a new launch template version with the AMI, then start an instance refresh with a desired configuration pointing to that version (or update the group to use it first).

### How do I check instance refresh progress?

Run aws autoscaling describe-instance-refreshes --auto-scaling-group-name <asg> and read Status, PercentageComplete and InstancesToUpdate.

### What happens if the new instances are unhealthy?

The refresh stops making progress and eventually fails. With AutoRollback enabled, Auto Scaling replaces the new instances with the previous configuration.

## When this happens away from your desk

A rolling replacement that stalls half-way often surfaces as a capacity alarm. CloudConsole is built to show those alarms and the group behind them on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [aws autoscaling start-instance-refresh (AWS CLI Command Reference)](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/start-instance-refresh.html)
- [Use an instance refresh to update instances in an Auto Scaling group (User Guide)](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-instance-refresh.html)

## Related

- [aws autoscaling update-auto-scaling-group](https://cloudconsole.dev/cli/autoscaling-update-auto-scaling-group)
- [aws autoscaling set-desired-capacity](https://cloudconsole.dev/cli/autoscaling-set-desired-capacity)
- [aws elbv2 describe-target-health](https://cloudconsole.dev/cli/elbv2-describe-target-health)
- [CloudWatch alarm for Auto Scaling GroupInServiceCapacity](https://cloudconsole.dev/alarms/auto-scaling-groupinservicecapacity)
- [ALB target health check failed (unhealthy targets)](https://cloudconsole.dev/errors/alb-targets-unhealthy)

---

Source: https://cloudconsole.dev/cli/autoscaling-start-instance-refresh

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
