Menu
Application Auto Scaling
API Reference (API Version 2016-02-06)

RegisterScalableTarget

Registers or updates a scalable target. A scalable target is a resource that Application Auto Scaling can scale out or scale in. After you have registered a scalable target, you can use this operation to update the minimum and maximum values for your scalable dimension.

After you register a scalable target, you can create and apply scaling policies using PutScalingPolicy. You can view the scaling policies for a service namespace using DescribeScalableTargets. If you are no longer using a scalable target, you can deregister it using DeregisterScalableTarget.

Request Syntax

{
   "MaxCapacity": number,
   "MinCapacity": number,
   "ResourceId": "string",
   "RoleARN": "string",
   "ScalableDimension": "string",
   "ServiceNamespace": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

MaxCapacity

The maximum value to scale to in response to a scale out event. This parameter is required if you are registering a scalable target and optional if you are updating one.

Type: Integer

Required: No

MinCapacity

The minimum value to scale to in response to a scale in event. This parameter is required if you are registering a scalable target and optional if you are updating one.

Type: Integer

Required: No

ResourceId

The identifier of the resource associated with the scalable target. This string consists of the resource type and unique identifier.

  • ECS service - The resource type is service and the unique identifier is the cluster name and service name. Example: service/default/sample-webapp.

  • Spot fleet request - The resource type is spot-fleet-request and the unique identifier is the Spot fleet request ID. Example: spot-fleet-request/sfr-73fbd2ce-aa30-494c-8788-1cee4EXAMPLE.

  • EMR cluster - The resource type is instancegroup and the unique identifier is the cluster ID and instance group ID. Example: instancegroup/j-2EEZNYKUA1NTV/ig-1791Y4E1L8YI0.

  • AppStream 2.0 fleet - The resource type is fleet and the unique identifier is the fleet name. Example: fleet/sample-fleet.

  • DynamoDB table - The resource type is table and the unique identifier is the resource ID. Example: table/my-table.

  • DynamoDB global secondary index - The resource type is index and the unique identifier is the resource ID. Example: table/my-table/index/my-table-index.

  • Aurora DB cluster - The resource type is cluster and the unique identifier is the cluster name. Example: cluster:my-db-cluster.

Type: String

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

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

Required: Yes

RoleARN

The ARN of an IAM role that allows Application Auto Scaling to modify the scalable target on your behalf.

With Amazon RDS resources, permissions are granted using a service-linked role. For more information, see Service-Linked Roles for Application Auto Scaling.

For resources that are not supported using a service-linked role, this parameter is required when you register a scalable target and optional when you update one.

Type: String

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

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

Required: No

ScalableDimension

The scalable dimension associated with the scalable target. This string consists of the service namespace, resource type, and scaling property.

  • ecs:service:DesiredCount - The desired task count of an ECS service.

  • ec2:spot-fleet-request:TargetCapacity - The target capacity of a Spot fleet request.

  • elasticmapreduce:instancegroup:InstanceCount - The instance count of an EMR Instance Group.

  • appstream:fleet:DesiredCapacity - The desired capacity of an AppStream 2.0 fleet.

  • dynamodb:table:ReadCapacityUnits - The provisioned read capacity for a DynamoDB table.

  • dynamodb:table:WriteCapacityUnits - The provisioned write capacity for a DynamoDB table.

  • dynamodb:index:ReadCapacityUnits - The provisioned read capacity for a DynamoDB global secondary index.

  • dynamodb:index:WriteCapacityUnits - The provisioned write capacity for a DynamoDB global secondary index.

  • rds:cluster:ReadReplicaCount - The count of Aurora Replicas in an Aurora DB cluster. Available for Aurora MySQL-compatible edition.

Type: String

Valid Values: ecs:service:DesiredCount | ec2:spot-fleet-request:TargetCapacity | elasticmapreduce:instancegroup:InstanceCount | appstream:fleet:DesiredCapacity | dynamodb:table:ReadCapacityUnits | dynamodb:table:WriteCapacityUnits | dynamodb:index:ReadCapacityUnits | dynamodb:index:WriteCapacityUnits | rds:cluster:ReadReplicaCount

Required: Yes

ServiceNamespace

The namespace of the AWS service. For more information, see AWS Service Namespaces in the Amazon Web Services General Reference.

Type: String

Valid Values: ecs | elasticmapreduce | ec2 | appstream | dynamodb | rds

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

ConcurrentUpdateException

Concurrent updates caused an exception, for example, if you request an update to an Application Auto Scaling resource that already has a pending update.

HTTP Status Code: 400

InternalServiceException

The service encountered an internal error.

HTTP Status Code: 400

LimitExceededException

Your account exceeded a limit. This exception is thrown when a per-account resource limit is exceeded. For more information, see Application Auto Scaling Limits.

HTTP Status Code: 400

ValidationException

An exception was thrown for a validation issue. Review the available parameters for the API request.

HTTP Status Code: 400

Example

If you plan to create requests manually, you must replace the Authorization header contents in the examples (AUTHPARAMS) with a signature. For more information, see Signature Version 4 Signing Process in the AWS Gerneral Reference. If you plan to use the AWS CLI or one of the AWS SDKs, these tools sign the requests for you.

Example

The following example registers an Amazon ECS service with Application Auto Scaling.

Sample Request

POST / HTTP/1.1
Host: autoscaling.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 229
X-Amz-Target: AnyScaleFrontendService.RegisterScalableTarget
X-Amz-Date: 20160506T182145Z
User-Agent: aws-cli/1.10.23 Python/2.7.11 Darwin/15.4.0 botocore/1.4.8
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
    "ScalableDimension": "ecs:service:DesiredCount",
    "ResourceId": "service/default/web-app",
    "RoleARN": "arn:aws:iam::012345678910:role/ApplicationAutoscalingECSRole",
    "MinCapacity": 1,
    "ServiceNamespace": "ecs",
    "MaxCapacity": 10
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: