or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdscalable-targets.mdscheduled-scaling.mdstep-scaling.mdtarget-tracking.md
tile.json

index.mddocs/

AWS Application AutoScaling

AWS Application AutoScaling is a CDK construct library that provides autoscaling for AWS services beyond EC2 instances, including ECS tasks, DynamoDB capacity, Spot Fleet sizes, Lambda provisioned concurrency, and more. It offers three primary scaling approaches: step scaling based on metric thresholds, target tracking scaling to maintain specific utilization, and scheduled scaling for time-based capacity adjustments.

Package Information

  • Package Name: @aws-cdk/aws-applicationautoscaling
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-cdk/aws-applicationautoscaling (CDK v1 - deprecated)

Core Imports

import * as appscaling from '@aws-cdk/aws-applicationautoscaling';
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
import * as iam from '@aws-cdk/aws-iam';

For specific imports:

import { 
  ScalableTarget, 
  ServiceNamespace, 
  Schedule,
  PredefinedMetric,
  AdjustmentType,
  MetricAggregationType,
  BaseScalableAttribute,
  StepScalingPolicy,
  TargetTrackingScalingPolicy,
  StepScalingAction
} from '@aws-cdk/aws-applicationautoscaling';

Basic Usage

import * as appscaling from '@aws-cdk/aws-applicationautoscaling';
import * as iam from '@aws-cdk/aws-iam';
import { Construct } from 'constructs';

// Create a scalable target for Lambda provisioned concurrency
const target = new appscaling.ScalableTarget(this, 'ScalableTarget', {
  serviceNamespace: appscaling.ServiceNamespace.LAMBDA,
  maxCapacity: 100,
  minCapacity: 10,
  resourceId: `function:${functionName}:${version}`,
  scalableDimension: 'lambda:function:ProvisionedConcurrency',
});

// Add target tracking scaling
target.scaleToTrackMetric('PceTracking', {
  targetValue: 0.9,
  predefinedMetric: appscaling.PredefinedMetric.LAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION,
});

Architecture

The library is built around several key components:

  • ScalableTarget: Central component that defines what resource to scale and capacity limits
  • BaseScalableAttribute: Abstract base class for service-specific scalable attributes
  • Scaling Policies: Step scaling and target tracking policies that define scaling behavior
  • Schedule: Time-based scaling with cron, rate, and at expressions
  • Service Integration: Extensible design allowing other CDK libraries to provide service-specific scaling

Capabilities

Scalable Targets

Core functionality for defining scalable resources with capacity limits and IAM roles.

class ScalableTarget extends Resource implements IScalableTarget {
  constructor(scope: Construct, id: string, props: ScalableTargetProps);
  static fromScalableTargetId(scope: Construct, id: string, scalableTargetId: string): IScalableTarget;
  
  readonly scalableTargetId: string;
  readonly role: iam.IRole;
  
  addToRolePolicy(statement: iam.PolicyStatement): void;
  scaleOnSchedule(id: string, action: ScalingSchedule): void;
  scaleOnMetric(id: string, props: BasicStepScalingPolicyProps): StepScalingPolicy;
  scaleToTrackMetric(id: string, props: BasicTargetTrackingScalingPolicyProps): TargetTrackingScalingPolicy;
}

interface ScalableTargetProps {
  readonly minCapacity: number;
  readonly maxCapacity: number;
  readonly role?: iam.IRole;
  readonly resourceId: string;
  readonly scalableDimension: string;
  readonly serviceNamespace: ServiceNamespace;
}

Scalable Targets

Step Scaling

Scaling based on metric thresholds with configurable scaling steps and adjustment types.

class StepScalingPolicy extends Construct {
  constructor(scope: Construct, id: string, props: StepScalingPolicyProps);
  
  readonly lowerAlarm?: cloudwatch.Alarm;
  readonly lowerAction?: StepScalingAction;
  readonly upperAlarm?: cloudwatch.Alarm;
  readonly upperAction?: StepScalingAction;
}

