AWS CloudFormation
User Guide (Version )

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

AWS::ApplicationAutoScaling::ScalableTarget

The AWS::ApplicationAutoScaling::ScalableTarget resource specifies a resource that Application Auto Scaling can scale.

For more information, see RegisterScalableTarget in the Application Auto Scaling API Reference.

Syntax

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

JSON

{ "Type" : "AWS::ApplicationAutoScaling::ScalableTarget", "Properties" : { "MaxCapacity" : Integer, "MinCapacity" : Integer, "ResourceId" : String, "RoleARN" : String, "ScalableDimension" : String, "ScheduledActions" : [ ScheduledAction, ... ], "ServiceNamespace" : String, "SuspendedState" : SuspendedState } }

YAML

Type: AWS::ApplicationAutoScaling::ScalableTarget Properties: MaxCapacity: Integer MinCapacity: Integer ResourceId: String RoleARN: String ScalableDimension: String ScheduledActions: - ScheduledAction ServiceNamespace: String SuspendedState: SuspendedState

Properties

MaxCapacity

The maximum value to scale to in response to a scale-out event.

Required: Yes

Type: Integer

Update requires: No interruption

MinCapacity

The minimum value to scale to in response to a scale-in event.

Required: Yes

Type: Integer

Update requires: No interruption

ResourceId

The resource identifier to associate with this scalable target. This string consists of the resource type and unique identifier. For valid values, see the ResourceId parameter for RegisterScalableTarget in the Application Auto Scaling API Reference.

Required: Yes

Type: String

Update requires: Replacement

RoleARN

The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that allows Application Auto Scaling to modify the scalable target on your behalf.

Required: Yes

Type: String

Update requires: No interruption

ScalableDimension

The scalable dimension that is associated with the scalable target. Specify the service namespace, resource type, and scaling property, for example, ecs:service:DesiredCount for the desired task count of an Amazon ECS service. For valid values, see the ScalableDimension parameter for RegisterScalableTarget in the Application Auto Scaling API Reference.

Required: Yes

Type: String

Update requires: Replacement

ScheduledActions

The scheduled actions for the scalable target. Duplicates aren't allowed.

Required: No

Type: List of ScheduledAction

Update requires: No interruption

ServiceNamespace

The namespace of the AWS service that provides the resource or custom-resource for a resource provided by your own application or service. For valid values, see the ServiceNamespace parameter for RegisterScalableTarget in the Application Auto Scaling API Reference.

Required: Yes

Type: String

Update requires: Replacement

SuspendedState

An embedded object that contains attributes and attribute values that are used to suspend and resume automatic scaling. Setting the value of an attribute to true suspends the specified scaling activities. Setting it to false (default) resumes the specified scaling activities.

Suspension Outcomes

  • For DynamicScalingInSuspended, while a suspension is in effect, all scale-in activities that are triggered by a scaling policy are suspended.

  • For DynamicScalingOutSuspended, while a suspension is in effect, all scale-out activities that are triggered by a scaling policy are suspended.

  • For ScheduledScalingSuspended, while a suspension is in effect, all scaling activities that involve scheduled actions are suspended.

For more information, see Suspend and Resume Application Auto Scaling in the Application Auto Scaling User Guide.

Required: No

Type: SuspendedState

Update requires: No interruption

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the AWS CloudFormation-generated ID of the resource. For example: service/ecsStack-MyECSCluster-AB12CDE3F4GH/ecsStack-MyECSService-AB12CDE3F4GH|ecs:service:DesiredCount|ecs.

AWS CloudFormation uses the following format to generate the ID: service/resource_ID|scalable_dimension|service_namespace .

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

Examples

Each scalable target has a resource ID, scalable dimension, and namespace, as well as values for minimum and maximum capacity. For more information, see RegisterScalableTarget in the Application Auto Scaling API Reference.

Register a Scalable Target

The following example creates a scalable target for an AWS::ECS::Service. Application Auto Scaling can scale the number of tasks at a minimum of 1 task and a maximum of 2.

JSON

