# InstanceRefreshOptions

Options for customizing the instance refresh update policy.

- Source: [`aws-autoscaling/lib/auto-scaling-group.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-autoscaling/lib/auto-scaling-group.ts#L1204)
- Type last changed: v2.263.0 · 31 Jul 2026

## Example

```ts
declare const vpc: ec2.Vpc;
declare const instanceType: ec2.InstanceType;
declare const machineImage: ec2.IMachineImage;
declare const alarm: cloudwatch.Alarm;

new autoscaling.AutoScalingGroup(this, 'ASG', {
  vpc,
  instanceType,
  machineImage,

  updatePolicy: autoscaling.UpdatePolicy.instanceRefresh({
    strategy: autoscaling.InstanceRefreshStrategy.ROLLING,
    minHealthyPercentage: 90,
    maxHealthyPercentage: 100,
    instanceWarmup: Duration.seconds(300),
    checkpointPercentages: [50, 100],
    checkpointDelay: Duration.minutes(10),
    alarms: [alarm],
  }),
});
```

## Properties

- `alarms`: [IAlarmRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_cloudwatch.IAlarmRef.html)[] — The CloudWatch alarms to monitor during the instance refresh.

  **Default:** no alarms

  If any of the alarms goes into
  ALARM state, the instance refresh fails. You can specify up to 10 alarms.

- `bakeTime`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.seconds(0) — The amount of time after an instance refresh completes successfully before CloudFormation considers the update successful.

- `checkpointDelay`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The amount of time to wait after a checkpoint is reached before continuing.

  **Default:** 3600 seconds (1 hour), applied only when checkpointPercentages is set

- `checkpointPercentages`: number[] — Threshold values for each checkpoint in ascending order.

  **Default:** no checkpoints

  Each number must be unique.
  To replace all instances in the group, the last number in the array must be 100.

- `instanceWarmup`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The amount of time to wait after a new instance enters the InService state before moving on to refresh the next instance.

  **Default:** the group's DefaultInstanceWarmup if defined; otherwise the group's HealthCheckGracePeriod

- `maxHealthyPercentage`: number — The maximum percentage of the group that can be in service and healthy, or pending, to support your workload during the instance refresh.

  **Default:** the value set in the Auto Scaling group's instance maintenance policy, if defined; otherwise 110 when the strategy is Rolling, or 100 when the strategy is ReplaceRootVolume

  The difference between
  `maxHealthyPercentage` and `minHealthyPercentage` cannot be greater than 100. A larger
  range increases the number of instances that can be replaced at the same time.

- `minHealthyPercentage`: number — The minimum percentage of the group to keep in service, healthy, and ready to use to support your workload during the instance refresh, expressed as a percentage of the group's desired capacity.

  **Default:** the value set in the Auto Scaling group's instance maintenance policy, if defined; otherwise 100 when the strategy is Rolling, or 90 when the strategy is ReplaceRootVolume

- `scaleInProtectedInstances`: [ScaleInProtectedInstances](/cdk/api/v2/docs/aws-cdk-lib.aws_autoscaling.ScaleInProtectedInstances.html) = ScaleInProtectedInstances.WAIT — Specifies the behavior of instances that are protected from scale in during an instance refresh.

- `skipMatching`: boolean = true — Indicates whether skip matching is enabled.

- `standbyInstances`: [StandbyInstances](/cdk/api/v2/docs/aws-cdk-lib.aws_autoscaling.StandbyInstances.html) = StandbyInstances.WAIT — Specifies the behavior of instances in standby during an instance refresh.

- `strategy`: [InstanceRefreshStrategy](/cdk/api/v2/docs/aws-cdk-lib.aws_autoscaling.InstanceRefreshStrategy.html) (required) — The strategy to use for the instance refresh.