# Use an instance refresh to update instances in an Auto Scaling group
You can use an instance refresh to update the instances in your Auto Scaling group. This feature can be useful when a configuration change requires you to replace instances or their root volumes, especially if your Auto Scaling group contains a large number of instances.
Some situations where an instance refresh can help include:
+ Deploying a new Amazon Machine Image (AMI) or user data script across your Auto Scaling group. You can create a new launch template with the changes and then use an instance refresh to roll out the updates immediately.
+ Migrating your instances to new instance types to take advantage of the latest improvements and optimizations.
+ Switching your Auto Scaling groups from using a launch configuration to using a launch template. You can copy your launch configurations to launch templates and then use an instance refresh to update your instances to the new templates. For more information about migrating to launch templates, see [Migrate your Auto Scaling groups to launch templates](migrate-to-launch-templates.md).
+ Applying security patches or software updates while preserving long-running instance state and avoiding capacity constraints with specialized instance types like GPU or Mac instances.
**Topics**
+ [How an instance refresh works](instance-refresh-overview.md)
+ [Understand the default values](understand-instance-refresh-default-values.md)
+ [Start an instance refresh](start-instance-refresh.md)
+ [Monitor an instance refresh](check-status-instance-refresh.md)
+ [Replace root volumes](replace-root-volume.md)
+ [Cancel an instance refresh](cancel-instance-refresh.md)
+ [Undo changes with a rollback](instance-refresh-rollback.md)
+ [Use skip matching](asg-instance-refresh-skip-matching.md)
+ [Add checkpoints](asg-adding-checkpoints-instance-refresh.md)
# How an instance refresh works in an Auto Scaling group
This topic describes how an instance refresh works and introduces the key concepts you need to understand to use it effectively.
**Topics**
+ [How it works](#instance-refresh-how-it-works)
+ [Core concepts](#instance-refresh-core-concepts)
+ [Health check grace period](#instance-refresh-health-check-grace-period)
+ [Instance type compatibility](#instance-type-compatibility)
+ [Limitations](#instance-refresh-limitations)
## How it works
To refresh instances in an Auto Scaling group, you can define a new configuration that contains the latest version of your application and any other updates you want to make.
Instance refresh supports two strategies for updating instances:
+ **Rolling strategy (default)** — Terminates instances and launches new ones in batches according to your preferences. This ensures that your Auto Scaling group maintains its desired capacity and availability throughout the update process.
+ **Replace root volume strategy** — Updates instances by replacing only the root volume without terminating the instance. This preserves instance network interfaces, non-root EBS volumes, and instance store data.
Requirements for replace root volume strategy:
+ Your Auto Scaling group must use a mixed instances policy
+ All overrides in the mixed instances policy must specify an `ImageId`
+ AMIs must contain only a single root volume
+ All instances must match the group's launch template configuration
+ You must start the instance refresh with a desired configuration having a mixed instances policy containing `ImageId` overrides.
When skip matching is enabled, Auto Scaling compares each instance's current AMI ID against the AMI IDs in your desired configuration. It only replaces instances where the AMI IDs don't match, allowing you to skip instances that are already updated.
### Perform an instance refresh
Start an instance refresh to replace existing instances with new ones based on that configuration.
1. Create a new launch template or update the existing template with the desired configuration changes, such as a new Amazon Machine Image (AMI). For more information, see [Create a launch template for an Auto Scaling group](create-launch-template.md).
1. Start the instance refresh using the Amazon EC2 Auto Scaling console, AWS CLI, or SDK:
+ Specify the new launch template or launch template version you created. This will be used to launch new instances.
+ Set the preferred minimum and maximum healthy percentage. This controls how many instances are replaced simultaneously and whether new instances are launched before terminating old ones.
+ Configure any optional settings, such as:
+ **Checkpoints** – Pause the instance refresh after a certain percentage of replacements to verify progress.
+ **Bake time** – Pause at the end of instance refresh to validate instance health before the instance refresh is considered complete.
+ **Skip matching** – Compare old instances to the new configuration and only replace those that don't match. When you start an instance refresh from the console, skip matching is on by default.
+ **Multiple instance types** – Apply a new or updated [mixed instances policy](ec2-auto-scaling-mixed-instances-groups.md) as part of the desired configuration.
When the instance refresh has started, Amazon EC2 Auto Scaling will:
+ Replace instances in batches based on the minimum and maximum healthy percentages.
+ Launch the new instances first before terminating the old ones if the minimum healthy percentage is set to 100 percent. This ensures that your desired capacity is maintained at all times.
+ Check instances for health status and give them time to warm up before more instances are replaced.
+ Terminate and replace instances that are found to be unhealthy.
+ Automatically update the Auto Scaling group settings with the new configuration changes after the instance refresh succeeds.
+ Replace `InService` instances before instances that are in a warm pool.
The following flow diagram illustrates the launch before terminate behavior when you set the minimum healthy percentage to 100 percent.
![\[A diagram showing how an instance refresh works when the minimum healthy percentage is set to 100 percent.\]](http://docs.aws.amazon.com/autoscaling/ec2/userguide/images/instance-refresh-high-level-flowchart-diagram.png)
**Note**
The minimum and maximum healthy percentages for an instance refresh only need to be specified if you have not set an instance maintenance policy, or if you need to override the existing policy. For more information, see [Instance maintenance policies](ec2-auto-scaling-instance-maintenance-policy.md).
Similarly, you only need to specify the instance warmup period for an instance refresh if you have not enabled the default warmup, or if you need to override the default. For more information, see [Set the default instance warmup for an Auto Scaling group](ec2-auto-scaling-default-instance-warmup.md).
## Core concepts
Before you get started, familiarize yourself with the following instance refresh core concepts:
**Minimum healthy percentage**
The *minimum healthy percentage* is the percentage of the desired capacity to keep in service, healthy, and ready to use during an instance refresh so that the refresh can continue. For example, if the minimum healthy percentage is 90 percent and the maximum healthy percentage is 100 percent, then 10 percent of capacity will be replaced at a time. If the new instances don't pass their health checks, Amazon EC2 Auto Scaling terminates and replaces them. If the instance refresh can't launch any healthy instances, it will eventually fail, leaving the other 90 percent of the group untouched. If the new instances stay healthy and finish their warmup period, Amazon EC2 Auto Scaling can continue to replace other instances.
An instance refresh can replace instances one at a time, several at a time, or all at once. To replace one instance at a time, set both the minimum and maximum healthy percentage to 100 percent. This changes the behavior of an instance refresh to launch before terminating, which prevents the group's capacity from falling below 100 percent of its desired capacity. To replace all instances at once, set a minimum healthy percentage of 0 percent.
**Maximum healthy percentage**
The *maximum healthy percentage* is the percentage of the desired capacity that your Auto Scaling group can increase to when replacing instances. The difference between the minimum and maximum cannot be greater than 100. A larger range increases the number of instances that can be replaced at the same time.
**Instance warmup**
The *instance warmup* is the time period from when a new instance's state changes to `InService` to when it is considered to have finished initializing. During an instance refresh, if the instances pass their health checks, Amazon EC2 Auto Scaling does not immediately move on to replacing the next instance after determining that a newly launched instance is healthy. It waits for the warmup period before it moves on to replacing the next instance. This can be helpful when your application still needs some initialization time before it responds to requests.
The instance warmup works the same way as the default instance warmup. Therefore, the same scaling considerations apply. For more information, see [Set the default instance warmup for an Auto Scaling group](ec2-auto-scaling-default-instance-warmup.md).
**Desired configuration**
The *desired configuration* is the new configuration that you want Amazon EC2 Auto Scaling to deploy across your Auto Scaling group. For example, you can specify a new launch template and new instance types for your instances. During an instance refresh, Amazon EC2 Auto Scaling updates the Auto Scaling group to the desired configuration. If a scale-out event occurs during an instance refresh, Amazon EC2 Auto Scaling launches new instances with the desired configuration instead of the group's current settings. After the instance refresh succeeds, Amazon EC2 Auto Scaling updates the Auto Scaling group settings to reflect the new desired configuration that you specified as part of the instance refresh.
**Skip matching**
Skip matching tells Amazon EC2 Auto Scaling to ignore instances that already have your latest updates. This way, you don't replace more instances than you need to. This is helpful when you want to make sure your Auto Scaling group uses a particular version of your launch template and only replaces those instances that use a different version.
**Checkpoints**
A *checkpoint* is a point in time where the instance refresh pauses for a specified amount of time. An instance refresh can contain multiple checkpoints. Amazon EC2 Auto Scaling emits events for each checkpoint. Therefore, you can add an EventBridge rule to send the events to a target, such as Amazon SNS, to be notified when a checkpoint is reached. After a checkpoint is reached, you have the opportunity to verify your deployment. If any problems are identified, you can cancel the instance refresh or roll it back. The ability to deploy updates in phases is a key benefit of checkpoints. If you don't use checkpoints, rolling replacements are performed continuously.
To learn more about all of the default settings you can configure when starting an instance refresh, see [Understand the default values for an instance refresh](understand-instance-refresh-default-values.md).
## Health check grace period
Amazon EC2 Auto Scaling determines whether an instance is healthy based on the status of the health checks that your Auto Scaling group uses. For more information, see [Health checks for instances in an Auto Scaling group](ec2-auto-scaling-health-checks.md).
To make sure that these health checks start as soon as possible, don't set the group's health check grace period too high, but high enough for your Elastic Load Balancing health checks to determine whether a target is available to handle requests. For more information, see [Set the health check grace period for an Auto Scaling group](health-check-grace-period.md).
## Instance type compatibility
Before you change your instance type, it's a good idea to verify that it works with your launch template. This confirms compatibility with the AMI that you specified. For example, let's say you launched your original instances from a paravirtual (PV) AMI, but you want to change to a current generation instance type that is only supported by a hardware virtual machine (HVM) AMI. In this case, you must use an HVM AMI in your launch template.
To confirm compatibility of the instance type without launching instances, use the [run-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/run-instances.html) command with the `--dry-run` option, as shown in the following example.
```
aws ec2 run-instances --launch-template LaunchTemplateName=my-template,Version='1' --dry-run
```
For information about how compatibility is determined, see [Compatibility for changing the instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/resize-limitations.html) in the *Amazon EC2 User Guide*.
## Limitations
+ **Total duration** — The maximum amount of time that an instance refresh can continue to actively replace instances is 14 days.
+ **Difference in behavior specific to weighted groups** — If a mixed instances group is configured with an instance weight that is larger than or equal to the group's desired capacity, Amazon EC2 Auto Scaling might replace all `InService` instances at once. To avoid this situation, follow the recommendation in the [Configure an Auto Scaling group to use instance weights](ec2-auto-scaling-mixed-instances-groups-instance-weighting.md) topic. Specify a desired capacity that is larger than your largest weight when you use weights with your Auto Scaling group.
+ **One-hour timeout** — When an instance refresh is unable to continue making replacements because it is waiting to replace instances on standby or protected from scale in, or the new instances do not pass their health checks, Amazon EC2 Auto Scaling keeps retrying for an hour. It also provides a status message to help you resolve the issue. If the problem persists after an hour, the operation fails. The intention is to give it time to recover if there is a temporary issue.
+ **Deploying code via user data** — Skip matching doesn't check for code changes that are deployed from a user data script. If you use user data to pull new code and install these updates on new instances, we recommend that you turn off skip matching to make sure that all instances receive your latest code, even without a launch template version update.
+ **Update restriction** — If you attempt to update an Auto Scaling group's launch template, launch configuration, or mixed instances policy while an instance refresh with a desired configuration is active, the request will fail with the following validation error: `An active instance refresh with a desired configuration exists. All configuration options derived from the desired configuration are not available for update while the instance refresh is active.`
+ **Attribute-based instance selection** — If your Auto Scaling group uses attribute-based instance selection (specifying `InstanceRequirements` in a mixed instances policy), the following instance refresh parameters aren't supported:
+ **SkipMatching** - An instance refresh will fail if you start it with the `SkipMatching` parameter in an Auto Scaling group that has `InstanceRequirements` configured.
+ **DesiredConfiguration** - An instance refresh will fail if you start it with the `DesiredConfiguration` parameter in an Auto Scaling group that has `InstanceRequirements` configured.
If you need to perform an instance refresh on an Auto Scaling group with attribute-based instance selection, start the instance refresh without these parameters.
+ Root volume replacement doesn’t support Elastic Load Balancing.
# Understand the default values for an instance refresh
Before you start an instance refresh, you can customize various preferences that affect the instance refresh. Some preference defaults are different depending on whether you use the console or the command line (AWS CLI or AWS SDK).
The following table lists the default values for the instance refresh settings.
| Setting | AWS CLI or AWS SDK | Amazon EC2 Auto Scaling console |
| --- | --- | --- |
| CloudWatch alarm | Disabled (null) | Disabled |
| Auto rollback | Disabled (false) | Disabled |
| Bake time | Zero | Zero |
| Checkpoints | Disabled (false) | Disabled |
| Checkpoint delay | 1 hour (3600 seconds) | 1 hour |
| Instance warmup | The [default instance warmup](ec2-auto-scaling-default-instance-warmup.md), if defined, or the [health check grace period](health-check-grace-period.md) otherwise. | The [default instance warmup](ec2-auto-scaling-default-instance-warmup.md), if defined, or the [health check grace period](health-check-grace-period.md) otherwise. |
| Maximum healthy percentage | Varies based on your instance maintenance policy. If no instance maintenance policy, this defaults to 100 percent (null). | Varies based on your instance maintenance policy. If no instance maintenance policy, this defaults to 100 percent (null). |
| Minimum healthy percentage | Varies based on your instance maintenance policy. If no instance maintenance policy, this defaults to 90 percent. | Varies based on your instance maintenance policy. If no instance maintenance policy, this defaults to 90 percent. |
| Scale-in protected instances | Wait | Ignore |
| Skip matching | Disabled (false) | Enabled |
| Standby instances | Wait | Ignore |
A description of each setting follows:
**CloudWatch alarm (`AlarmSpecification`)**
The CloudWatch alarm specification. CloudWatch alarms can be used to identify any issues and fail the operation if an alarm goes into the `ALARM` state. For more information, see [Start an instance refresh with auto rollback](instance-refresh-rollback.md#instance-refresh-using-auto-rollback).
**Auto rollback (`AutoRollback`)**
Controls whether Amazon EC2 Auto Scaling rolls back the Auto Scaling group to its previous configuration if the instance refresh fails. For more information, see [Undo changes with a manual or auto rollback](instance-refresh-rollback.md).
**Bake time (`BakeTime`)**
The amount of time to wait at the end of an instance refresh before the instance refresh is considered complete.
**Checkpoints (`CheckpointPercentages`)**
Controls whether Amazon EC2 Auto Scaling replaces instances in phases. This is useful if you need to perform verifications on your instances before replacing all instances. For more information, see [Add checkpoints to an instance refresh](asg-adding-checkpoints-instance-refresh.md).
**Checkpoint delay (`CheckpointDelay`)**
The amount of time, in seconds, to wait after a checkpoint before continuing. For more information, see [Add checkpoints to an instance refresh](asg-adding-checkpoints-instance-refresh.md).
**Instance warmup (`InstanceWarmup`)**
A time period, in seconds, during which Amazon EC2 Auto Scaling waits until a new instance is considered to have finished initializing before moving on to replacing the next instance. If you have already correctly defined a default instance warmup for the Auto Scaling group, then you don't need to change the instance warmup (unless you want to override the default). For more information, see [Set the default instance warmup for an Auto Scaling group](ec2-auto-scaling-default-instance-warmup.md).
**Maximum healthy percentage (`MaxHealthyPercentage`)**
The percentage of the desired capacity of the Auto Scaling group that your group can increase to when replacing instances.
**Minimum healthy percentage (`MinHealthyPercentage`)**
The percentage of the desired capacity of the Auto Scaling group that must be in service, healthy, and ready to use before the operation can continue.
**Scale-in protected instances (`ScaleInProtectedInstances`)**
Controls what Amazon EC2 Auto Scaling does if instances that are protected from scale in are found. For more information about these instances, see [Use instance scale-in protection to control instance termination](ec2-auto-scaling-instance-protection.md).
Amazon EC2 Auto Scaling provides the following options:
+ **Replace** (`Refresh`) – Replaces instances that are protected from scale in.
+ **Ignore** (`Ignore`) – Ignores instances that are protected from scale in and continues to replace instances that are not protected.
+ **Wait** (`Wait`) – Waits one hour for you to remove scale-in protection. If you don't do so, the instance refresh fails.
**Skip matching (`SkipMatching`)**
Controls whether Amazon EC2 Auto Scaling skips replacing instances that match the desired configuration. If no desired configuration is specified, then it skips replacing instances that have the same launch template and instance types that the Auto Scaling group was using before the instance refresh started. For more information, see [Use an instance refresh with skip matching](asg-instance-refresh-skip-matching.md).
**Standby instances (`StandbyInstances`)**
Controls what Amazon EC2 Auto Scaling does if instances are found in `Standby` state. For more information about these instances, see [Temporarily remove instances from your Auto Scaling group](as-enter-exit-standby.md).
Amazon EC2 Auto Scaling provides the following options:
+ **Terminate** (`Terminate`) – Terminates instances that are in `Standby`.
+ **Ignore** (`Ignore`) – Ignores instances that are in `Standby` and continues to replace instances that are in the `InService` state.
+ **Wait** (`Wait`) – Waits one hour for you to return the instances to service. If you don't do so, the instance refresh fails.
# Start an instance refresh using the AWS Management Console or AWS CLI
**Important**
You can roll back an instance refresh that is in progress to undo any changes. For this to work, the Auto Scaling group must meet the prerequisites for using rollbacks before starting the instance refresh. For more information, see [Undo changes with a manual or auto rollback](instance-refresh-rollback.md).
The following procedures help you start an instance refresh using the AWS Management Console or AWS CLI.
## Start an instance refresh (console)
If this is your first time starting an instance refresh, using the console will help you understand the features and options available.
### Start an instance refresh in the console (basic procedure)
Use the following procedure if you have not previously defined a [mixed instances policy](ec2-auto-scaling-mixed-instances-groups.md) for your Auto Scaling group. If you have previously defined a mixed instances policy, see [Start an instance refresh in the console (mixed instances group)](#starting-an-instance-refresh-in-the-console-mig) to start an instance refresh.
**To start an instance refresh**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to your Auto Scaling group.
A split pane opens up at the bottom of the **Auto Scaling groups** page.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Start instance refresh**.
1. For **Availability settings**, do the following:
1. For **Instance replacement method**:
+ If you *haven't* set an instance maintenance policy on the Auto Scaling group, the default setting for **Instance replacement method** is **Terminate and launch**. This is the legacy default behavior for an instance refresh.
+ If you set an instance maintenance policy on the Auto Scaling group, it provides default values for **Instance replacement method**. To override the instance maintenance policy, choose **Override**. Overriding only applies to the current instance refresh. The next time you start an instance refresh, these values are reset to the instance maintenance policy defaults.
The following procedure explains how to update the instance replacement method.
1. Choose one of the following instance replacement methods:
+ **Launch before terminating**: A new instance must be provisioned first before an existing instance can be terminated. This is a good choice for applications that favor availability over cost savings.
+ **Terminate and launch**: New instances are provisioned at the same time your existing instances are terminated. This is a good choice for applications that favor cost savings over availability. It's also a good choice for applications that should not launch more capacity than is currently available.
+ **Custom behavior**: This option lets you set up a custom minimum and maximum range for the amount of capacity that you want available when replacing instances. This can help you achieve the right balance between cost and availability.
1. For **Set healthy percentage**, enter values for one or both of the following fields. The enable fields vary depending on the option you choose for **Instance replacement method**.
+ **Min**: Sets the minimum healthy percentage that's required to proceed with the instance refresh.
+ **Max**: Sets the maximum healthy percentage that's possible during the instance refresh.
1. Expand the **View estimated temporary capacity during replacements based on current group size** section to confirm how the values for **Min** and **Max** apply to your group. The exact values used depend on the desired capacity value, which will change if the group scales.
1. Expand the **Set fallback behavior for invalid replacement sizes** section, and then choose whether to **Violate max healthy percentage** in order to prioritize availability, or **Violate min healthy percentage**.
Keeping the default **Violate min healthy percentage** option is not recommended for very small groups. If there is only one instance in the Auto Scaling group, starting an instance refresh can result in an outage.
This step configures fallback behavior if you are using an Auto Scaling group that doesn't have an instance maintenance policy yet. This option isn't available and doesn't appear when your group has an instance maintenance policy. This option is also only available for the **Terminate and launch** replacement method. Other replacement methods will violate the maximum healthy percentage in order to prioritize availability.
1. For **Instance warmup**, enter the number of seconds from when a new instance's state changes to `InService` to when it finishes initializing. Amazon EC2 Auto Scaling waits this amount of time before moving on to replace the next instance.
While warming up, a newly launched instance is also not counted toward the aggregated instance metrics of the Auto Scaling group (such as `CPUUtilization`, `NetworkIn`, and `NetworkOut`). If you added scaling policies to the Auto Scaling group, the scaling activities run in parallel. If you set a long interval for the instance refresh warmup period, it takes more time for newly launched instances to show up in the metrics. Therefore, an adequate warmup period keeps Amazon EC2 Auto Scaling from scaling on stale metric data.
If you have already correctly defined a default instance warmup for the Auto Scaling group, then you don't need to change the instance warmup. However, if you want to override the default, you can set a value for this option. For more information about setting the default instance warmup, see [Set the default instance warmup for an Auto Scaling group](ec2-auto-scaling-default-instance-warmup.md).
1. For **Refresh settings**, do the following:
1. (Optional) For **Checkpoints**, choose **Enable checkpoints** to replace instances using an incremental or phased approach to an instance refresh. This provides additional time for verification between sets of replacements. If you choose not to enable checkpoints, the instances are replaced in one nearly continuous operation.
If you enable checkpoints, see [Enable checkpoints (console)](enable-checkpoints-console-cli.md#enable-checkpoints-console) for additional steps.
1. (Optional) For **Bake time**, specify the amount of time to wait at the end of the instance refresh before the instance refresh is considered complete.
1. Enable or turn off **Skip matching**:
+ To skip replacing instances that already match your launch template, keep the **Enable skip matching** check box selected.
+ If you turn off skip matching by clearing this check box, all instances can be replaced.
When you enable skip matching, you can set a new launch template or a new version of the launch template instead of using the existing one. Do this in the **Desired configuration** section of the **Start instance refresh** page.
**Note**
To use the skip matching feature to update an Auto Scaling group that currently uses a launch configuration, you must select a launch template in **Desired configuration**. Skip matching with a launch configuration is not supported.
1. For **Standby instances**, choose **Ignore**, **Terminate**, or **Wait**. This determines what happens if instances are found in `Standby` state. For more information, see [Temporarily remove instances from your Auto Scaling group](as-enter-exit-standby.md).
If you choose **Wait**, you must take additional steps to return these instances to service. If you don't, the instance refresh replaces all `InService` instances and waits for one hour. Then, if any `Standby` instances remain, the instance refresh fails. To prevent this situation, choose to **Ignore** or **Terminate** these instances instead.
1. For **Scale-in protected instances**, choose **Ignore**, **Replace**, or **Wait**. This determines what happens if scale-in protected instances are found. For more information, see [Use instance scale-in protection to control instance termination](ec2-auto-scaling-instance-protection.md).
If you choose **Wait**, you must take additional steps to remove scale-in protection from these instances. If you don't, the instance refresh replaces all unprotected instances and waits one hour. Then, if any scale-in protected instances remain, the instance refresh fails. To prevent this situation, choose to **Ignore** or **Replace** these instances instead.
1. (Optional) For **CloudWatch alarm**, choose **Enable CloudWatch alarms**, and then choose one or more alarms. CloudWatch alarms can be used to identify any issues and fail the operation if an alarm goes into the `ALARM` state. For more information, see [Start an instance refresh with auto rollback](instance-refresh-rollback.md#instance-refresh-using-auto-rollback).
1. (Optional) Expand the **Desired configuration** section to specify updates that you want to make to your Auto Scaling group.
For this step, you can choose to use JSON or YAML syntax to edit parameter values instead of making selections in the console interface. To do so, choose **Use code editor** instead of **Use console interface**. The following procedure explains how to make selections using the console interface.
1. For **Update launch template**:
+ If you *haven't* created a new launch template or a new launch template version for your Auto Scaling group, don't select this check box.
+ If you created a new launch template or a new launch template version, select this check box. When you select this option, Amazon EC2 Auto Scaling shows you the current launch template and current launch template version. It also lists any other available versions. Choose the launch template and then choose the version.
After you choose a version, you can see the version information. This is the version of the launch template that will be used when replacing instances as part of an instance refresh. If the instance refresh succeeds, this version of the launch template will also be used whenever new instances launch, such as when the group scales.
1. For **Choose a set of instance types and purchase options to override the instance type in the launch template**:
+ Don't select this check box if you want to use the instance type and purchase option you specified in your launch template.
+ Select this check box if you want to override the instance type in the launch template or run Spot Instances. You can either manually add each instance type or choose a primary instance type and recommendation option that retrieves any additional matching instance types for you. If you plan to launch Spot Instances, we recommend adding a few different instance types. This way, Amazon EC2 Auto Scaling can launch another instance type if there is insufficient instance capacity in your chosen Availability Zones. For more information, see [Auto Scaling groups with multiple instance types and purchase options](ec2-auto-scaling-mixed-instances-groups.md).
**Warning**
Don't use Spot Instances with applications that can't handle a Spot Instance interruption. Interruptions can occur if the Amazon EC2 Spot service needs to reclaim capacity.
If you select this check box, make sure that the launch template doesn't already request Spot Instances. You can't use a launch template that requests Spot Instances to create an Auto Scaling group that uses multiple instance types and launches Spot and On-Demand Instances.
**Note**
To configure these options on an Auto Scaling group that currently uses a launch configuration, you must select a launch template in **Update launch template**. Overriding the instance type in your launch configuration is not supported.
1. (Optional) For **Rollback settings**, choose **Enable auto rollback** to automatically roll back the instance refresh if it fails.
This setting can only be enabled when the Auto Scaling group meets the prerequisites for using rollbacks.
For more information, see [Undo changes with a manual or auto rollback](instance-refresh-rollback.md).
1. Review all of your selections to confirm that everything is set up correctly.
At this point, it's a good idea to verify that the differences between the current and proposed changes won't affect your application in unexpected or unwanted ways. To confirm that your instance type is compatible with your launch template, see [Instance type compatibility](instance-refresh-overview.md#instance-type-compatibility).
1. When you are satisfied with your instance refresh selections, choose **Start instance refresh**.
### Start an instance refresh in the console (mixed instances group)
Use the following procedure if you have created an Auto Scaling group with a [mixed instances policy](ec2-auto-scaling-mixed-instances-groups.md). If you haven't defined a mixed instances policy for your group yet, see [Start an instance refresh in the console (basic procedure)](#starting-an-instance-refresh-in-the-console) to start an instance refresh.
**To start an instance refresh**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to your Auto Scaling group.
A split pane opens up at the bottom of the **Auto Scaling groups** page.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Start instance refresh**.
1. For **Availability settings**, do the following:
1. For **Instance replacement method**:
+ If you *haven't* set an instance maintenance policy on the Auto Scaling group, the default setting for **Instance replacement method** is **Terminate and launch**. This is the legacy default behavior for an instance refresh.
+ If you set an instance maintenance policy on the Auto Scaling group, it provides default values for **Instance replacement method**. To override the instance maintenance policy, choose **Override**. Overriding only applies to the current instance refresh. The next time you start an instance refresh, these values are reset to the instance maintenance policy defaults.
The following procedure explains how to update the instance replacement method.
1. Choose one of the following instance replacement methods:
+ **Launch before terminating**: A new instance must be provisioned first before an existing instance can be terminated. This is a good choice for applications that favor availability over cost savings.
+ **Terminate and launch**: New instances are provisioned at the same time your existing instances are terminated. This is a good choice for applications that favor cost savings over availability. It's also a good choice for applications that should not launch more capacity than is currently available.
+ **Custom behavior**: This option lets you set up a custom minimum and maximum range for the amount of capacity that you want available when replacing instances. This can help you achieve the right balance between cost and availability.
1. For **Set healthy percentage**, enter values for one or both of the following fields. The enable fields vary depending on the option you choose for **Instance replacement method**.
+ **Min**: Sets the minimum healthy percentage that's required to proceed with the instance refresh.
+ **Max**: Sets the maximum healthy percentage that's possible during the instance refresh.
1. Expand the **View estimated temporary capacity during replacements based on current group size** section to confirm how the values for **Min** and **Max** apply to your group. The exact values used depend on the desired capacity value, which will change if the group scales.
1. Expand the **Set fallback behavior for invalid replacement sizes** section, and then choose whether to **Violate max healthy percentage** in order to prioritize availability, or **Violate min healthy percentage**.
Keeping the default **Violate min healthy percentage** option is not recommended for very small groups. If there is only one instance in the Auto Scaling group, starting an instance refresh can result in an outage.
This step configures fallback behavior if you are using an Auto Scaling group that doesn't have an instance maintenance policy yet. This option isn't available and doesn't appear when your group has an instance maintenance policy. This option is also only available for the **Terminate and launch** replacement method. Other replacement methods will violate the maximum healthy percentage in order to prioritize availability.
1. For **Instance warmup**, enter the number of seconds from when a new instance's state changes to `InService` to when it finishes initializing. Amazon EC2 Auto Scaling waits this amount of time before moving on to replace the next instance.
While warming up, a newly launched instance is also not counted toward the aggregated instance metrics of the Auto Scaling group (such as `CPUUtilization`, `NetworkIn`, and `NetworkOut`). If you added scaling policies to the Auto Scaling group, the scaling activities run in parallel. If you set a long interval for the instance refresh warmup period, it takes more time for newly launched instances to show up in the metrics. Therefore, an adequate warmup period keeps Amazon EC2 Auto Scaling from scaling on stale metric data.
If you have already correctly defined a default instance warmup for the Auto Scaling group, then you don't need to change the instance warmup. However, if you want to override the default, you can set a value for this option. For more information about setting the default instance warmup, see [Set the default instance warmup for an Auto Scaling group](ec2-auto-scaling-default-instance-warmup.md).
1. For **Refresh settings**, do the following:
1. (Optional) For **Checkpoints**, choose **Enable checkpoints** to replace instances using an incremental or phased approach to an instance refresh. This provides additional time for verification between sets of replacements. If you choose not to enable checkpoints, the instances are replaced in one nearly continuous operation.
If you enable checkpoints, see [Enable checkpoints (console)](enable-checkpoints-console-cli.md#enable-checkpoints-console) for additional steps.
1. Enable or turn off **Skip matching**:
+ To skip replacing instances that already match your launch template and any instance type overrides, keep the **Enable skip matching** check box selected.
+ If you choose to turn off skip matching by clearing this check box, all instances can be replaced.
When you enable skip matching, you can set a new launch template or a new version of the launch template instead of using the existing one. Do this in the **Desired configuration** section of the **Start instance refresh** page. You can also update your instance type overrides in **Desired configuration**.
1. For **Standby instances**, choose **Ignore**, **Terminate**, or **Wait**. This determines what happens if instances are found in `Standby` state. For more information, see [Temporarily remove instances from your Auto Scaling group](as-enter-exit-standby.md).
If you choose **Wait**, you must take additional steps to return these instances to service. If you don't, the instance refresh replaces all `InService` instances and waits one hour. Then, if any `Standby` instances remain, the instance refresh fails. To prevent this situation, choose to **Ignore** or **Terminate** these instances instead.
1. For **Scale-in protected instances**, choose **Ignore**, **Replace**, or **Wait**. This determines what happens if scale-in protected instances are found. For more information, see [Use instance scale-in protection to control instance termination](ec2-auto-scaling-instance-protection.md).
If you choose **Wait**, you must take additional steps to remove scale-in protection from these instances. If you don't, the instance refresh replaces all unprotected instances and waits one hour. Then, if any scale-in protected instances remain, the instance refresh fails. To prevent this situation, choose to **Ignore** or **Replace** these instances instead.
1. (Optional) For **CloudWatch alarm**, choose **Enable CloudWatch alarms**, and then choose one or more alarms. CloudWatch alarms can be used to identify any issues and fail the operation if an alarm goes into the `ALARM` state. For more information, see [Start an instance refresh with auto rollback](instance-refresh-rollback.md#instance-refresh-using-auto-rollback).
1. In the **Desired configuration** section, do the following.
For this step, you can choose to use JSON or YAML syntax to edit parameter values instead of making selections in the console interface. To do so, choose **Use code editor** instead of **Use console interface**. The following procedure explains how to make selections using the console interface.
1. For **Update launch template**:
+ If you *haven't* created a new launch template or a new launch template version for your Auto Scaling group, don't select this check box.
+ If you created a new launch template or a new launch template version, select this check box. When you select this option, Amazon EC2 Auto Scaling shows you the current launch template and current launch template version. It also lists any other available versions. Choose the launch template and then choose the version.
After you choose a version, you can see the version information. This is the version of the launch template that will be used when replacing instances as part of an instance refresh. If the instance refresh succeeds, this version of the launch template will also be used whenever new instances launch, such as when the group scales.
1. For **Use these settings to override the instance type and purchase option defined in the launch template**:
By default, this check box is selected. Amazon EC2 Auto Scaling populates each parameter with the value that's currently set in the *mixed instances policy* for the Auto Scaling group. Only update values for the parameters that you want to change. For guidance on these settings, see [Auto Scaling groups with multiple instance types and purchase options](ec2-auto-scaling-mixed-instances-groups.md).
**Warning**
We recommend that you do not clear this check box. Only clear it if you want to stop using a mixed instances policy. After the instance refresh succeeds, Amazon EC2 Auto Scaling updates your group to match the **Desired configuration**. If it no longer includes a mixed instances policy, Amazon EC2 Auto Scaling gradually terminates any Spot Instances that are currently running and replaces them with On-Demand Instances. Or, if your launch template requests Spot Instances, then Amazon EC2 Auto Scaling gradually terminates any On-Demand Instances that are currently running and replaces them with Spot Instances.
1. (Optional) For **Rollback settings**, choose **Enable auto rollback** to automatically roll back the instance refresh if it fails for any reason.
This setting can only be enabled when the Auto Scaling group meets the prerequisites for using rollbacks.
For more information, see [Undo changes with a manual or auto rollback](instance-refresh-rollback.md).
1. Review all of your selections to confirm that everything is set up correctly.
At this point, it's a good idea to verify that the differences between the current and proposed changes won't affect your application in unexpected or unwanted ways. To confirm that your instance type is compatible with your launch template, see [Instance type compatibility](instance-refresh-overview.md#instance-type-compatibility).
When you are satisfied with your instance refresh selections, choose **Start instance refresh**.
## Start an instance refresh (AWS CLI)
**To start an instance refresh**
Use the following [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command to start an instance refresh from the AWS CLI. You can specify any preferences that you want to change in a JSON configuration file. When you reference the configuration file, provide the file path and name as shown in the following example.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`:
```
{
"AutoScalingGroupName": "my-asg",
"Preferences": {
"InstanceWarmup": 60,
"MinHealthyPercentage": 50,
"AutoRollback": true,
"ScaleInProtectedInstances": Ignore,
"StandbyInstances": Terminate
}
}
```
If preferences are not provided, default values are used. For more information, see [Understand the default values for an instance refresh](understand-instance-refresh-default-values.md).
Example output:
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
# Monitor an instance refresh using the AWS Management Console or AWS CLI
You can monitor an in progress instance refresh or look up the status of past instance refreshes from the last six weeks using the AWS Management Console or AWS CLI.
## Monitor and check the status of an instance refresh
To monitor and check the status of an instance refresh, use one of the following methods:
------
#### [ Console ]
**Tip**
In this procedure, the named columns should already be displayed. To display hidden columns or change the number of rows shown, choose the gear icon on the top right corner of the section to open the preferences modal. Update the settings as needed and choose **Confirm**.
**To monitor and check the status of an instance refresh (console)**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to the Auto Scaling group.
A split pane opens up at the bottom of the page.
1. On the **Instance refresh** tab, under **Instance refresh history**, you can determine the status of your request by looking at the **Status** column. The operation goes into `Pending` status while it's initializing. The status should then quickly change to `InProgress`. When all instances are updated, the status changes to `Successful`.
1. You can further monitor the success or failure of in progress activities by viewing the group's scaling activities. On the **Activity** tab, under **Activity history**, when the instance refresh starts, you see entries when instances are terminated and another set of entries when instances are launched. If you have numerous scaling activities, you can see more of them by choosing the **>** icon at the top of the activity history. For information about troubleshooting issues that might cause activities to fail, see [Troubleshoot issues in Amazon EC2 Auto Scaling](CHAP_Troubleshooting.md).
1. (Optional) On the **Instance management** tab, under **Instances**, you can review the progress of specific instances as needed.
------
#### [ AWS CLI ]
**To monitor and check the status of an instance refresh (AWS CLI)**
Use the following [describe-instance-refreshes](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/describe-instance-refreshes.html) command.
```
aws autoscaling describe-instance-refreshes --auto-scaling-group-name my-asg
```
The following is example output.
Instance refreshes are ordered by start time. Instance refreshes still in progress are described first.
```
{
"InstanceRefreshes":[
{
"InstanceRefreshId":"08b91cf7-8fa6-48af-b6a6-d227f40f1b9b",
"AutoScalingGroupName":"my-asg",
"Status":"InProgress",
"StatusReason":"Waiting for instances to warm up before continuing. For example: i-0645704820a8e83ff is warming up.",
"StartTime":"2023-11-24T16:46:52+00:00",
"PercentageComplete":50,
"InstancesToUpdate":0,
"Preferences":{
"MaxHealthyPercentage":120,
"MinHealthyPercentage":90,
"InstanceWarmup":60,
"SkipMatching":false,
"AutoRollback":true,
"ScaleInProtectedInstances":"Ignore",
"StandbyInstances":"Ignore"
}
},
{
"InstanceRefreshId":"0e151305-1e57-4a32-a256-1fd14157c5ec",
"AutoScalingGroupName":"my-asg",
"Status":"Successful",
"StartTime":"2023-11-22T13:53:37+00:00",
"EndTime":"2023-11-22T13:59:45+00:00",
"PercentageComplete":100,
"InstancesToUpdate":0,
"Preferences":{
"MaxHealthyPercentage":120,
"MinHealthyPercentage":90,
"InstanceWarmup":60,
"SkipMatching":false,
"AutoRollback":true,
"ScaleInProtectedInstances":"Ignore",
"StandbyInstances":"Ignore"
}
}
]
}
```
You can further monitor the success or failure of in progress activities by viewing the group's scaling activities. The scaling activities also help you drill in for more details to help you troubleshoot issues with an instance refresh. For more information, see [Troubleshoot issues in Amazon EC2 Auto Scaling](CHAP_Troubleshooting.md).
------
## Instance refresh statuses
When you start an instance refresh, it enters the **Pending** status. It passes from **Pending** to **InProgress** until it reaches **Successful**, **Failed**, **Cancelled**, **RollbackSuccessful**, or **RollbackFailed**.
An instance refresh can have the following statuses:
| Status | Description |
| --- | --- |
| Pending | The request was created, but the instance refresh has not started. |
| InProgress | An instance refresh is in progress. |
| Successful | An instance refresh completed successfully. |
| Failed | An instance refresh failed to complete. You can troubleshoot using the status reason and the scaling activities. |
| Cancelling | An ongoing instance refresh is being cancelled. |
| Cancelled | The instance refresh is cancelled. |
| RollbackInProgress | An instance refresh is being rolled back. |
| RollbackFailed | The rollback failed to complete. You can troubleshoot using the status reason and the scaling activities. |
| RollbackSuccessful | The rollback completed successfully. |
| Baking | Waiting the specified bake time after an instance refresh has finished updating instances. |
# Replace root volumes during instance refresh
**Topics**
+ [How it works](#start-instance-refresh-replace-root-volume-how-it-works)
+ [Requirements](#start-instance-refresh-replace-root-volume-requirements)
+ [Start an instance refresh with Replace Root Volume](#start-instance-refresh-replace-root-volume-cli)
+ [Limitations](#start-instance-refresh-replace-root-volume-limitations)
+ [Use lifecycle hooks with replace root volume](#replace-root-volume-lifecycle-hooks)
## How it works
Root volume replacement updates your instances by replacing only the root EBS volume while keeping the instance running. This removes the need to launch new instances and avoids potential capacity constraints. This process preserves all other instance resources including:
+ Network interfaces and IP addresses
+ Non-root EBS volumes
+ Instance store volumes and data
+ Security groups and IAM roles
During root volume replacement, your application continues running on the existing instance. The original root volume is detached, a new root volume is created from your specified AMI, and then attached to the same instance. Original root volumes are automatically deleted after successful replacement.
When you use the replace root volume strategy, instances go through these lifecycle states:
1. `ReplacingRootVolume` - Root volume replacement begins
1. `ReplacingRootVolume:Wait` - Waits for lifecycle hook completion (if configured)
1. `ReplacingRootVolume:Proceed` - Proceeds with replacement
1. `RootVolumeReplaced` - Replacement completed successfully
After root volume replacement completes, Auto Scaling conducts health checks on updated instances. If root volume replacement fails for an instance, Auto Scaling marks that instance for termination and replaces it with a new instance.
## Requirements
+ Your Auto Scaling group must use a mixed instances policy
+ All overrides in the mixed instances policy must specify an `ImageId`
+ AMIs must contain only a single root volume
+ All instances must match the group's launch template configuration
+ You must start the instance refresh with a desired configuration having a mixed instances policy containing `ImageId` overrides.
## Start an instance refresh with Replace Root Volume
**To start an instance refresh with Replace Root Volume (AWS CLI)**
Use the following [start-instance-refresh ](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command to start an instance refresh from the AWS CLI. You can specify any preferences that you want to change in a JSON configuration file. When you reference the configuration file, provide the file path and name as shown in the following example.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`:
**Example**
```
{
"AutoScalingGroupName": "my-asg",
"Strategy" : "ReplaceRootVolume",
"DesiredConfiguration":{
"MixedInstancesPolicy":{
"LaunchTemplate": {
"LaunchTemplateSpecification": {
"LaunchTemplateId":"my-launch-template",
"Version": "1"
},
"Overrides": [
{
"InstanceType":"c5.large",
"ImageId":"ami-1234example"
},
{
"InstanceType":"m5.large",
"ImageId":"ami-2345example"
}
]
}
}
},
"Preferences": {
"InstanceWarmup": 60,
"MinHealthyPercentage": 90,
"AutoRollback": true,
"ScaleInProtectedInstances": Ignore,
"StandbyInstances": Ignore
}
}
```
If preferences are not provided, default values are used. For more information, see [Understand the default values for an instance refresh](understand-instance-refresh-default-values.md).
Example output:
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
## Limitations
+ You can’t start an instance refresh with Replace Root Volume if the EC2 Auto Scaling group or the instance refresh desired configuration uses the `$Latest` or `$Default` launch template version.
+ You can’t start an instance refresh with Replace Root Volume on an Amazon EC2 Auto Scaling Group if it contains instances whose instance type is not present in the mixed instances policy.
+ During an instance refresh with Replace Root Volume, you can only attach instances with types that are present in the desired configuration's mixed instances policy.
+ You can’t start an instance refresh with Replace Root Volume on an EC2 Auto Scaling Group that has a warm pool.
+ You can't add a warm pool to an Amazon EC2 Auto Scaling group that has an active instance refresh with Replace Root Volume.
## Use lifecycle hooks with replace root volume
Instances undergoing root volume replacement follow their own lifecycle transitions, allowing you to invoke actions (for example, a Lambda function) before and/or after the replacement. For more information about lifecycle states during root volume replacement, see [Lifecycle state transitions for instances undergoing root volume replacement](lifecycle-hooks-overview.md#rvr-lifecycle-state-transitions).
For more information about adding a lifecycle hook, see [Add lifecycle hooks to your Auto Scaling group](adding-lifecycle-hooks.md). For more information about completing a lifecycle action, see [Complete a lifecycle action in an Auto Scaling group](completing-lifecycle-hooks.md).
Before root volume replacement, a lifecycle hook can be useful in the following scenarios:
+ You want to gracefully shut down your application before the root volume is replaced and the instance is rebooted.
+ You want to move data from the root volume to another location before the volume is replaced.
After root volume replacement, a lifecycle hook can be useful in the following scenarios:
+ You want to verify that your instance is fully ready with the new AMI before it starts receiving traffic.
+ You want to bootstrap application data that previously existed on the root volume.
When you add lifecycle hooks, consider the following:
+ When a lifecycle hook is configured for the `autoscaling:EC2_INSTANCE_TERMINATING` lifecycle action, an instance about to undergo root volume replacement pauses to perform a custom action when it reaches the `ReplacingRootVolume:Wait` state.
+ When a lifecycle hook is configured for the `autoscaling:EC2_INSTANCE_LAUNCHING` lifecycle action, an instance that just had its root volume replaced pauses to perform a custom action when it reaches the `Pending:Wait` state.
When instances reach a wait state, Amazon EC2 Auto Scaling sends a notification. Auto Scaling lifecycle hook notifications contain an `Action` field with value `ReplaceRootVolume` to indicate the instance is undergoing root volume replacement.
Examples of these notifications are available in the EventBridge section of this guide. For more information see [Instance refresh replace root volume lifecycle events](instance-refresh-eventbridge-events.md#instance-refresh-rvr-lifecycle-events).
# Cancel an instance refresh using the AWS Management Console or AWS CLI
You can cancel an instance refresh that is still in progress. You can't cancel it after it's finished.
Canceling an instance refresh does not roll back any instances that were already replaced. To roll back the changes to your instances, perform a rollback instead. For more information, see [Undo changes with a manual or auto rollback](instance-refresh-rollback.md).
**Topics**
+ [Cancel an instance refresh (console)](#cancel-instance-refresh-console)
+ [Cancel an instance refresh (AWS CLI)](#cancel-instance-refresh-cli)
## Cancel an instance refresh (console)
**To cancel an instance refresh**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to the Auto Scaling group.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Actions**, **Cancel**.
1. When prompted for confirmation, choose **Confirm**.
The status of the instance refresh is set to **Cancelling**. After the cancellation is complete, the status of the instance refresh is set to **Cancelled**.
## Cancel an instance refresh (AWS CLI)
**To cancel an instance refresh**
Use the [cancel-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/cancel-instance-refresh.html) command from the AWS CLI and provide the Auto Scaling group name.
```
aws autoscaling cancel-instance-refresh --auto-scaling-group-name my-asg
```
Example output:
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
**To cancel an instance refresh without waiting for transitioning instances**
Use the `--no-wait-for-transitioning-instances` option with the [cancel-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/cancel-instance-refresh.html) command from the AWS CLI to cancel an instance refresh without waiting for transitioning instances.
```
aws autoscaling cancel-instance-refresh —auto-scaling-group-name my-asg --no-wait-for-transitioning-instances
```
By default, when you cancel an instance refresh, Amazon EC2 Auto Scaling waits for any in-flight launches and terminations to complete before setting the status to **Cancelled**. If you have instances with long draining periods or need to start a new instance refresh immediately, you can use the command so that you don’t have to wait for these transitioning operations.
When you use this option, the instance refresh status changes to **Cancelled**, allowing you to start a new instance refresh. Any in-flight launches and terminations continue in the background.
# Undo changes with a manual or auto rollback
You can roll back an instance refresh that is still in progress. You can't roll it back after it's finished. You can, however, update your Auto Scaling group again by starting a new instance refresh.
When rolling back, Amazon EC2 Auto Scaling replaces the instances that have been deployed so far. The new instances match the configuration that you last saved on the Auto Scaling group before starting the instance refresh.
Amazon EC2 Auto Scaling provides the following ways to roll back:
+ Manual rollback: You start a rollback manually to reverse what was deployed up to the rollback point.
+ Auto rollback: Amazon EC2 Auto Scaling automatically reverses what was deployed if the instance refresh fails for some reason or if any CloudWatch alarms you specify go into the `ALARM` state.
**Topics**
+ [Considerations](#instance-refresh-rollback-considerations)
+ [Manually start a rollback](#instance-refresh-manual-rollback)
+ [Start an instance refresh with auto rollback](#instance-refresh-using-auto-rollback)
## Considerations
The following considerations apply when using a rollback:
+ The rollback option is only available if you specify a desired configuration as part of starting an instance refresh.
+ You can only roll back to a previous version of a launch template if the version is a specific numbered version. The rollback option is not available if the Auto Scaling group is configured to use the `$Latest` or `$Default` launch template version.
+ You also cannot roll back to a launch template that is configured to use an AMI alias from the AWS Systems Manager Parameter Store.
+ The configuration that you last saved on the Auto Scaling group must be in a stable state. If it's not in a stable state, the rollback workflow will still occur, but it will eventually fail. Until you resolve the issue, the Auto Scaling group might be in a failed state where it can no longer launch instances successfully. This might impact the availability of the service or application.
## Manually start a rollback
------
#### [ Console ]
**To manually start a rollback of an instance refresh (console)**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to the Auto Scaling group.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Actions**, **Start rollback**.
1. When prompted for confirmation, choose **Confirm**.
------
#### [ AWS CLI ]
**To manually start a rollback of an instance refresh (AWS CLI)**
Use the [rollback-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/rollback-instance-refresh.html) command from the AWS CLI and provide the Auto Scaling group name.
```
aws autoscaling rollback-instance-refresh --auto-scaling-group-name my-asg
```
Example output:
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
**Tip**
If this command throws an error, make sure that you have updated the AWS CLI locally to the latest version.
------
## Start an instance refresh with auto rollback
Using the auto rollback feature, you can automatically roll back the instance refresh when it fails, such as when there are errors or a specified Amazon CloudWatch alarm goes into the `ALARM` state.
If you enable auto rollback, and there are errors while replacing instances, the instance refresh attempts to complete all replacements for one hour before it fails and rolls back. These errors are usually caused by things like EC2 launch failures, misconfigured health checks, or not ignoring or allowing the termination of instances that are in `Standby` state or protected from scale in.
Specifying CloudWatch alarms is optional. To specify an alarm, you first need to create it. You can specify metric alarms and composite alarms. For information about creating the alarm, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). Using Elastic Load Balancing metrics as an example, if you use an Application Load Balancer, you could use the `HTTPCode_ELB_5XX_Count` and `HTTPCode_ELB_4XX_Count` metrics.
**Considerations**
+ If you specify a CloudWatch alarm but do not enable auto rollback, and the alarm state goes to `ALARM`, the instance refresh fails without rolling back.
+ You can choose a maximum of 10 alarms when you start an instance refresh.
+ When choosing a CloudWatch alarm, the alarm must be in a compatible state. If the alarm state is `INSUFFICIENT_DATA` or `ALARM`, you receive an error when you try to start the instance refresh.
+ When creating an alarm for Amazon EC2 Auto Scaling to use, the alarm should include how to treat missing data points. If a metric is frequently missing data points by design, the state of the alarm is `INSUFFICIENT_DATA` during those periods. When this happens, Amazon EC2 Auto Scaling cannot replace instances until new data points are found. To force the alarm to maintain the previous `ALARM` or `OK` state, you could choose to ignore missing data instead. For more information, see [Configuring how alarms treat missing data](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data) in the *Amazon CloudWatch User Guide*.
------
#### [ Console ]
**To start an instance refresh with auto rollback (console)**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to the Auto Scaling group.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Start instance refresh**.
1. Follow the [Start an instance refresh (console)](start-instance-refresh.md#start-instance-refresh-console) procedure and configure your instance refresh settings as needed.
1. (Optional) Under **Refresh settings**, for **CloudWatch alarm**, choose **Enable CloudWatch alarms**, and then choose one or more alarms to identify any issues and fail the operation if an alarm goes into the `ALARM` state.
1. Under **Rollback settings**, choose **Enable auto rollback** to automatically roll back a failed instance refresh to the configuration that you last saved on the Auto Scaling group before starting the instance refresh.
1. Review your selections, and then choose **Start instance refresh**.
------
#### [ AWS CLI ]
**To start an instance refresh with auto rollback (AWS CLI)**
Use the [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command and specify `true` for the `AutoRollback` option in the `Preferences`.
The following example shows how to start an instance refresh that will automatically roll back if something fails. Replace the *`italicized`* parameter values with your own.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`.
```
{
"AutoScalingGroupName": "my-asg",
"DesiredConfiguration": {
"LaunchTemplate": {
"LaunchTemplateName": "my-launch-template",
"Version": "1"
}
},
"Preferences": {
"AutoRollback": true
}
}
```
Alternatively, to automatically roll back when the instance refresh fails or when a specified CloudWatch alarm is in the `ALARM` state, specify the `AlarmSpecification` option in the `Preferences` and provide the alarm name, as in the following example. Replace the *`italicized`* parameter values with your own.
```
{
"AutoScalingGroupName": "my-asg",
"DesiredConfiguration": {
"LaunchTemplate": {
"LaunchTemplateName": "my-launch-template",
"Version": "1"
}
},
"Preferences": {
"AutoRollback": true,
"AlarmSpecification": { "Alarms": [ "my-alarm" ] }
}
}
```
If successful, the command returns output similar to the following.
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
**Tip**
If this command throws an error, make sure that you have updated the AWS CLI locally to the latest version.
------
# Use an instance refresh with skip matching
Skip matching tells Amazon EC2 Auto Scaling to ignore instances that already have your latest updates. This way, you don't replace more instances than you need to. This is helpful when you want to make sure that your Auto Scaling group uses a particular version of your launch template and only replaces those instances that use a different version.
The following considerations apply to skip matching:
+ If you start an instance refresh with both skip matching and a *desired configuration*, Amazon EC2 Auto Scaling checks to see if any instances match your desired configuration. Then, it only replaces the instances that don't match your desired configuration. After the instance refresh succeeds, Amazon EC2 Auto Scaling updates the group to reflect your desired configuration.
+ If you start an instance refresh with skip matching, but you don't specify a desired configuration, Amazon EC2 Auto Scaling checks to see if any instances match the configuration that you last saved on the Auto Scaling group. Then, it only replaces the instances that don't match your last saved configuration.
+ You can use skip matching with a new launch template, a new version of a launch template, or a set of instance types. If you enable skip matching, but none of these are changing, the instance refresh will succeed immediately without replacing any instances. If you made any other changes in your desired configuration (such as changing your Spot allocation strategy), Amazon EC2 Auto Scaling waits for the instance refresh to succeed. Then, it updates the Auto Scaling group settings to reflect the new desired configuration.
+ You cannot use skip matching with a new launch configuration.
+ When you start an instance refresh and provide a desired configuration, Amazon EC2 Auto Scaling ensures that all instances use your desired configuration. Therefore, when you specify either `$Default` or `$Latest` as the desired version for your launch template and then create a new version of the launch template while an instance refresh is in progress, any instances that were already replaced will be replaced again.
+ Skip matching doesn't know whether a user data script in the launch template will pull updated code and install it on new instances. As a result, skip matching might skip replacing instances that have outdated code installed. In this case, you should turn off skip matching to make sure that all instances receive your latest code, even without a launch template version update.
This section includes AWS CLI instructions for starting an instance refresh with skip matching enabled. For instructions on using the console, see [Start an instance refresh (console)](start-instance-refresh.md#start-instance-refresh-console).
## Skip matching (basic procedure)
Follow the steps in this section to use the AWS CLI to do the following:
+ Create the launch template that you want to apply to your instances.
+ Start an instance refresh to apply your launch template to your Auto Scaling group. If you do not enable skip matching, all instances will be replaced. This is true even if the launch template used to provision the instance is the same as the one that you specified for your desired configuration.
**To use skip matching with a new launch template**
1. Use the [create-launch-template](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/create-launch-template.html) command to create a new launch template for your Auto Scaling group. Include the `--launch-template-data` option and JSON input that defines the details of the instances that are created for your Auto Scaling group.
For example, use the following command to create a basic launch template with the AMI ID *`ami-0123456789abcdef0`* and the `t2.micro` instance type.
```
aws ec2 create-launch-template --launch-template-name my-template-for-auto-scaling --version-description version1 \
--launch-template-data '{"ImageId":"ami-0123456789abcdef0","InstanceType":"t2.micro"}'
```
If successful, the command returns output similar to the following.
```
{
"LaunchTemplate": {
"LaunchTemplateId": "lt-068f72b729example",
"LaunchTemplateName": "my-template-for-auto-scaling",
"CreatedBy": "arn:aws:iam::123456789012:user/Bob",
"CreateTime": "2023-01-30T18:16:06.000Z",
"DefaultVersionNumber": 1,
"LatestVersionNumber": 1
}
}
```
For more information, see [Examples for creating and managing launch templates with the AWS CLI](examples-launch-templates-aws-cli.md).
1. Use the [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command to initiate the instance replacement workflow and apply your new launch template with the ID *`lt-068f72b729example`*. Because the launch template is new, it only has one version. This means that version `1` of the launch template is the target of this instance refresh. If a scale-out event occurs during the instance refresh, and Amazon EC2 Auto Scaling provisions new instances using the version `1` of this launch template, they will not be replaced. On successful completion of the operation, the new launch template is successfully applied to your Auto Scaling group.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`.
```
{
"AutoScalingGroupName": "my-asg",
"DesiredConfiguration": {
"LaunchTemplate": {
"LaunchTemplateId": "lt-068f72b729example",
"Version": "$Default"
}
},
"Preferences": {
"SkipMatching": true
}
}
```
If successful, the command returns output similar to the following.
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
## Skip matching (mixed instances group)
If you have an Auto Scaling group with a [mixed instances policy](ec2-auto-scaling-mixed-instances-groups.md), follow the steps in this section to use the AWS CLI to start an instance refresh with skip matching. You have the following options:
+ Provide a new launch template to apply to all instance types specified in the policy.
+ Provide an updated set of instance types with or without changing the launch template in the policy. For example, you might want to migrate away from unwanted instance types. You would use the launch template as is, without changing the AMI, security groups, or other specifics of the instances being replaced.
Follow the steps in one of the following sections, depending on which option fits your needs.
**To use skip matching with a new launch template**
1. Use the [create-launch-template](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/create-launch-template.html) command to create a new launch template for your Auto Scaling group. Include the `--launch-template-data` option and JSON input that defines the details of the instances that are created for your Auto Scaling group.
For example, use the following command to create a launch template with the AMI ID *`ami-0123456789abcdef0`*.
```
aws ec2 create-launch-template --launch-template-name my-new-template --version-description version1 \
--launch-template-data '{"ImageId":"ami-0123456789abcdef0"}'
```
If successful, the command returns output similar to the following.
```
{
"LaunchTemplate": {
"LaunchTemplateId": "lt-04d5cc9b88example",
"LaunchTemplateName": "my-new-template",
"CreatedBy": "arn:aws:iam::123456789012:user/Bob",
"CreateTime": "2023-01-31T15:56:02.000Z",
"DefaultVersionNumber": 1,
"LatestVersionNumber": 1
}
}
```
For more information, see [Examples for creating and managing launch templates with the AWS CLI](examples-launch-templates-aws-cli.md).
1. To view the existing mixed instances policy for your Auto Scaling group, run the [describe-auto-scaling-groups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/describe-auto-scaling-groups.html) command. You'll need this information in the next step, when you start the instance refresh.
The following example command returns the mixed instances policy configured for the Auto Scaling group named *`my-asg`*.
```
aws autoscaling describe-auto-scaling-groups --auto-scaling-group-name my-asg
```
If successful, the command returns output similar to the following.
```
{
"AutoScalingGroups":[
{
"AutoScalingGroupName":"my-asg",
"AutoScalingGroupARN":"arn",
"MixedInstancesPolicy":{
"LaunchTemplate":{
"LaunchTemplateSpecification":{
"LaunchTemplateId":"lt-073693ed27example",
"LaunchTemplateName":"my-old-template",
"Version":"$Default"
},
"Overrides":[
{
"InstanceType":"c5.large"
},
{
"InstanceType":"c5a.large"
},
{
"InstanceType":"m5.large"
},
{
"InstanceType":"m5a.large"
}
]
},
"InstancesDistribution":{
"OnDemandAllocationStrategy":"prioritized",
"OnDemandBaseCapacity":1,
"OnDemandPercentageAboveBaseCapacity":50,
"SpotAllocationStrategy":"price-capacity-optimized"
}
},
"MinSize":1,
"MaxSize":5,
"DesiredCapacity":4,
...
}
]
}
```
1. Use the [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command to initiate the instance replacement workflow and apply your new launch template with the ID *`lt-04d5cc9b88example`*. Because the launch template is new, it only has one version. This means that version `1` of the launch template is the target of this instance refresh. If a scale-out event occurs during the instance refresh, and Amazon EC2 Auto Scaling provisions new instances using the version `1` of this launch template, they will not be replaced. On successful completion of the operation, the updated mixed instances policy is successfully applied to your Auto Scaling group.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`.
```
{
"AutoScalingGroupName":"my-asg",
"DesiredConfiguration":{
"MixedInstancesPolicy":{
"LaunchTemplate":{
"LaunchTemplateSpecification":{
"LaunchTemplateId":"lt-04d5cc9b88example",
"Version":"$Default"
},
"Overrides":[
{
"InstanceType":"c5.large"
},
{
"InstanceType":"c5a.large"
},
{
"InstanceType":"m5.large"
},
{
"InstanceType":"m5a.large"
}
]
},
"InstancesDistribution":{
"OnDemandAllocationStrategy":"prioritized",
"OnDemandBaseCapacity":1,
"OnDemandPercentageAboveBaseCapacity":50,
"SpotAllocationStrategy":"price-capacity-optimized"
}
}
}
},
"Preferences":{
"SkipMatching":true
}
}
```
If successful, the command returns output similar to the following.
```
{
"InstanceRefreshId": "08b91cf7-8fa6-48af-b6a6-d227f40f1b9b"
}
```
In this next procedure, you provide an updated set of instance types without changing the launch template.
**To use skip matching with an updated set of instance types**
1. To view the existing mixed instances policy for your Auto Scaling group, run the [describe-auto-scaling-groups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/describe-auto-scaling-groups.html) command. You'll need this information in the next step, when you start the instance refresh.
The following example command returns the mixed instances policy configured for the Auto Scaling group named *`my-asg`*.
```
aws autoscaling describe-auto-scaling-groups --auto-scaling-group-name my-asg
```
If successful, the command returns output similar to the following.
```
{
"AutoScalingGroups":[
{
"AutoScalingGroupName":"my-asg",
"AutoScalingGroupARN":"arn",
"MixedInstancesPolicy":{
"LaunchTemplate":{
"LaunchTemplateSpecification":{
"LaunchTemplateId":"lt-073693ed27example",
"LaunchTemplateName":"my-template-for-auto-scaling",
"Version":"$Default"
},
"Overrides":[
{
"InstanceType":"c5.large"
},
{
"InstanceType":"c5a.large"
},
{
"InstanceType":"m5.large"
},
{
"InstanceType":"m5a.large"
}
]
},
"InstancesDistribution":{
"OnDemandAllocationStrategy":"prioritized",
"OnDemandBaseCapacity":1,
"OnDemandPercentageAboveBaseCapacity":50,
"SpotAllocationStrategy":"price-capacity-optimized"
}
},
"MinSize":1,
"MaxSize":5,
"DesiredCapacity":4,
...
}
]
}
```
1. Use the [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command to initiate the instance replacement workflow and apply your updates. If you want to replace instances that use specific instance types, your desired configuration must specify the mixed instance policy with only the instance types that you want. You can choose whether to add new instance types in their place.
The following example command starts an instance refresh without the unwanted instance type *`m5a.large`*. When an instance type in your group doesn’t match one of the remaining three instance types, the instances are replaced. (Note that an instance refresh does not choose the instance types from which to provision the new instances; instead, the [allocation strategies](allocation-strategies.md) do that.) On successful completion of the operation, the updated mixed instances policy is successfully applied to your Auto Scaling group.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`
```
{
"AutoScalingGroupName":"my-asg",
"DesiredConfiguration":{
"MixedInstancesPolicy":{
"LaunchTemplate":{
"LaunchTemplateSpecification":{
"LaunchTemplateId":"lt-073693ed27example",
"Version":"$Default"
},
"Overrides":[
{
"InstanceType":"c5.large"
},
{
"InstanceType":"c5a.large"
},
{
"InstanceType":"m5.large"
}
]
},
"InstancesDistribution":{
"OnDemandAllocationStrategy":"prioritized",
"OnDemandBaseCapacity":1,
"OnDemandPercentageAboveBaseCapacity":50,
"SpotAllocationStrategy":"price-capacity-optimized"
}
}
}
},
"Preferences":{
"SkipMatching":true
}
}
```
# Add checkpoints to an instance refresh
When using an instance refresh, you can choose to replace instances in phases, so that you can perform verifications on your instances as you go. To do a phased replacement, you add checkpoints, which are points in time where the instance refresh pauses. Using checkpoints gives you greater control over how you choose to update your Auto Scaling group. It helps you to confirm that your application will function in a reliable, predictable manner.
**Topics**
+ [How it works](#instance-refresh-checkpoints-how-it-works)
+ [Considerations](#instance-refresh-checkpoints-considerations)
+ [Enable checkpoints](enable-checkpoints-console-cli.md)
## How it works
When starting an instance refresh, you specify checkpoints as percentages of the total number of instances in the Auto Scaling group. These checkpoints indicate the minimum percentage of instances in the Auto Scaling group that must be new instances before the checkpoint is considered reached. For example, if your checkpoints are `[20, 50, 100]`, the first checkpoint is reached when 20 percent of instances are new, the second when 50 percent are new, and the final checkpoint when all instances are new.
Amazon EC2 Auto Scaling paces instance replacements to honor the specified checkpoint percentages while maintaining the group's minimum healthy percentage. To reach a checkpoint percentage, Amazon EC2 Auto Scaling will sometimes replace fewer but never more than what the minimum healthy percentage allows.
Consider the following Auto Scaling group that has 10 instances. The checkpoint percentages are `[20,50,100]`, the minimum healthy percentage is 80 percent, and the maximum healthy percentage is 100 percent. To maintain the minimum healthy percentage, only two instances can be replaced at a time. The following diagram summarizes the process for replacing instances before a checkpoint is reached.
![\[This diagram shows how checkpoints affect the flow of an instance refresh.\]](http://docs.aws.amazon.com/autoscaling/ec2/userguide/images/checkpoints-instance-refresh.png)
In the above example, there is an instance warmup period for each new instance that starts. You might also have a lifecycle hook that puts an instance into a wait state and then performs a custom action as it's launching or terminating.
Amazon EC2 Auto Scaling emits events for each checkpoint except for the 100 percent complete checkpoint. You can add an EventBridge rule to send the events to a target such as Amazon SNS. This way, you are notified when you can run the required verifications. For more information, see [Create EventBridge rules for instance refresh events](monitor-events-eventbridge-sns.md).
## Considerations
Keep the following considerations in mind when using checkpoints:
+ Because checkpoints are based on percentages, the number of instances to replace changes with the size of the group. When a scale-out activity occurs and the size of the group increases, an in progress operation could reach a checkpoint again. If that happens, Amazon EC2 Auto Scaling sends another notification and repeats the wait time between checkpoints before continuing.
+ It's possible to skip a checkpoint under certain circumstances. For example, suppose that your Auto Scaling group has two instances and your checkpoint percentages are `[10,40,100]`. After the first instance is replaced, Amazon EC2 Auto Scaling calculates that 50 percent of the group was replaced. Because 50 percent is higher than the first two checkpoints, it skips the first checkpoint (`10`) and sends a notification for the second checkpoint (`40`).
+ Canceling the operation stops any further replacements from being made. If you cancel the operation or it fails before reaching the last checkpoint, any instances that were already replaced are not rolled back to their previous configuration.
+ For a partial refresh, when you rerun the operation, Amazon EC2 Auto Scaling doesn't restart from the point of the last checkpoint, nor does it stop when only the earlier instances are replaced. However, it targets earlier instances for replacement first, before targeting new instances.
+ The actual percentage complete might be higher than the percentage for that checkpoint when the checkpoint's percentage is too low relative to the number of instances in the group. For example, suppose the checkpoint's percentage is 20 percent and the group has four instances. If Amazon EC2 Auto Scaling replaces one of the four instances, the actual percentage replaced (25 percent) will be higher than the checkpoint's percentage (20 percent).
+ After a checkpoint is reached, the displayed overall percentage complete doesn't update until after the instances finish warming up. For example, your checkpoint percentages are `[20,50]` with a checkpoint delay of 15 minutes and a minimum healthy percentage of 80 percent. Your Auto Scaling group has 10 instances and makes the following replacements:
+ 0:00: Two earlier instances are replaced with new ones.
+ 0:10: Two new instances finish warming up.
+ 0:25: Two earlier instances are replaced with new ones. (To maintain the minimum healthy percentage, only two instances are replaced.)
+ 0:35: Two new instances finish warming up.
+ 0:35: One earlier instance is replaced with a new one.
+ 0:45: One new instance finishes warming up.
At 0:35, the operation stops launching new instances. The percentage complete doesn't accurately reflect the number of completed replacements yet (50 percent), because the new instance isn't done warming up. After the new instance completes its warmup period at 0:45, the percentage complete shows 50 percent.
+ If multiple checkpoints are enabled, the instance refresh checkpoint must be set to 100% to ensure complete replacement of all instances. If you set the final checkpoint to a percentage less than 100% (for example, 50%), the instance refresh will stop replacing instances after reaching that checkpoint percentage and will not automatically continue to 100% completion.
# Enable checkpoints using the using the AWS Management Console or AWS CLI
You can use the AWS Management Console or AWS CLI to enable checkpoints.
## Enable checkpoints (console)
You can enable checkpoints before starting an instance refresh to replace instances using an incremental or phased approach. This provides additional time for verification.
**To start an instance refresh that uses checkpoints**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/), and choose **Auto Scaling Groups** from the navigation pane.
1. Select the check box next to your Auto Scaling group.
A split pane opens up at the bottom of the **Auto Scaling groups** page.
1. On the **Instance refresh** tab, in **Active instance refresh**, choose **Start instance refresh**.
1. On the **Start instance refresh** page, enter the values for **Minimum healthy percentage** and **Instance warmup**.
1. Select the **Enable checkpoints** check box.
This displays a box where you can define the percentage threshold for the first checkpoint.
1. For **Proceed until \$1\$1\$1\$1 % of the group is refreshed**, enter a number (1–100). This sets the percentage for the first checkpoint.
1. To add another checkpoint, choose **Add checkpoint** and then define the percentage for the next checkpoint.
1. To specify how long Amazon EC2 Auto Scaling waits after a checkpoint is reached, update the fields in **Wait for `1` `hour` between checkpoints**. The time unit can be hours, minutes, or seconds.
1. If you are finished with your instance refresh selections, choose **Start instance refresh**.
## Enable checkpoints (AWS CLI)
To start an instance refresh with checkpoints enabled using the AWS CLI, you need a configuration file that defines the following parameters:
+ `CheckpointPercentages`: Specifies threshold values for the percentage of instances to be replaced. These threshold values provide the checkpoints. When the percentage of instances that are replaced and warmed up reaches one of the specified thresholds, the operation waits for a specified period of time. You specify the number of seconds to wait in `CheckpointDelay`. When the specified period of time has passed, the instance refresh continues until it reaches the next checkpoint (if applicable).
+ `CheckpointDelay`: Specifies the amount of time, in seconds, to wait after a checkpoint is reached before continuing. Choose a time period that provides enough time to perform your verifications.
The last value shown in the `CheckpointPercentages` array describes the percentage of the Auto Scaling group that needs to be successfully replaced. The operation transitions to `Successful` after this percentage is successfully replaced and each instance is considered to have finished initializing.
**To create multiple checkpoints**
To create multiple checkpoints, use the following example [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command. This example configures an instance refresh that initially refreshes one percent of the Auto Scaling group. After waiting 10 minutes, it then refreshes the next 19 percent and waits another 10 minutes. Finally, it refreshes the rest of the group before concluding the operation.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`:
```
{
"AutoScalingGroupName": "my-asg",
"Preferences": {
"InstanceWarmup": 60,
"MinHealthyPercentage": 80,
"CheckpointPercentages": [1,20,100],
"CheckpointDelay": 600
}
}
```
**To create a single checkpoint**
To create a single checkpoint, use the following example [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command. This example configures an instance refresh that initially refreshes 20 percent of the Auto Scaling group. After waiting 10 minutes, it then refreshes the rest of the group before concluding the operation.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`:
```
{
"AutoScalingGroupName": "my-asg",
"Preferences": {
"InstanceWarmup": 60,
"MinHealthyPercentage": 80,
"CheckpointPercentages": [20,100],
"CheckpointDelay": 600
}
}
```
**To partially refresh the Auto Scaling group**
To replace only a portion of your Auto Scaling group and then stop completely, use the following example [start-instance-refresh](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/autoscaling/start-instance-refresh.html) command. This example configures an instance refresh that initially refreshes one percent of the Auto Scaling group. After waiting 10 minutes, it then refreshes the next 19 percent before concluding the operation.
```
aws autoscaling start-instance-refresh --cli-input-json file://config.json
```
Contents of `config.json`:
```
{
"AutoScalingGroupName": "my-asg",
"Preferences": {
"InstanceWarmup": 60,
"MinHealthyPercentage": 80,
"CheckpointPercentages": [1,20],
"CheckpointDelay": 600
}
}
```