AWS CloudFormation
User Guide (Version )

AWS::AutoScaling::AutoScalingGroup

Defines an Amazon EC2 Auto Scaling group with the specified name and attributes.

To configure Amazon EC2 instances launched as part of the group, you can specify a launch template or a launch configuration. We recommend that you use a launch template to make sure that you can use the latest features of Amazon EC2, such as T2 Unlimited instances. For more information, see Creating a Launch Template for an Auto Scaling Group.

Important

You can add an UpdatePolicy attribute to your Auto Scaling group to perform rolling updates (or replace the group) when a change has been made to the group. You can find sample update policies for rolling updates in the Examples section.

For more information, see CreateAutoScalingGroup and UpdateAutoScalingGroup in the Amazon EC2 Auto Scaling API Reference. For more information about Amazon EC2 Auto Scaling, see the Amazon EC2 Auto Scaling User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::AutoScaling::AutoScalingGroup", "Properties" : { "AutoScalingGroupName" : String, "AvailabilityZones" : [ String, ... ], "Cooldown" : String, "DesiredCapacity" : String, "HealthCheckGracePeriod" : Integer, "HealthCheckType" : String, "InstanceId" : String, "LaunchConfigurationName" : String, "LaunchTemplate" : LaunchTemplateSpecification, "LifecycleHookSpecificationList" : [ LifecycleHookSpecification, ... ], "LoadBalancerNames" : [ String, ... ], "MaxSize" : String, "MetricsCollection" : [ MetricsCollection, ... ], "MinSize" : String, "MixedInstancesPolicy" : MixedInstancesPolicy, "NotificationConfigurations" : [ NotificationConfiguration, ... ], "PlacementGroup" : String, "ServiceLinkedRoleARN" : String, "Tags" : [ TagProperty, ... ], "TargetGroupARNs" : [ String, ... ], "TerminationPolicies" : [ String, ... ], "VPCZoneIdentifier" : [ String, ... ] } }

Properties

AutoScalingGroupName

The name of the Auto Scaling group. This name must be unique per Region per account.

Required: No

Type: String

Minimum: 1

Maximum: 255

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: Replacement

AvailabilityZones

A list of Availability Zones for the group. You must specify one of the following properties: VPCZoneIdentifier or AvailabilityZones.

If your account supports EC2-Classic and VPC, this property is required to launch instances into EC2-Classic.

Required: Conditional

Type: List of String

Update requires: No interruption

Cooldown

The amount of time, in seconds, after a scaling activity completes before another scaling activity can start. The default value is 300.

Used only when a scaling-specific cooldown is not specified and not supported for target tracking scaling policies, step scaling policies, or scheduled scaling. For more information, see Scaling Cooldowns in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: String

Update requires: No interruption

DesiredCapacity

The number of Amazon EC2 instances that the Auto Scaling group attempts to maintain. The number must be greater than or equal to the minimum size of the group and less than or equal to the maximum size of the group. If you do not specify a desired capacity, the default is the minimum size of the group.

If SpotPrice is not set in the LaunchConfiguration for the Auto Scaling group, then Amazon EC2 Auto Scaling will begin to launch instances based on DesiredCapacity. CloudFormation will not mark the Auto Scaling group as successful (by setting its status to CREATE_COMPLETE) until the desired capacity is reached.

If SpotPrice is set, then DesiredCapacity will not be used as a criteria for success, since instances will only be started when the Spot price has been matched. After the Spot price has been matched, however, Amazon EC2 Auto Scaling uses DesiredCapacity as the target capacity for the group.

Required: No

Type: String

Update requires: No interruption

HealthCheckGracePeriod

The amount of time, in seconds, that Amazon EC2 Auto Scaling waits before checking the health status of an EC2 instance that has come into service.

For more information, see Health Checks for Auto Scaling Instances in the Amazon EC2 Auto Scaling User Guide.

If you are adding an ELB health check, you must specify this property.

Required: Conditional

Type: Integer

Update requires: No interruption

HealthCheckType

The service to use for the health checks. The valid values are EC2 (default) and ELB. If you configure an Auto Scaling group to use ELB health checks, it considers the instance unhealthy if it fails either the EC2 status checks or the load balancer health checks.