{ "scalableTarget":{ "Type":"AWS::ApplicationAutoScaling::ScalableTarget", "Properties":{ "MaxCapacity":2, "MinCapacity":1, "ResourceId":"service/ecsStack-MyECSCluster-AB12CDE3F4GH/ecsStack-MyECSService-AB12CDE3F4GH", "RoleARN" : {"Fn::GetAtt" : ["ApplicationAutoScalingRole", "Arn"] }, "ScalableDimension":"ecs:service:DesiredCount", "ServiceNamespace":"ecs" } } }

YAML

scalableTarget: Type: AWS::ApplicationAutoScaling::ScalableTarget Properties: MaxCapacity: 2 MinCapacity: 1 ResourceId: service/ecsStack-MyECSCluster-AB12CDE3F4GH/ecsStack-MyECSService-AB12CDE3F4GH RoleARN: !GetAtt [ ApplicationAutoScalingRole, Arn ] ScalableDimension: ecs:service:DesiredCount ServiceNamespace: ecs

Using Functions to Construct the Resource ID

The following example uses the Fn::Join and Ref intrinsic functions to construct the ResourceId property of the scaling target.

JSON

{ "SpotFleetScalingTarget":{ "Type":"AWS::ApplicationAutoScaling::ScalableTarget", "Properties":{ "MaxCapacity":2, "MinCapacity":1, "ResourceId":{ "Fn::Join":[ "/", [ "spot-fleet-request", { "Ref":"ECSSpotFleet" } ] ] }, "RoleARN":{ "Fn::GetAtt":[ "AutoScalingRole", "Arn" ] }, "ScalableDimension":"ec2:spot-fleet-request:TargetCapacity", "ServiceNamespace":"ec2" } } }

YAML

SpotFleetScalingTarget: Type: AWS::ApplicationAutoScaling::ScalableTarget Properties: MaxCapacity: 2 MinCapacity: 1 ResourceId: !Join - / - - spot-fleet-request - !Ref ECSSpotFleet RoleARN: !GetAtt - AutoScalingRole - Arn ScalableDimension: 'ec2:spot-fleet-request:TargetCapacity' ServiceNamespace: ec2

Application Auto Scaling Scalable Target with an Amazon DynamoDB Table

This example registers an AWS::DynamoDB::Table as a scalable target. It also defines a TargetTrackingScaling scaling policy that scales the WriteCapacityUnits throughput for the table.

JSON

{ "Resources":{ "DDBTable":{ "Type":"AWS::DynamoDB::Table", "Properties":{ "AttributeDefinitions":[ { "AttributeName":"ArtistId", "AttributeType":"S" }, { "AttributeName":"Concert", "AttributeType":"S" }, { "AttributeName":"TicketSales", "AttributeType":"S" } ], "KeySchema":[ { "AttributeName":"ArtistId", "KeyType":"HASH" }, { "AttributeName":"Concert", "KeyType":"RANGE" } ], "GlobalSecondaryIndexes":[ { "IndexName":"GSI", "KeySchema":[ { "AttributeName":"TicketSales", "KeyType":"HASH" } ], "Projection":{ "ProjectionType":"KEYS_ONLY" }, "ProvisionedThroughput":{ "ReadCapacityUnits":5, "WriteCapacityUnits":5 } } ], "ProvisionedThroughput":{ "ReadCapacityUnits":5, "WriteCapacityUnits":5 } } }, "WriteCapacityScalableTarget":{ "Type":"AWS::ApplicationAutoScaling::ScalableTarget", "Properties":{ "MaxCapacity":15, "MinCapacity":5, "ResourceId":{ "Fn::Join":[ "/", [ "table", { "Ref":"DDBTable" } ] ] }, "RoleARN":{ "Fn::GetAtt":[ "ScalingRole", "Arn" ] }, "ScalableDimension":"dynamodb:table:WriteCapacityUnits", "ServiceNamespace":"dynamodb" } }, "ScalingRole":{ "Type":"AWS::IAM::Role", "Properties":{ "AssumeRolePolicyDocument":{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "application-autoscaling.amazonaws.com" ] }, "Action":[ "sts:AssumeRole" ] } ] }, "Path":"/", "Policies":[ { "PolicyName":"root", "PolicyDocument":{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "dynamodb:DescribeTable", "dynamodb:UpdateTable", "cloudwatch:PutMetricAlarm", "cloudwatch:DescribeAlarms", "cloudwatch:GetMetricStatistics", "cloudwatch:SetAlarmState", "cloudwatch:DeleteAlarms" ], "Resource":"*" } ] } } ] } }, "WriteScalingPolicy":{ "Type":"AWS::ApplicationAutoScaling::ScalingPolicy", "Properties":{ "PolicyName":"WriteAutoScalingPolicy", "PolicyType":"TargetTrackingScaling", "ScalingTargetId":{ "Ref":"WriteCapacityScalableTarget" }, "TargetTrackingScalingPolicyConfiguration":{ "TargetValue":50.0, "ScaleInCooldown":60, "ScaleOutCooldown":60, "PredefinedMetricSpecification":{ "PredefinedMetricType":"DynamoDBWriteCapacityUtilization" } } } } } }