interface BasicStepScalingPolicyProps {
  readonly metric: cloudwatch.IMetric;
  readonly scalingSteps: ScalingInterval[];
  readonly adjustmentType?: AdjustmentType;
  readonly cooldown?: cdk.Duration;
  readonly minAdjustmentMagnitude?: number;
  readonly evaluationPeriods?: number;
  readonly datapointsToAlarm?: number;
  readonly metricAggregationType?: MetricAggregationType;
}

Step Scaling

Target Tracking Scaling

Automatic scaling to maintain a target metric value with built-in and custom metrics support.

class TargetTrackingScalingPolicy extends Construct {
  constructor(scope: Construct, id: string, props: TargetTrackingScalingPolicyProps);
  
  readonly scalingPolicyArn: string;
}

interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackingProps {
  readonly targetValue: number;
  readonly predefinedMetric?: PredefinedMetric;
  readonly resourceLabel?: string;
  readonly customMetric?: cloudwatch.IMetric;
}

interface BaseTargetTrackingProps {
  readonly policyName?: string;
  readonly disableScaleIn?: boolean;
  readonly scaleInCooldown?: Duration;
  readonly scaleOutCooldown?: Duration;
}

Target Tracking Scaling

Scheduled Scaling

Time-based scaling with cron expressions, rate schedules, and one-time scaling events.

abstract class Schedule {
  static expression(expression: string): Schedule;
  static rate(duration: Duration): Schedule;
  static at(moment: Date): Schedule;
  static cron(options: CronOptions): Schedule;
  
  abstract readonly expressionString: string;
}

interface ScalingSchedule {
  readonly schedule: Schedule;
  readonly startTime?: Date;
  readonly endTime?: Date;
  readonly minCapacity?: number;
  readonly maxCapacity?: number;
}

Scheduled Scaling

Base Scalable Attribute

Abstract base class for service-specific scalable attributes, providing a protected interface around ScalableTarget.

abstract class BaseScalableAttribute extends Construct {
  constructor(scope: Construct, id: string, props: BaseScalableAttributeProps);
  
  protected doScaleOnSchedule(id: string, props: ScalingSchedule): void;
  protected doScaleOnMetric(id: string, props: BasicStepScalingPolicyProps): void;
  protected doScaleToTrackMetric(id: string, props: BasicTargetTrackingScalingPolicyProps): void;
}

Step Scaling Action

Low-level construct for step scaling actions that can be used with CloudWatch alarms.

class StepScalingAction extends Construct {
  constructor(scope: Construct, id: string, props: StepScalingActionProps);
  
  readonly scalingPolicyArn: string;
  
  addAdjustment(adjustment: AdjustmentTier): void;
}

interface StepScalingActionProps {
  readonly scalingTarget: IScalableTarget;
  readonly policyName?: string;
  readonly adjustmentType?: AdjustmentType;
  readonly cooldown?: Duration;
  readonly minAdjustmentMagnitude?: number;
  readonly metricAggregationType?: MetricAggregationType;
}

Common Types

enum ServiceNamespace {
  ECS = 'ecs',
  ELASTIC_MAP_REDUCE = 'elasticmapreduce',
  EC2 = 'ec2',
  APPSTREAM = 'appstream',
  DYNAMODB = 'dynamodb',
  RDS = 'rds',
  SAGEMAKER = 'sagemaker',
  CUSTOM_RESOURCE = 'custom-resource',
  LAMBDA = 'lambda',
  COMPREHEND = 'comprehend',
  KAFKA = 'kafka',
  ELASTICACHE = 'elasticache',
}

enum AdjustmentType {
  CHANGE_IN_CAPACITY = 'ChangeInCapacity',
  PERCENT_CHANGE_IN_CAPACITY = 'PercentChangeInCapacity',
  EXACT_CAPACITY = 'ExactCapacity',
}

enum MetricAggregationType {
  AVERAGE = 'Average',
  MINIMUM = 'Minimum',
  MAXIMUM = 'Maximum'
}

