Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » Auto Scaling Resource Types Reference » AWS::AutoScaling::AutoScalingGroup

AWS::AutoScaling::AutoScalingGroup

Creates an Amazon EC2 Auto Scaling group.

You can add an UpdatePolicy Attribute 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

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.

Minimum length of 1. Maximum length of 255. Must follow the following pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\r\n\t]*

Required: No

Type: String

Update requires: Replacement

AvailabilityZones

Contains a list of availability zones for the group.

Required: Conditional. If you don't specify the VPCZoneIdentifier property, you must specify this property.

Type: List of String values

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, Amazon EC2 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 Amazon EC2 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 one of the following: InstanceId, LaunchConfigurationName, LaunchTemplate, or MixedInstancesPolicy.

Type: String

Update requires: Replacement

LaunchConfigurationName

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

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 one of the following: InstanceId, LaunchConfigurationName, LaunchTemplate, or MixedInstancesPolicy.

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 Attribute.

LaunchTemplate

The launch template to use to launch instances.

Required: Conditional. You must specify one of the following: InstanceId, LaunchConfigurationName, LaunchTemplate, or MixedInstancesPolicy.

Type: LaunchTemplateSpecification

Update requires: No interruption

Important

When you update the LaunchTemplate, 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 Attribute.

LifecycleHookSpecificationList

The lifecycle hooks for the group, which specify actions to perform when Amazon EC2 Auto Scaling launches or terminates instances. For more information, see Amazon EC2 Auto Scaling Lifecycle Hooks in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of LifecycleHookSpecification

Update requires: No interruption

LoadBalancerNames

A list of Classic load balancers associated with this Auto Scaling group. To specify Application Load Balancers, use TargetGroupARNs.

Required: No

Type: List of String values

Update requires: No interruption

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 Amazon EC2 Auto Scaling AutoScalingGroup MetricsCollection

Update requires: No interruption

MinSize

The minimum size of the Auto Scaling group.

Required: Yes

Type: String

Update requires: No interruption

MixedInstancesPolicy

The mixed instances policy to use to launch instances.

Required: Conditional. You must specify one of the following: InstanceId, LaunchConfigurationName, LaunchTemplate, or MixedInstancesPolicy.

Type: MixedInstancesPolicy

Update requires: No interruption

NotificationConfigurations

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

Required: No

Type: List of Amazon EC2 Auto Scaling AutoScalingGroup 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

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, Auto Scaling uses a service-linked role named AWSServiceRoleForAutoScaling, which it creates if it does not exist.

Length Constraints: Minimum length of 1. Maximum length of 1600.

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

Required: No

Type: String

Update requires: No interruption

Tags

The tags to attach to this resource. For more information, see Tagging Auto Scaling Groups and Instances in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of Amazon EC2 Auto Scaling AutoScalingGroup TagProperty

Update requires: No interruption

TargetGroupARNs

A list of Amazon Resource Names (ARN) of target groups to associate with the Auto Scaling group.

Required: No

Type: List of String values

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 Controlling Which Auto Scaling Instances Terminate During Scale In in the Amazon EC2 Auto Scaling User Guide.

Required: No

Type: List of String values

Update requires: No interruption

VPCZoneIdentifier

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

If you specify the AvailabilityZones property, the subnets that you specify for this property must reside in those Availability Zones.

For more information, see Launching Auto Scaling Instances in a VPC in the Amazon EC2 Auto Scaling User Guide.

Required: Conditional. If you don't specify the AvailabilityZones property, you must specify this property.

Type: List of String values

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, Ref returns the resource name.

In the following sample, the Ref function returns the name of the MyASGroup Auto Scaling group, such as mystack-myasgroup-NT5EUXTNTXXD. 

{ "Ref": "MyASGroup" }

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

Examples

To view more examples, see Auto Scaling Template Snippets.

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

JSON

"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"
            ]
         }
      ]
   }
}

YAML

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 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 Amazon EC2 Auto Scaling proceeds to update the next batch of instances. In the UpdatePolicy Attribute 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.

JSON

"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"
   }
}

YAML

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"

See Also