For more information, see Health Checks for Auto Scaling Instances in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: String

Minimum: 1

Maximum: 32

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

InstanceId

The ID of the instance used to create a launch configuration for the group.

When you specify an ID of an instance, Amazon EC2 Auto Scaling creates a new launch configuration and associates it with the Auto Scaling group. The new launch configuration derives all its properties from the instance, with the exception of BlockDeviceMapping and AssociatePublicIpAddress.

For more information, see Create an Auto Scaling Group Using an EC2 Instance in the Amazon EC2 Auto Scaling User Guide.

When you create an Auto Scaling group, you must specify one of the following properties in your request: LaunchConfigurationName, LaunchTemplate, InstanceId, or MixedInstancesPolicy.

Required: Conditional

Type: String

Update requires: Replacement

LaunchConfigurationName

The name of the LaunchConfiguration to use to launch instances.

If this resource has a public IP address and is also in a VPC that is defined in the same template, you must use the DependsOn attribute to declare a dependency on the VPC-gateway attachment.

When you create an Auto Scaling group, you must specify one of the following properties in your request: LaunchConfigurationName, LaunchTemplate, InstanceId, or MixedInstancesPolicy.

Note

When you update LaunchConfigurationName, existing Amazon EC2 instances continue to run with the configuration that they were originally launched with. To update existing instances, specify an UpdatePolicy attribute for the Auto Scaling group.

Required: Conditional

Type: String

Minimum: 1

Maximum: 255

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

LaunchTemplate

The LaunchTemplate to use to launch instances.

When you create an Auto Scaling group, you must specify one of the following properties in your request: LaunchConfigurationName, LaunchTemplate, InstanceId, or MixedInstancesPolicy.

Note

When you update LaunchTemplate, existing Amazon EC2 instances continue to run with the configuration that they were originally launched with. To update existing instances, specify an UpdatePolicy attribute for the Auto Scaling group.

Required: Conditional

Type: LaunchTemplateSpecification

Update requires: No interruption

LifecycleHookSpecificationList

The lifecycle hooks for the group, which specify actions to perform when Amazon EC2 Auto Scaling launches or terminates instances.

Required: No

Type: List of LifecycleHookSpecification

Update requires: No interruption

LoadBalancerNames

A list of Classic Load Balancers associated with this Auto Scaling group. For Application Load Balancers and Network Load Balancers, specify a list of target groups using the TargetGroupARNs property instead.

For more information, see Using a Load Balancer with an Auto Scaling Group in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of String

Update requires: No interruption

MaxSize

The maximum number of Amazon EC2 instances in the Auto Scaling group.

Required: Yes

Type: String

Update requires: No interruption

MetricsCollection

Enables the monitoring of group metrics of an Auto Scaling group. By default, these metrics are disabled.

Required: No

Type: List of MetricsCollection

Update requires: No interruption

MinSize

The minimum number of Amazon EC2 instances in the Auto Scaling group.

Required: Yes

Type: String

Update requires: No interruption

MixedInstancesPolicy

An embedded object that specifies a mixed instances policy.

The policy includes properties that not only define the distribution of On-Demand Instances and Spot Instances, the maximum price to pay for Spot instances, and how the Auto Scaling group allocates instance types to fulfill On-Demand and Spot capacity, but also the properties that specify the instance configuration information—the launch template and instance types.

For more information, see Auto Scaling Groups with Multiple Instance Types and Purchase Options in the Amazon EC2 Auto Scaling User Guide.

When you create an Auto Scaling group, you must specify one of the following properties in your request: LaunchConfigurationName, LaunchTemplate, InstanceId, or MixedInstancesPolicy.

Required: Conditional

Type: MixedInstancesPolicy

Update requires: No interruption

NotificationConfigurations

Configures an Auto Scaling group to send notifications when specified events take place.

Required: No

Type: List of NotificationConfiguration

Update requires: No interruption

PlacementGroup

The name of an existing cluster placement group into which you want to launch your instances. A placement group is a logical grouping of instances within a single Availability Zone. You cannot specify multiple Availability Zones and a placement group.

Required: No

Type: String

Minimum: 1

