serviceAutoscaling

Application Auto Scaling in AWS provides automatic scaling for ECS services based on CloudWatch metrics. Stackattack creates auto scaling policies with CloudWatch alarms that can scale services up or down based on custom metrics.

import * as saws from "@stackattack/aws";

const ctx = saws.context();
const vpc = saws.vpc(ctx);
const cluster = saws.cluster(ctx, { network: vpc.network("private") });
const app = saws.service(ctx, {
  name: "my-app",
  image: "nginx:latest",
  network: vpc.network("private"),
  cluster
});

// NOTE: this can also be specified in the service itself via the `autoScaling` argument; the arguments are identical.
saws.serviceAutoScaling(ctx, {
  service: app,
  minReplicas: 1,
  maxReplicas: 10,
  policies: saws.targetTrackingPolicies({
   targetValue: 50,
   metric: 'CPUUtilization',
   namespace: 'AWS/ECS',
})

Usage

After deploying auto scaling, you can monitor and manage it using:

AWS CLI:

# View scaling policies
aws application-autoscaling describe-scaling-policies --service-namespace ecs

# View scaling activities
aws application-autoscaling describe-scaling-activities --service-namespace ecs

# View CloudWatch alarms
aws cloudwatch describe-alarms --alarm-names your-alarm-name

Related Components

Autoscaling work together with other Stackattack components:

• service - The autoscaling component is used to scale services based on Cloudwatch metrics.

Costs

Application Auto Scaling itself is free - you only pay for the underlying resources:

• CloudWatch Alarms - Each alarm costs $0.10/month. Multiple scaling policies create multiple alarms, so costs scale with the number of policies you define.
• ECS Service Scaling - When auto scaling triggers, you pay for additional ECS tasks that are launched. Scaling down reduces costs by terminating tasks.
• CloudWatch Metrics - Custom metrics cost $0.30/metric/month. Built-in AWS metrics like CPU utilization are free.

Cost Optimization:

• Make sure that your scaling policies are set up such that your application will actually scale down when it should. If you set your scaling policies such that low resource usage triggers a “scale up” action, you may find that your resources stay at their maximum capacity indefinitely
• Use built-in metrics (CPU, memory) instead of custom metrics when it makes sense
• Set appropriate min/max replica limits to prevent runaway scaling costs
• Monitor scaling activities to ensure policies aren’t triggering too frequently
• Consider longer evaluation periods to reduce alarm noise and unnecessary scaling

serviceAutoScaling

Creates auto scaling configuration for an ECS service with CloudWatch alarms and scaling policies.

function serviceAutoScaling(ctx: Context, args: ServiceAutoScalingArgs): void

Parameters

• ctx (Context) -
• args (ServiceAutoScalingArgs) -

Returns

• (void) - Creates auto scaling configuration for an ECS service with CloudWatch alarms and scaling policies.

Functions

serviceDimensions

Extracts service and cluster dimensions from an ECS service for CloudWatch metrics.

function serviceDimensions(service: Input<ServiceInput>): Record<string, Input<string>>

Parameters

• service (Input<ServiceInput>) - The ECS service to extract dimensions from

Returns

• (Record<string, Input<string>>) - Extracts service and cluster dimensions from an ECS service for CloudWatch metrics.

targetTrackingPolicies

Creates a pair of scaling policies (up and down) that maintain a target metric value. Uses a multi-step approach with increasing scaling aggressiveness for values further from target.

function targetTrackingPolicies(args: TargetTrackingPoliciesArgs): ServiceAutoScalingPolicy[]

Parameters

• args (TargetTrackingPoliciesArgs) - Configuration for the target tracking policies

Returns

• (ServiceAutoScalingPolicy[]) - Creates a pair of scaling policies (up and down) that maintain a target metric value. Uses a multi-step approach with increasing scaling aggressiveness for values further from target.

Interfaces

AutoScalingPolicyStep

Configuration for a single scaling step within an auto scaling policy.

Properties

• adjustment (Input<number> | "min" | "max") - The scaling adjustment to apply. Use ‘min’ or ‘max’ to scale to capacity limits, or a number for relative/absolute changes. These values should always be positive; the correct directionally will be inferred from the direction of the parent ServiceAutoScalingPolicy
• value (number) - The metric threshold value that triggers this scaling step.

ServiceAutoScalingArgs

Configuration for service auto scaling.

Properties

• maxReplicas (Input<number>) - Maximum number of replicas allowed.
• minReplicas (Input<number>) - Minimum number of replicas to maintain.
• noPrefix? (boolean) - If true, skips adding “autoscaling” prefix to resource names.
• policies (ServiceAutoScalingPolicy[]) - Array of scaling policies that define when and how to scale. You should always specify at least one policy with direction: 'up' and one with direction: 'down'
• service (Input<ServiceInput>) - The ECS service to configure auto scaling for.

ServiceAutoScalingPolicy

Configuration for a single auto scaling policy.

Properties

• adjustmentType ("percent-change" | "change" | "absolute") - Whether to use “change” (relative) or “absolute” (exact capacity) adjustments.
• aggregationType? (Input<string>) - How the metric data is aggregated. Defaults to the same as statistic.
• cooldown? (number) - Cooldown period in seconds between scaling actions. Defaults to 300 seconds
• dimensions? (Record<string, Input<string>>) - Dimensions to filter the metric by (e.g., ServiceName, ClusterName). If not provided, this will default to { ServiceName: <ecs service name>, ClusterName: <ecs cluster name> }, which is the correct value for built-in ECS metrics such as CPUUtilization. To scale on other metrics, you should pass the dimensions explicitly.
• direction ("up" | "down") - Whether this policy scales “up” or “down”.
• evaluationPeriods? (Input<number>) - Number of consecutive periods the condition must be met before triggering. Defaults to 2 evaluation periods
• metric (Input<string>) - CloudWatch metric name (e.g., “CPUUtilization”, “MemoryUtilization”).
• missingDataBehavior? ("ignore" | "missing" | "breaching" | "notBreaching") - How to treat missing data points. Defaults to not specified.
• namespace (Input<string>) - CloudWatch metric namespace (e.g., “AWS/ECS”, “AWS/ApplicationELB”).
• period? (Input<number>) - Period in seconds over which the metric is evaluated. Defaults to 60 seconds
• statistic? (Input<string>) - Statistic to use for the metric. Defaults to “Maximum” for scale-up, “Minimum” for scale-down.
• steps (AutoScalingPolicyStep[]) - Scaling steps that define metric thresholds and corresponding capacity adjustments.

TargetTrackingPoliciesArgs

Arguments for creating target tracking scaling policies. These are meant to mimic the behavior of “target tracking” scaling in ECS, though they still use step-scaling policies under the hood. This is a good way to get auto scaling set up initially, but you will likely want to switch to step scaling policies to achieve optimal scaling behavior.

Properties

• dimensions? (Record<string, Input<string>>) - Optional dimensions to filter the metric. If not passed, these will be filled with serviceDimensions
• metric (Input<string>) - The CloudWatch metric name to track.
• namespace (Input<string>) - The CloudWatch namespace for the metric.
• targetValue (number) - The target value to maintain for the metric.