Table Of Contents

Feedback

User Guide

First time using the AWS CLI? See the User Guide for help getting started.

Note: You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . autoscaling ]

start-instance-refresh

Description

Starts a new instance refresh operation. An instance refresh performs a rolling replacement of all or some instances in an Auto Scaling group. Each instance is terminated first and then replaced, which temporarily reduces the capacity available within your Auto Scaling group.

This operation is part of the instance refresh feature in Amazon EC2 Auto Scaling, which helps you update instances in your Auto Scaling group. This feature is helpful, for example, when you have a new AMI or a new user data script. You just need to create a new launch template that specifies the new AMI or user data script. Then start an instance refresh to immediately begin the process of updating instances in the group.

If the call succeeds, it creates a new instance refresh request with a unique ID that you can use to track its progress. To query its status, call the DescribeInstanceRefreshes API. To describe the instance refreshes that have already run, call the DescribeInstanceRefreshes API. To cancel an instance refresh operation in progress, use the CancelInstanceRefresh API.

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.

Synopsis

  start-instance-refresh
--auto-scaling-group-name <value>
[--strategy <value>]
[--desired-configuration <value>]
[--preferences <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

Options

--auto-scaling-group-name (string)

The name of the Auto Scaling group.

--strategy (string)

The strategy to use for the instance refresh. The only valid value is Rolling .

A rolling update helps you update your instances gradually. A rolling update can fail due to failed health checks or if instances are on standby or are protected from scale in. If the rolling update process fails, any instances that are replaced are not rolled back to their previous configuration.

Possible values:

  • Rolling

--desired-configuration (structure)

The desired configuration. For example, the desired configuration can specify a new launch template or a new version of the current launch template.

Once the instance refresh succeeds, Amazon EC2 Auto Scaling updates the settings of the Auto Scaling group to reflect the new desired configuration.

Note

When you specify a new launch template or a new version of the current launch template for your desired configuration, consider enabling the SkipMatching property in preferences. If it's enabled, Amazon EC2 Auto Scaling skips replacing instances that already use the specified launch template and version. This can help you reduce the number of replacements that are required to apply updates.

LaunchTemplate -> (structure)

Describes the launch template and the version of the launch template that Amazon EC2 Auto Scaling uses to launch Amazon EC2 instances. For more information about launch templates, see Launch templates in the Amazon EC2 Auto Scaling User Guide .

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

MixedInstancesPolicy -> (structure)

Describes a mixed instances policy. A mixed instances policy contains the instance types Amazon EC2 Auto Scaling can launch, and other information Amazon EC2 Auto Scaling can use to launch instances to help you optimize your costs. For more information, see Auto Scaling groups with multiple instance types and purchase options in the Amazon EC2 Auto Scaling User Guide .

LaunchTemplate -> (structure)

Specifies the launch template to use and the instance types (overrides) that are used to provision EC2 instances to fulfill On-Demand and Spot capacities. Required when creating a mixed instances policy.

LaunchTemplateSpecification -> (structure)

The launch template to use.

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

Overrides -> (list)

Any properties that you specify override the same properties in the launch template. If not provided, Amazon EC2 Auto Scaling uses the instance type specified in the launch template when it launches an instance.

(structure)

Describes an override for a launch template. The maximum number of instance types that can be associated with an Auto Scaling group is 40. The maximum number of distinct launch templates you can define for an Auto Scaling group is 20. For more information about configuring overrides, see Configuring overrides in the Amazon EC2 Auto Scaling User Guide .

InstanceType -> (string)

The instance type, such as m3.xlarge . You must use an instance type that is supported in your requested Region and Availability Zones. For more information, see Instance types in the Amazon Elastic Compute Cloud User Guide .

WeightedCapacity -> (string)

The number of capacity units provided by the specified instance type in terms of virtual CPUs, memory, storage, throughput, or other relative performance characteristic. When a Spot or On-Demand Instance is provisioned, the capacity units count toward the desired capacity. Amazon EC2 Auto Scaling provisions instances until the desired capacity is totally fulfilled, even if this results in an overage. For example, if there are 2 units remaining to fulfill capacity, and Amazon EC2 Auto Scaling can only provision an instance with a WeightedCapacity of 5 units, the instance is provisioned, and the desired capacity is exceeded by 3 units. For more information, see Instance weighting for Amazon EC2 Auto Scaling in the Amazon EC2 Auto Scaling User Guide . Value must be in the range of 1 to 999.

LaunchTemplateSpecification -> (structure)

Provides the launch template to be used when launching the instance type. For example, some instance types might require a launch template with a different AMI. If not provided, Amazon EC2 Auto Scaling uses the launch template that's defined for your mixed instances policy. For more information, see Specifying a different launch template for an instance type in the Amazon EC2 Auto Scaling User Guide .

LaunchTemplateId -> (string)

The ID of the launch template. To get the template ID, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

LaunchTemplateName -> (string)

The name of the launch template. To get the template name, use the Amazon EC2 DescribeLaunchTemplates API operation. New launch templates can be created using the Amazon EC2 CreateLaunchTemplate API.

Conditional: You must specify either a LaunchTemplateId or a LaunchTemplateName .

Version -> (string)

The version number, $Latest , or $Default . To get the version number, use the Amazon EC2 DescribeLaunchTemplateVersions API operation. New launch template versions can be created using the Amazon EC2 CreateLaunchTemplateVersion API. If the value is $Latest , Amazon EC2 Auto Scaling selects the latest version of the launch template when launching instances. If the value is $Default , Amazon EC2 Auto Scaling selects the default version of the launch template when launching instances. The default value is $Default .

InstancesDistribution -> (structure)

Specifies the instances distribution. If not provided, the value for each property in InstancesDistribution uses a default value.

OnDemandAllocationStrategy -> (string)

Indicates how to allocate instance types to fulfill On-Demand capacity. The only valid value is prioritized , which is also the default value. This strategy uses the order of instance types in the LaunchTemplateOverrides to define the launch priority of each instance type. The first instance type in the array is prioritized higher than the last. If all your On-Demand capacity cannot be fulfilled using your highest priority instance, then the Auto Scaling groups launches the remaining capacity using the second priority instance type, and so on.

OnDemandBaseCapacity -> (integer)

The minimum amount of the Auto Scaling group's capacity that must be fulfilled by On-Demand Instances. This base portion is provisioned first as your group scales. Defaults to 0 if not specified. If you specify weights for the instance types in the overrides, set the value of OnDemandBaseCapacity in terms of the number of capacity units, and not the number of instances.

OnDemandPercentageAboveBaseCapacity -> (integer)

Controls the percentages of On-Demand Instances and Spot Instances for your additional capacity beyond OnDemandBaseCapacity . Expressed as a number (for example, 20 specifies 20% On-Demand Instances, 80% Spot Instances). Defaults to 100 if not specified. If set to 100, only On-Demand Instances are provisioned.

SpotAllocationStrategy -> (string)

Indicates how to allocate instances across Spot Instance pools.

If the allocation strategy is lowest-price , the Auto Scaling group launches instances using the Spot pools with the lowest price, and evenly allocates your instances across the number of Spot pools that you specify. Defaults to lowest-price if not specified.

If the allocation strategy is capacity-optimized (recommended), the Auto Scaling group launches instances using Spot pools that are optimally chosen based on the available Spot capacity. Alternatively, you can use capacity-optimized-prioritized and set the order of instance types in the list of launch template overrides from highest to lowest priority (from first to last in the list). Amazon EC2 Auto Scaling honors the instance type priorities on a best-effort basis but optimizes for capacity first.

SpotInstancePools -> (integer)

The number of Spot Instance pools across which to allocate your Spot Instances. The Spot pools are determined from the different instance types in the overrides. Valid only when the Spot allocation strategy is lowest-price . Value must be in the range of 1 to 20. Defaults to 2 if not specified.

SpotMaxPrice -> (string)

The maximum price per unit hour that you are willing to pay for a Spot Instance. If you leave the value at its default (empty), Amazon EC2 Auto Scaling uses the On-Demand price as the maximum Spot price. To remove a value that you previously set, include the property but specify an empty string ("") for the value.

JSON Syntax:

{
  "LaunchTemplate": {
    "LaunchTemplateId": "string",
    "LaunchTemplateName": "string",
    "Version": "string"
  },
  "MixedInstancesPolicy": {
    "LaunchTemplate": {
      "LaunchTemplateSpecification": {
        "LaunchTemplateId": "string",
        "LaunchTemplateName": "string",
        "Version": "string"
      },
      "Overrides": [
        {
          "InstanceType": "string",
          "WeightedCapacity": "string",
          "LaunchTemplateSpecification": {
            "LaunchTemplateId": "string",
            "LaunchTemplateName": "string",
            "Version": "string"
          }
        }
        ...
      ]
    },
    "InstancesDistribution": {
      "OnDemandAllocationStrategy": "string",
      "OnDemandBaseCapacity": integer,
      "OnDemandPercentageAboveBaseCapacity": integer,
      "SpotAllocationStrategy": "string",
      "SpotInstancePools": integer,
      "SpotMaxPrice": "string"
    }
  }
}

--preferences (structure)

Set of preferences associated with the instance refresh request. If not provided, the default values are used.

MinHealthyPercentage -> (integer)

The amount of capacity in the Auto Scaling group that must remain healthy during an instance refresh to allow the operation to continue. The value is expressed as a percentage of the desired capacity of the Auto Scaling group (rounded up to the nearest integer). The default is 90 .

Setting the minimum healthy percentage to 100 percent limits the rate of replacement to one instance at a time. In contrast, setting it to 0 percent has the effect of replacing all instances at the same time.

InstanceWarmup -> (integer)

The number of seconds until a newly launched instance is configured and ready to use. During this time, Amazon EC2 Auto Scaling does not immediately move on to the next replacement. The default is to use the value for the health check grace period defined for the group.

CheckpointPercentages -> (list)

Threshold values for each checkpoint in ascending order. Each number must be unique. To replace all instances in the Auto Scaling group, the last number in the array must be 100 .

For usage examples, see Adding checkpoints to an instance refresh in the Amazon EC2 Auto Scaling User Guide .

(integer)

CheckpointDelay -> (integer)

The amount of time, in seconds, to wait after a checkpoint before continuing. This property is optional, but if you specify a value for it, you must also specify a value for CheckpointPercentages . If you specify a value for CheckpointPercentages and not for CheckpointDelay , the CheckpointDelay defaults to 3600 (1 hour).

SkipMatching -> (boolean)

A boolean value that indicates whether skip matching is enabled. If true, then 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 configuration that is already set on the group. The default is false .

Shorthand Syntax:

MinHealthyPercentage=integer,InstanceWarmup=integer,CheckpointPercentages=integer,integer,CheckpointDelay=integer,SkipMatching=boolean

JSON Syntax:

{
  "MinHealthyPercentage": integer,
  "InstanceWarmup": integer,
  "CheckpointPercentages": [integer, ...],
  "CheckpointDelay": integer,
  "SkipMatching": true|false
}

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.

Examples

Example 1: To start an instance refresh with command line parameters

The following start-instance-refresh example starts an instance refresh using command line arguments. The optional preferences parameter specifies an InstanceWarmup of 400 seconds and a MinHealthyPercentage of 50 percent.

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

Output:

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

For more information, see Replacing Auto Scaling instances based on an instance refresh in the Amazon EC2 Auto Scaling User Guide.

Example 2: To start an instance refresh using a JSON file

The following start-instance-refresh example starts an instance refresh using a JSON file. You can specify the Auto Scaling group and define your preferences in a JSON file, 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": 400,
        "MinHealthyPercentage": 50
    }
}

Output:

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

For more information, see Replacing Auto Scaling instances based on an instance refresh in the Amazon EC2 Auto Scaling User Guide.

Output

InstanceRefreshId -> (string)

A unique ID for tracking the progress of the request.