enum PredefinedMetric {
  APPSTREAM_AVERAGE_CAPACITY_UTILIZATION = 'AppStreamAverageCapacityUtilization',
  CASSANDRA_READ_CAPACITY_UTILIZATION = 'CassandraReadCapacityUtilization',
  CASSANDRA_WRITE_CAPACITY_UTILIZATION = 'CassandraWriteCapacityUtilization',
  COMPREHEND_INFERENCE_UTILIZATION = 'ComprehendInferenceUtilization',
  NEPTURE_READER_AVERAGE_CPU_UTILIZATION = 'NeptuneReaderAverageCPUUtilization',
  DYNAMODB_READ_CAPACITY_UTILIZATION = 'DynamoDBReadCapacityUtilization',
  DYNAMODB_WRITE_CAPACITY_UTILIZATION = 'DynamoDBWriteCapacityUtilization',
  /** @deprecated use DYNAMODB_WRITE_CAPACITY_UTILIZATION */
  DYANMODB_WRITE_CAPACITY_UTILIZATION = 'DynamoDBWriteCapacityUtilization',
  ALB_REQUEST_COUNT_PER_TARGET = 'ALBRequestCountPerTarget',
  RDS_READER_AVERAGE_CPU_UTILIZATION = 'RDSReaderAverageCPUUtilization',
  RDS_READER_AVERAGE_DATABASE_CONNECTIONS = 'RDSReaderAverageDatabaseConnections',
  EC2_SPOT_FLEET_REQUEST_AVERAGE_CPU_UTILIZATION = 'EC2SpotFleetRequestAverageCPUUtilization',
  EC2_SPOT_FLEET_REQUEST_AVERAGE_NETWORK_IN = 'EC2SpotFleetRequestAverageNetworkIn',
  EC2_SPOT_FLEET_REQUEST_AVERAGE_NETWORK_OUT = 'EC2SpotFleetRequestAverageNetworkOut',
  SAGEMAKER_VARIANT_INVOCATIONS_PER_INSTANCE = 'SageMakerVariantInvocationsPerInstance',
  ECS_SERVICE_AVERAGE_CPU_UTILIZATION = 'ECSServiceAverageCPUUtilization',
  ECS_SERVICE_AVERAGE_MEMORY_UTILIZATION = 'ECSServiceAverageMemoryUtilization',
  LAMBDA_PROVISIONED_CONCURRENCY_UTILIZATION = 'LambdaProvisionedConcurrencyUtilization',
  KAFKA_BROKER_STORAGE_UTILIZATION = 'KafkaBrokerStorageUtilization',
  ELASTICACHE_PRIMARY_ENGINE_CPU_UTILIZATION = 'ElastiCachePrimaryEngineCPUUtilization',
  ELASTICACHE_REPLICA_ENGINE_CPU_UTILIZATION = 'ElastiCacheReplicaEngineCPUUtilization',
  ELASTICACHE_DATABASE_MEMORY_USAGE_COUNTED_FOR_EVICT_PERCENTAGE = 'ElastiCacheDatabaseMemoryUsageCountedForEvictPercentage',
}

interface IScalableTarget extends IResource {
  readonly scalableTargetId: string;
}

interface BaseScalableAttributeProps extends EnableScalingProps {
  readonly serviceNamespace: ServiceNamespace;
  readonly resourceId: string;
  readonly dimension: string;
  readonly role: iam.IRole;
}

interface EnableScalingProps {
  readonly minCapacity?: number;
  readonly maxCapacity: number;
}

interface ScalingInterval {
  readonly lower?: number;
  readonly upper?: number;
  readonly change: number;
}

interface AdjustmentTier {
  readonly adjustment: number;
  readonly lowerBound?: number;
  readonly upperBound?: number;
}

interface CronOptions {
  readonly minute?: string;
  readonly hour?: string;
  readonly day?: string;
  readonly month?: string;
  readonly year?: string;
  readonly weekDay?: string;
}

CloudFormation Resources

The package also exports low-level CloudFormation resources that are generated at build time from the AWS CloudFormation resource specifications. These are typically used internally by the higher-level constructs and rarely needed for direct use:

  • CfnScalableTarget - AWS::ApplicationAutoScaling::ScalableTarget
  • CfnScalingPolicy - AWS::ApplicationAutoScaling::ScalingPolicy

Import these if needed with:

import { CfnScalableTarget, CfnScalingPolicy } from '@aws-cdk/aws-applicationautoscaling';