Maximum: 255

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

ServiceLinkedRoleARN

The Amazon Resource Name (ARN) of the service-linked role that the Auto Scaling group uses to call other AWS services on your behalf. By default, Amazon EC2 Auto Scaling uses a service-linked role named AWSServiceRoleForAutoScaling, which it creates if it does not exist.

Required: No

Type: String

Minimum: 1

Maximum: 1600

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

Tags

The tags for the group.

Required: No

Type: List of TagProperty

Update requires: No interruption

TargetGroupARNs

A list of Amazon Resource Names (ARN) of target groups to associate with the Auto Scaling group. Instances are registered as targets in a target group, and traffic is routed to the target group.

For more information, see Using a Load Balancer with an Auto Scaling Group in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of String

Update requires: No interruption

TerminationPolicies

A policy or a list of policies that are used to select the instances to terminate. The policies are executed in the order that you list them. The termination policies supported by Amazon EC2 Auto Scaling: OldestInstance, OldestLaunchConfiguration, NewestInstance, ClosestToNextInstanceHour, Default, OldestLaunchTemplate, and AllocationStrategy.

For more information, see Controlling Which Auto Scaling Instances Terminate During Scale In in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of String

Update requires: No interruption

VPCZoneIdentifier

A list of subnet IDs for a virtual private cloud (VPC). You must specify one of the following properties: VPCZoneIdentifier or AvailabilityZones. If you specify VPCZoneIdentifier with AvailabilityZones, the subnets that you specify for this property must reside in those Availability Zones.

If your account supports EC2-Classic and VPC, this property is required to launch instances into a VPC.

Note

When you update VPCZoneIdentifier, this retains the same Auto Scaling group and replaces old instances with new ones, according to the specified subnets. You can specify how AWS CloudFormation handles these updates by using an UpdatePolicy attribute.

Required: Conditional

Type: List of String

Minimum: 1

Maximum: 2047

Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Update requires: No interruption

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the resource name. For example: mystack-myasgroup-NT5EUXTNTXXD.

For more information about using the Ref function, see Ref.

Examples

The following examples create or make changes to an Auto Scaling group. To view more examples, see Auto Scaling Template Snippets.

Auto Scaling Group with Load Balancer and Multiple Properties

The following example attaches an Elastic Load Balancing load balancer to an Auto Scaling group named myASGroup. It enables two group metrics using the MetricsCollection property and creates tags using the Tags property. The first tag, Environment=Production, is assigned to the Auto Scaling group and to any EC2 instances launched as part of the Auto Scaling group. The second tag, Purpose=WebServerGroup, is assigned only to the Auto Scaling group itself.

It also specifies the launch configuration that the Auto Scaling group uses to launch EC2 instances. The AvailabilityZones property specifies the Availability Zones where the Auto Scaling group's instances will be created. The Fn::GetAZs function call { "Fn::GetAZs" : "" } specifies all Availability Zones for the region in which the stack is created. Amazon EC2 Auto Scaling can scale the number of instances in the group at a minimum of 1 instance and a maximum of 4 based on the values for MinSize and MaxSize.

JSON

{ "myASGroup":{ "Type":"AWS::AutoScaling::AutoScalingGroup", "Properties":{ "AvailabilityZones":{ "Fn::GetAZs":"" }, "LaunchConfigurationName":{ "Ref":"myLaunchConfig" }, "MinSize":"1", "MaxSize":"4", "LoadBalancerNames":[ { "Ref":"myLoadBalancer" } ], "MetricsCollection":[ { "Granularity":"1Minute", "Metrics":[ "GroupMinSize", "GroupMaxSize" ] } ], "Tags":[ { "Key":"Environment", "Value":"Production", "PropagateAtLaunch":"true" }, { "Key":"Purpose", "Value":"WebServerGroup", "PropagateAtLaunch":"false" } ] } } }

YAML

myASGroup: Type: AWS::AutoScaling::AutoScalingGroup Properties: AvailabilityZones: Fn::GetAZs: "" LaunchConfigurationName: Ref: "myLaunchConfig" MinSize: "1" MaxSize: "4" LoadBalancerNames: - Ref: "myLoadBalancer" MetricsCollection: - Granularity: "1Minute" Metrics: - "GroupMinSize" - "GroupMaxSize" Tags: - Key: Environment Value: Production PropagateAtLaunch: "true" - Key: Purpose Value: WebServerGroup PropagateAtLaunch: "false"