YAML

Resources: DDBTable: Type: AWS::DynamoDB::Table Properties: AttributeDefinitions: - AttributeName: "ArtistId" AttributeType: "S" - AttributeName: "Concert" AttributeType: "S" - AttributeName: "TicketSales" AttributeType: "S" KeySchema: - AttributeName: "ArtistId" KeyType: "HASH" - AttributeName: "Concert" KeyType: "RANGE" GlobalSecondaryIndexes: - IndexName: "GSI" KeySchema: - AttributeName: "TicketSales" KeyType: "HASH" Projection: ProjectionType: "KEYS_ONLY" ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 WriteCapacityScalableTarget: Type: AWS::ApplicationAutoScaling::ScalableTarget Properties: MaxCapacity: 15 MinCapacity: 5 ResourceId: !Join - / - - table - !Ref DDBTable RoleARN: !GetAtt ScalingRole.Arn ScalableDimension: dynamodb:table:WriteCapacityUnits ServiceNamespace: dynamodb ScalingRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Principal: Service: - application-autoscaling.amazonaws.com Action: - "sts:AssumeRole" Path: "/" Policies: - PolicyName: "root" PolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Action: - "dynamodb:DescribeTable" - "dynamodb:UpdateTable" - "cloudwatch:PutMetricAlarm" - "cloudwatch:DescribeAlarms" - "cloudwatch:GetMetricStatistics" - "cloudwatch:SetAlarmState" - "cloudwatch:DeleteAlarms" Resource: "*" WriteScalingPolicy: Type: AWS::ApplicationAutoScaling::ScalingPolicy Properties: PolicyName: WriteAutoScalingPolicy PolicyType: TargetTrackingScaling ScalingTargetId: !Ref WriteCapacityScalableTarget TargetTrackingScalingPolicyConfiguration: TargetValue: 50.0 ScaleInCooldown: 60 ScaleOutCooldown: 60 PredefinedMetricSpecification: PredefinedMetricType: DynamoDBWriteCapacityUtilization

Scheduled Actions

The following example creates a ScheduledAction for a scalable target.

JSON

