AWS CDK Application Auto Scaling

1.204.0 · active · verified Thu Apr 16

The `aws-cdk-aws-applicationautoscaling` library provides constructs for defining application auto-scaling policies within the AWS Cloud Development Kit (CDK). It enables users to programmatically configure scalable targets and scaling policies for various AWS services like ECS services, DynamoDB tables, and Aurora clusters. This library is part of the AWS CDK v1, which receives frequent updates and is distinct from the consolidated v2 package.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_applicationautoscaling'
```
cause The `aws-cdk.aws-applicationautoscaling` package is not installed or the import path is incorrect for CDK v1.

fix Run `pip install aws-cdk.aws-applicationautoscaling`. Ensure your import statement is `from aws_cdk import aws_applicationautoscaling as appautoscaling`.
```
AWS CloudFormation Error: Parameter 'ResourceId' must be in the format 'service/<service_name>' for ECS (or similar for other services like 'table/<table_name>' for DynamoDB).
```
cause The `resource_id` provided to `appautoscaling.ScalableTarget` does not conform to the expected format for the specified `service_namespace`.

fix Verify the `resource_id` format based on the `service_namespace`. For ECS, it's typically `service/<cluster-name>/<service-name>`. For DynamoDB, `table/<table-name>` or `table/<table-name>/index/<index-name>`.
```
AttributeError: 'ScalableTarget' object has no attribute 'scale_on_cpu_utilization' (or 'scale_on_metric', etc.)
```
cause This error can occur if you are mixing CDK v1 constructs with v2 API patterns, or vice-versa, or if you're trying to call a method that doesn't exist on the `ScalableTarget` object.

fix Ensure your CDK version (v1) matches the documentation you are following. For v1, methods like `scale_on_cpu_utilization`, `scale_on_request_count`, and `scale_on_metric` are valid directly on the `ScalableTarget` object.

Warnings

breaking This library is for AWS CDK v1. AWS CDK v2 consolidated all construct libraries into a single `aws-cdk` package. Migrating from v1 to v2 requires updating imports and potentially some API changes.
Fix: For new projects, consider using AWS CDK v2 (install `aws-cdk` instead of individual modules). For existing v1 projects, ensure `pip install aws-cdk.aws-applicationautoscaling` is used.
gotcha The `resource_id` and `scalable_dimension` parameters for `ScalableTarget` are highly specific to the AWS service you are scaling. Incorrect formats will lead to CloudFormation deployment failures.
Fix: Consult the AWS documentation for Application Auto Scaling to find the exact `resource_id` and `scalable_dimension` formats for your target service (e.g., ECS, DynamoDB, RDS Aurora, AppStream 2.0).
gotcha Application Auto Scaling requires specific IAM permissions to describe the target resource and its metrics, as well as to update its capacity. Deployment might fail with permission errors if the CDK's execution role or the auto-scaling service-linked role lacks these permissions.
Fix: Ensure the IAM role used by CloudFormation and the implicitly created service-linked role for Application Auto Scaling have adequate permissions (e.g., `ecs:UpdateService`, `dynamodb:UpdateTable`, `cloudwatch:GetMetricData`).

Install

pip install aws-cdk.aws-applicationautoscaling Install v1 library

Imports

ScalableTarget
wrong:
```
from aws_cdk.aws_applicationautoscaling import ScalableTarget
```
correct:
```
from aws_cdk import aws_applicationautoscaling as appautoscaling
```
While direct import works, aliasing to `appautoscaling` is a common and recommended pattern in CDK examples.

Quickstart

This example demonstrates how to define a `ScalableTarget` for an ECS service's desired count and apply a CPU utilization scaling policy. Remember to replace the placeholder `resource_id` with your actual service details and ensure your environment variables `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are set.

import os
from aws_cdk import App, Stack, Duration
from aws_cdk import aws_applicationautoscaling as appautoscaling

class ApplicationAutoScalingStack(Stack):
    def __init__(self, scope: App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Define a scalable target for an ECS service's desired count.
        # In a real application, 'resource_id' would refer to an existing
        # ECS service ARN or logical ID. Adjust 'resource_id' to your target service.
        scalable_target = appautoscaling.ScalableTarget(
            self, "MyEcsScalableTarget",
            service_namespace=appautoscaling.ServiceNamespace.ECS,
            min_capacity=1,
            max_capacity=10,
            # IMPORTANT: Replace with your actual ECS Cluster/Service name
            resource_id="service/YourEcsClusterName/YourEcsServiceName",
            scalable_dimension="ecs:service:DesiredCount"
        )

        # Scale out based on CPU utilization
        scalable_target.scale_on_cpu_utilization(
            "CpuScalingPolicy",
            target_utilization_percent=70,
            scale_in_cooldown=Duration.seconds(60),
            scale_out_cooldown=Duration.seconds(60)
        )

app = App()
ApplicationAutoScalingStack(app, "ApplicationAutoScalingStack",
    env={
        'account': os.environ.get('CDK_DEFAULT_ACCOUNT', '123456789012'),
        'region': os.environ.get('CDK_DEFAULT_REGION', 'us-east-1')
    }
)
app.synth()

view raw JSON →