AWS CloudFormation
User Guide (API Version 2010-05-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

AWS::AutoScaling::AutoScalingGroup

The AWS::AutoScaling::AutoScalingGroup type creates an Auto Scaling group.

You can add an UpdatePolicy attribute to your Auto Scaling group to control how rolling updates are performed when a change has been made to the Auto Scaling group's launch configuration or subnet group membership.

Syntax

{
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : [ String, ... ],
      "Cooldown" : String,
      "DesiredCapacity" : String,
      "HealthCheckGracePeriod" : Integer,
      "HealthCheckType" : String,
      "InstanceId" : String,
      "LaunchConfigurationName" : String,
      "LoadBalancerNames" : [ String, ... ],
      "MaxSize" : String,
      "MetricsCollection" : [ MetricsCollection, ... ]
      "MinSize" : String,
      "NotificationConfiguration" : NotificationConfiguration,
      "PlacementGroup" : String,
      "Tags" : [ Auto Scaling Tag, ..., ],
      "TerminationPolicies" : [ String, ..., ],
      "VPCZoneIdentifier" : [ String, ... ]
   }
}     

Properties

AvailabilityZones

Contains a list of availability zones for the group.

Required: Yes

Type: A list of strings

Update requires: No interruption

Cooldown

The number of seconds after a scaling activity is completed before any further scaling activities can start.

Required: No

Type: String

Update requires: No interruption

DesiredCapacity

Specifies the desired capacity for the Auto Scaling group.

If SpotPrice is not set in the AWS::AutoScaling::LaunchConfiguration for this Auto Scaling group, then Auto Scaling will begin to bring instances online 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, Auto Scaling uses DesiredCapacity as the target capacity for the group.

Required: No

Type: String

Update requires: No interruption

HealthCheckGracePeriod

The length of time in seconds after a new EC2 instance comes into service that Auto Scaling starts checking its health.

Required: No

Type: Integer

Update requires: No interruption

HealthCheckType

The service you want the health status from, Amazon EC2 or Elastic Load Balancer. Valid values are EC2 or ELB.

Required: No

Type: String

Update requires: No interruption

InstanceId

The ID of the Amazon EC2 instance you want to use to create the Auto Scaling group. Use this property if you want to create an Auto Scaling group that uses an existing Amazon EC2 instance instead of a launch configuration.

When you use an Amazon EC2 instance to create an Auto Scaling group, a new launch configuration is first created and then associated with the Auto Scaling group. The new launch configuration derives all its properties from the instance, with the exception of BlockDeviceMapping and AssociatePublicIpAddress.

Required: Conditional. You must specify this property if you don't specify the LaunchConfigurationName property.

Type: String

Update requires: Replacement

LaunchConfigurationName

Specifies the name of the associated AWS::AutoScaling::LaunchConfiguration.

Note

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. For more information, see DependsOn Attribute.

Required: Conditional; you must specify this property if you don't specify the InstanceId property.

Type: String

Update requires: No interruption

Important

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

LoadBalancerNames

A list of load balancers associated with this Auto Scaling group.

Required: No

Type: A list of strings

Update requires: Replacement

Important

When you update LoadBalancerNames, the entire Auto Scaling group is replaced.

MaxSize

The maximum size of the Auto Scaling group.

Required: Yes

Type: String

Update requires: No interruption

MetricsCollection

Enables the monitoring of group metrics of an Auto Scaling group.

Required: No

Type: A list of Auto Scaling MetricsCollection

Update requires: No interruption

MinSize

The minimum size of the Auto Scaling group.

Required: Yes

Type: String

Update requires: No interruption

NotificationConfiguration

An embedded property that configures an Auto Scaling group to send notifications when specified events take place.

Required: No

Type: 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

Update requires: No interruption

Tags

The tags you want to attach to this resource.

For more information about tags, go to Tagging Auto Scaling Groups and Amazon EC2 Instances in the Auto Scaling Developer Guide.

Required: No

Type: List of Auto Scaling Tags

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.

For more information on configuring a termination policy for your Auto Scaling group, see Instance Termination Policy for Your Auto Scaling Group in the Auto Scaling Developer Guide.

Required: No

Type: A list of strings

Update requires: No interruption

VPCZoneIdentifier

A list of subnet identifiers of Amazon Virtual Private Cloud (Amazon VPCs).

The subnets that you specify for VPCZoneIdentifier must reside in the Availability Zones that you specify with the AvailabilityZones parameter.

For more information, go to Using EC2 Dedicated Instances Within Your VPC in the Auto Scaling Developer Guide.

Required: No

Type: A list of strings

Update requires: Some interruptions

Note

When you update VPCZoneIdentifier, the instances are replaced, but not the Auto Scaling group.

Return Value

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

{ "Ref": "MyASGroup" }

For an Auto Scaling group with the logical ID "MyASGroup", Ref will return:

mystack-myasgroup-NT5EUXTNTXXD

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

Examples

To view more Auto Scaling examples, see Auto Scaling Snippets.

Auto Scaling Group with an Elastic Load Balancing Load Balancer, Launch Configuration, and Metric Collection

"WebServerGroup" : {
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : { "Fn::GetAZs" : "" },
      "LaunchConfigurationName" : { "Ref" : "LaunchConfig" },
      "MinSize" : "2",
      "MaxSize" : "2",
      "LoadBalancerNames" : [ { "Ref" : "ElasticLoadBalancer" } ],
      "MetricsCollection": [
         {
            "Granularity": "1Minute",
            "Metrics": [
               "GroupMinSize",
               "GroupMaxSize"
            ]
         }
      ]
   }
}

Batch Update Instances in an Auto Scaling Group

The following example shows how to configure updates by including an UpdatePolicy attribute. The attribute contains an AutoScalingRollingUpdate embedded object with three attributes that specify the update policy settings.

"ASG1" : {
   "UpdatePolicy" : {
      "AutoScalingRollingUpdate" : {
         "MinInstancesInService" : "1",
         "MaxBatchSize" : "1",
         "PauseTime" : "PT12M5S"
      }
   },
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : { "Fn::GetAZs" : { "Ref" : "AWS::Region" } },
      "LaunchConfigurationName" : { "Ref" : "ASLC" },
      "MaxSize" : "3",
      "MinSize" : "1"
   }
}

Auto Scaling Group Wait on Signals From New Instances

In the following example, the Auto Scaling group waits for new Amazon EC2 instances to signal the group before Auto Scaling proceeds to update the next batch of instances. In the UpdatePolicy attribute, the WaitOnResourceSignals flag is set to true. You can use the cfn-signal helper script on each instance to signal the Auto Scaling group.

"ASG1" : {
   "UpdatePolicy" : {
      "AutoScalingRollingUpdate" : {
         "MinInstancesInService" : "1",
         "MaxBatchSize" : "1",
         "PauseTime" : "PT12M5S",
         "WaitOnResourceSignals" : "true"
      }
   },
   "Type" : "AWS::AutoScaling::AutoScalingGroup",
   "Properties" : {
      "AvailabilityZones" : { "Fn::GetAZs" : { "Ref" : "AWS::Region" } },
      "LaunchConfigurationName" : { "Ref" : "ASLC" },
      "MaxSize" : "3",
      "MinSize" : "1"
   }
}