{ "AWSTemplateFormatVersion":"2010-09-09", "Description":"Creating ECS service", "Parameters":{ "AppName":{ "Type":"String", "Description":"Name of app requiring ELB exposure", "Default":"simple-app" }, "AppContainerPort":{ "Type":"Number", "Description":"Container port of app requiring ELB exposure", "Default":"80" }, "AppHostPort":{ "Type":"Number", "Description":"Host port of app requiring ELB exposure", "Default":"80" } }, "Resources":{ "scalableTarget":{ "Type":"AWS::ApplicationAutoScaling::ScalableTarget", "Properties":{ "ResourceId":{ "Fn::Join":[ "/", [ "service", { "Ref":"cluster" }, { "Fn::GetAtt":[ "service", "Name" ] } ] ] }, "ServiceNamespace":"ecs", "ScalableDimension":"ecs:service:DesiredCount", "RoleARN":{ "Fn::GetAtt":[ "scalingRole", "Arn" ] }, "MaxCapacity":"2", "MinCapacity":"1", "ScheduledActions":[ { "EndTime":"2018-12-04T22:14:41.951Z", "ScalableTargetAction":{ "MaxCapacity":"2", "MinCapacity":"1" }, "ScheduledActionName":"First", "StartTime":"2018-11-28T22:14:41.951Z", "Schedule":"cron(0 12 ? * MON *)" } ] } }, "scalingRole":{ "Type":"AWS::IAM::Role", "Properties":{ "AssumeRolePolicyDocument":{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":[ "application-autoscaling.amazonaws.com" ] }, "Action":[ "sts:AssumeRole" ] } ] }, "Path":"/", "Policies":[ { "PolicyName":"root", "PolicyDocument":{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"*", "Resource":"*" } ] } } ] } }, "cluster":{ "Type":"AWS::ECS::Cluster" }, "taskdefinition":{ "Type":"AWS::ECS::TaskDefinition", "Properties":{ "ContainerDefinitions":[ { "Name":{ "Ref":"AppName" }, "MountPoints":[ { "SourceVolume":"my-vol", "ContainerPath":"/var/www/my-vol" } ], "Image":"amazon/amazon-ecs-sample", "Cpu":"10", "PortMappings":[ { "ContainerPort":{ "Ref":"AppContainerPort" }, "HostPort":{ "Ref":"AppHostPort" } } ], "EntryPoint":[ "/usr/sbin/apache2", "-D", "FOREGROUND" ], "Memory":"500", "Essential":"true" }, { "Name":"busybox", "Image":"busybox", "Cpu":"10", "EntryPoint":[ "sh", "-c" ], "Memory":"500", "Command":[ "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\"" ], "Essential":"false", "VolumesFrom":[ { "SourceContainer":{ "Ref":"AppName" } } ] } ], "Volumes":[ { "Host":{ "SourcePath":"/var/lib/docker/vfs/dir/" }, "Name":"my-vol" } ] } }, "service":{ "Type":"AWS::ECS::Service", "Properties":{ "Cluster":{ "Ref":"cluster" }, "DesiredCount":0, "TaskDefinition":{ "Ref":"taskdefinition" } } } }, "Outputs":{ "resourceId":{ "Description":"ResourceId", "Value":{ "Fn::Join":[ "/", [ "service", { "Ref":"cluster" }, { "Fn::GetAtt":[ "service", "Name" ] } ] ] } } } }

YAML

AWSTemplateFormatVersion: 2010-09-09 Description: Creating ECS service Parameters: AppName: Type: String Description: Name of app requiring ELB exposure Default: simple-app AppContainerPort: Type: Number Description: Container port of app requiring ELB exposure Default: '80' AppHostPort: Type: Number Description: Host port of app requiring ELB exposure Default: '80' Resources: scalableTarget: Type: AWS::ApplicationAutoScaling::ScalableTarget Properties: ResourceId: !Join - / - - service - !Ref cluster - !GetAtt service.Name ServiceNamespace: ecs ScalableDimension: 'ecs:service:DesiredCount' RoleARN: !GetAtt - scalingRole - Arn MaxCapacity: '2' MinCapacity: '1' ScheduledActions: - EndTime: '2018-12-04T22:14:41.951Z' ScalableTargetAction: MaxCapacity: '2' MinCapacity: '1' ScheduledActionName: First StartTime: '2018-11-28T22:14:41.951Z' Schedule: 'cron(0 12 ? * MON *)' scalingRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Principal: Service: - application-autoscaling.amazonaws.com Action: - 'sts:AssumeRole' Path: / Policies: - PolicyName: root PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: '*' Resource: '*' cluster: Type: AWS::ECS::Cluster taskdefinition: Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions: - Name: !Ref AppName MountPoints: - SourceVolume: my-vol ContainerPath: /var/www/my-vol Image: amazon/amazon-ecs-sample Cpu: '10' PortMappings: - ContainerPort: !Ref AppContainerPort HostPort: !Ref AppHostPort EntryPoint: - /usr/sbin/apache2 - '-D' - FOREGROUND Memory: '500' Essential: 'true' - Name: busybox Image: busybox Cpu: '10' EntryPoint: - sh - '-c' Memory: '500' Command: - >- /bin/sh -c "while true; do /bin/date > /var/www/my-vol/date; sleep 1; done" Essential: 'false' VolumesFrom: - SourceContainer: !Ref AppName Volumes: - Host: SourcePath: /var/lib/docker/vfs/dir/ Name: my-vol service: Type: AWS::ECS::Service Properties: Cluster: !Ref cluster DesiredCount: 0 TaskDefinition: !Ref taskdefinition Outputs: resourceId: Description: ResourceId Value: !Join - / - - service - !Ref cluster - !GetAtt service.Name

See Also