Rolling Updates with Batch Update Policy

The following example specifies an UpdatePolicy attribute for an Auto Scaling group and configures it to use the AutoScalingRollingUpdate policy with attributes that define the update policy settings.

The sample update policy instructs CloudFormation to perform a rolling update. The rolling update makes changes to the Auto Scaling group in small batches (for this example, instance by instance) based on the MaxBatchSize and a pause time between batches of updates based on the PauseTime. The MinInstancesInService specifies the minimum number of instances that must be in service within the Auto Scaling group while CloudFormation updates old instances.

While the stack update is in progress, the following Auto Scaling processes are suspended: HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, and ScheduledActions. Note: Do not suspend the Launch, Terminate, or AddToLoadBalancer (if the Auto Scaling group is being used with Elastic Load Balancing) process types because it can prevent the rolling update from functioning properly.

JSON

{ "myASGroup":{ "UpdatePolicy":{ "AutoScalingRollingUpdate":{ "MinInstancesInService":"1", "MaxBatchSize":"1", "PauseTime":"PT12M5S", "SuspendProcesses":[ "HealthCheck", "ReplaceUnhealthy", "AZRebalance", "AlarmNotification", "ScheduledActions" ] } }, "Type":"AWS::AutoScaling::AutoScalingGroup", "Properties":{ "AvailabilityZones":{ "Fn::GetAZs":{ "Ref":"AWS::Region" } }, "LaunchConfigurationName":{ "Ref":"myLaunchConfig" }, "MaxSize":"3", "MinSize":"1" } } }

YAML

myASGroup: UpdatePolicy: AutoScalingRollingUpdate: MinInstancesInService: "1" MaxBatchSize: "1" PauseTime: "PT12M5S" SuspendProcesses: - HealthCheck - ReplaceUnhealthy - AZRebalance - AlarmNotification - ScheduledActions Type: AWS::AutoScaling::AutoScalingGroup Properties: AvailabilityZones: Fn::GetAZs: Ref: "AWS::Region" LaunchConfigurationName: Ref: "myLaunchConfig" MaxSize: "3" MinSize: "1"

Batch Update Policy with Wait Condition

The following example demonstrates a batch update policy that instructs CloudFormation to wait for new instances to signal the Auto Scaling group before the group proceeds to update the next batch of instances. In the UpdatePolicy attribute, the WaitOnResourceSignals attribute is set to true. AWS CloudFormation must receive a signal from each new instance within the specified PauseTime before continuing the update. To signal the Auto Scaling group, a cfn-signal helper script (not shown) is run on each instance.

JSON

{ "myASGroup":{ "UpdatePolicy":{ "AutoScalingRollingUpdate":{ "MinInstancesInService":"1", "MaxBatchSize":"1", "PauseTime":"PT15M", "WaitOnResourceSignals":"true", "SuspendProcesses":[ "HealthCheck", "ReplaceUnhealthy", "AZRebalance", "AlarmNotification", "ScheduledActions" ] } }, "Type":"AWS::AutoScaling::AutoScalingGroup", "Properties":{ "AvailabilityZones":{ "Fn::GetAZs":{ "Ref":"AWS::Region" } }, "LaunchConfigurationName":{ "Ref":"myLaunchConfig" }, "MaxSize":"3", "MinSize":"1" } } }

YAML

myASGroup: UpdatePolicy: AutoScalingRollingUpdate: MinInstancesInService: "1" MaxBatchSize: "1" PauseTime: "PT15M" WaitOnResourceSignals: "true" SuspendProcesses: - HealthCheck - ReplaceUnhealthy - AZRebalance - AlarmNotification - ScheduledActions Type: AWS::AutoScaling::AutoScalingGroup Properties: AvailabilityZones: Fn::GetAZs: Ref: "AWS::Region" LaunchConfigurationName: Ref: "myLaunchConfig" MaxSize: "3" MinSize: "1"

See Also