Module classic/autoscaling

Pulumi Autoscaling Components

AutoScalingGroups (ASGs) allow you to allocate a set of EC2 instances on which to run code (like ECS Services) for a Cluster. Groups can define hard constraints in terms of the minimum, maximum and desired number of instances that should be running. They can also specify Scaling Schedules that control changing these desired values (for example, to scale up on certain days with high expected load), as well as specifying Scaling Policies that will adjust how the group scales in response to events happening in the system.

Creating an AutoScalingGroup

AutoScalingGroups are created for a corresponding awsx.ecs.Cluster. This can be done by either manually creating a cluster, or using Cluster.getDefault() to get to the default cluster for the default VPC for the account. The simplest way to create a AutoScalingGroup is to just do:

const cluster = new awsx.ecs.Cluster("testing", { vpc });

const autoScalingGroup = cluster.createAutoScalingGroup("testing", {
    templateParameters: { minSize: 10 },
    launchConfigurationArgs: { instanceType: "t2.medium" },
});

This will create an ASG that use the private subnets of the VPC, attempting to keep around at least 10 instances running with the specified size. If you want instances to be allowed access to the internet, this can be done by specifying:

const autoScalingGroup = cluster.createAutoScalingGroup("testing", {
    // ... other parameters
    subnetIds: vpc.publicSubnetIds,
    launchConfigurationArgs: { instanceType: "t2.medium", associatePublicIpAddress: true },
});

Here we place in the public subnets of the VPC and provide associatePublicIpAddress: true so that instances will have IPs that are externally reachable.

Template parameters

The templateParameters allows one to control additional aspects of the ASG. For example, the following are supported:

Setting a maxSize for the maximum number of instances that can be launched at a time.
Controlling how health checks are performed to determine if new instances should be created.
Specifying an appropriate defaultCooldown period which controls how often the ASG actually scales things. This cooldown period helps avoid rapid runaway scaling scenarios from happening.

Launch configuration

The launchConfiguration (or launchConfigurationArgs) properties help control the configuration of the actual instances that are launched by the ASG. A launch configuration is an instance configuration template that an Auto Scaling group uses to launch EC2 instances. When you create a launch configuration, you specify information for the instances. Include the ID of the Amazon Machine Image (AMI), the instance type, a key pair, one or more security groups, and a block device mapping. If you’ve launched an EC2 instance before, you specified the same information in order to launch the instance.

If you don’t provide either of these properties, a default configuration will be created on your behalf with basic values set as appropriate.

Scaling schedules

Scaling based on a schedule allows you to set your own scaling schedule for predictable load changes. For example, every week the traffic to your web application starts to increase on Wednesday, remains high on Thursday, and starts to decrease on Friday. You can plan your scaling actions based on the predictable traffic patterns of your web application. Scaling actions are performed automatically as a function of time and date.

To create a Schedule you can do:

// Schedule the ASG to go up to 20 instances on Friday and back down to 10 on Monday.
autoScalingGroup.scaleOnSchedule("scaleUpOnFriday", {
    desiredCapacity: 20,
    recurrence: { dayOfWeek: "Friday" },
});
autoScalingGroup.scaleOnSchedule("scaleDownOnMonday", {
    desiredCapacity: 10,
    recurrence: { dayOfWeek: "Monday" },
});

Schedules also support normal Cron format strings like so:

// Schedule the ASG to go up to 20 instances on Friday and back down to 10 on Monday.
autoScalingGroup.scaleOnSchedule("scaleUpOnFriday", {
    desiredCapacity: 20,
    recurrence: "* * * * 5",
});
autoScalingGroup.scaleOnSchedule("scaleDownOnMonday", {
    desiredCapacity: 10,
    recurrence: "* * * * 1",
});

Scaling policies

A more advanced way to scale; scaling policies lets you define parameters that control the scaling process. For example, you could have a web application that currently runs on two EC2 instances and you want the CPU utilization of the group to stay at around 50 percent when the load on the application changes. This is useful for scaling in response to changing conditions, when you don’t necessarily know a specific schedule when those conditions will change.

There are two main ways to scale on demand:

Target Tracking. With target tracking scaling policies, you select a scaling metric and set a target value. Amazon EC2 Auto Scaling creates and manages the CloudWatch alarms that trigger the scaling policy and calculates the scaling adjustment based on the metric and the target value. The scaling policy adds or removes capacity as required to keep the metric at, or close to, the specified target value.
Step Scaling. With step scaling, you choose scaling metrics and threshold values for the CloudWatch alarms that trigger the scaling process as well as define how your scalable target should be scaled when a threshold is in breach for a specified number of evaluation periods. Step scaling policies increase or decrease the current capacity of a scalable target based on a set of scaling adjustments, known as step adjustments. The adjustments vary based on the size of the alarm breach.

Target tracking scaling

With target tracking scaling policies, you select a scaling metric and set a target value. Amazon EC2 Auto Scaling creates and manages the CloudWatch alarms that trigger the scaling policy and calculates the scaling adjustment based on the metric and the target value. The scaling policy adds or removes capacity as required to keep the metric at, or close to, the specified target value. In addition to keeping the metric close to the target value, a target tracking scaling policy also adjusts to the changes in the metric due to a changing load pattern.

Predefined target tracking scaling

AutoScalingGroups provide several predefined scaling metrics.

Scaling based on cpu utilization:

// Try to keep the ASG using around 50% CPU.
autoScalingGroup.scaleToTrackAverageCPUUtilization("keepAround50Percent", {
    targetValue: 50,
});

If you only want the ASG to scale up by adding instances, and not have it remove instances when usage falls, you can pass disableScaleIn: true.

autoScalingGroup.scaleToTrackAverageCPUUtilization("scaleDownOnMonday", {
    targetValue: 50,
    disableScaleIn: true,
});

Scaling based on the average number of bytes sent/received on all network interfaces in this ASG.

autoScalingGroup.scaleToTrackAverageNetworkIn("scaleDownOnMonday", {
    targetValue: 100000000,
});
autoScalingGroup.scaleToTrackAverageNetworkOut("scaleDownOnMonday", {
    targetValue: 100000000,
});

Scaling based on the average number of requests completed per awsx.lb.ApplicationTargetGroup in the ASG. In order to do this, the ASG must be informed of that particular TargetGroup at creation time. Scaling for TargetGroups is only supported if the TargetGroup.targetType is set to "instance".

const cluster = new awsx.ecs.Cluster("testing");
const loadBalancer = new awsx.lb.ApplicationLoadBalancer("testing", { external: true });

const targetGroup = loadBalancer.createTargetGroup("testing", { port: 80, targetType: "instance" });

const autoScalingGroup = cluster.createAutoScalingGroup("testing", {
    targetGroups: [targetGroup],
    subnetIds: awsx.ec2.Vpc.getDefault().publicSubnetIds,
    templateParameters: { minSize: 10 },
    launchConfigurationArgs: { instanceType: "t2.medium", associatePublicIpAddress: true },
});

const policy = autoScalingGroup.scaleToTrackRequestCountPerTarget("onHighRequest", {
    targetValue: 1000,
    targetGroup: targetGroup,
});

Custom metric target tracking scaling

On top of the predefined targets defined above, you can also scale to any arbitrary [awsx.cloudwatch.Metric]. Note: not all metrics work for target tracking. This can be important when you are specifying a customized metric. The metric must be a valid utilization metric and describe how busy an instance is. The metric value must increase or decrease proportionally to the number of instances in the Auto Scaling group. That’s so the metric data can be used to proportionally scale out or in the number of instances.

We recommend that you scale on Amazon EC2 instance metrics with a 1-minute frequency because that ensures a faster response to utilization changes. Scaling on metrics with a 5-minute frequency can result in slower response times and scaling on stale metric data. By default, Amazon EC2 instances are enabled for basic monitoring, which means metric data for instances is available at 5-minute intervals. You can enable detailed monitoring to get metric data for instances at 1-minute frequency. For more information, see Configure-Monitoring-for-Auto-Scaling-Instances.

// Scale the ASG based on average memory utilization of a service.
// Try to keep enough instances to keep things around 50% memory utilization.
autoScalingGroup.scaleToTrackMetric("keepAround50Percent", {
    metric: awsx.ecs.metrics.memoryUtilization({ service, statistic: "Average", unit: "Percent" }),
    targetValue: 50,
});

Step scaling

Step scaling policies increase or decrease the current capacity of your Auto Scaling group based on a set of scaling adjustments, known as step adjustments. The adjustments vary based on the size of the alarm breach.

For example, consider the following StepScaling description for an ASG that has both a current capacity and a desired capacity of 10. The current and desired capacity is maintained while the aggregated metric value is greater than 40 and less than 60.

const autoScalingGroup = cluster.createAutoScalingGroup("testing", {
    templateParameters: { minSize: 2, desiredCapacity: 10 },
    launchConfigurationArgs: { instanceType: "t2.medium" },
});

autoScalingGroup.scaleInSteps("scale-in-out", {
    metric: awsx.ecs.metrics.memoryUtilization({ service, statistic: "Average", unit: "Percent" }),
    adjustmentType: "PercentChangeInCapacity",
    steps: {
        lower: [{ value: 30, adjustment: -30 }, { value: 40, adjustment: -10 }],
        upper: [{ value: 60, adjustment: 10 }, { value: 70, adjustment: 30 }]
    },
};

This represents the following scaling strategy:

Memory utilization:

0%               30%    40%          60%     70%               100%
-------------------------------------------------------------------
|       -30%      | -10% | Unchanged  | +10%  |       +30%        |
-------------------------------------------------------------------

This will end up setting two alarms for this metric. One for when the metric goes above 60%, and one where it goes below. Depending on which step range the value is in when the alarm fires, the ASG will scale accordingly. Because we’ve chosen "PercentChangeInCapacity" as our adjustment type, a value of 65% would scale the ASG up by 10%, while a value of 85% would scale the ASG up by 30%.

If the metric value gets to 60, Auto Scaling increases the desired capacity of the group by 1, to 11. That’s based on the second step adjustment of the scale-out policy (add 10 percent of 10). After the new capacity is added, Application Auto Scaling increases the current capacity to 11. If the metric value rises to 70 even after this increase in capacity, Application Auto Scaling increases the target capacity by 3, to 14. That’s based on the third step adjustment of the scale-out policy (add 30 percent of 11, 3.3, rounded down to 3).

If the metric value gets to 40, Application Auto Scaling decreases the target capacity by 1, to 13, based on the second step adjustment of the scale-in policy (remove 10 percent of 14, 1.4, rounded down to 1). If the metric value falls to 30 even after this decrease in capacity, Application Auto Scaling decreases the target capacity by 3, to 10, based on the third step adjustment of the scale-in policy (remove 30 percent of 13, 3.9, rounded down to 3).

Other adjustment types are possible as well. The full list is:

“ChangeInCapacity”. This increases or decreases the current capacity of the group by the specified number of instances. A positive value increases the capacity and a negative adjustment value decreases the capacity. For example: If the current capacity of the group is 3 instances and the adjustment is 5, then when this policy is performed, there are 5 instances added to the group for a total of 8 instances.
“ExactCapacity”. This changes the current capacity of the group to the specified number of instances. Specify a positive value with this adjustment type. For example: If the current capacity of the group is 3 instances and the adjustment is 5, then when this policy is performed, the capacity is set to 5 instances.
“PercentChangeInCapacity”. As shown above. Increment or decrement the current capacity of the group by the specified percentage. A positive value increases the capacity and a negative value decreases the capacity. If the resulting value is not an integer, it is rounded. See [step scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-scaling-simple-step.html for more) details. With “PercentChangeInCapacity”, you can also specify the minimum number of instances to scale using the minAdjustmentMagnitude parameter.

Others

AdjustmentType
ApplicationTargetGroupTrackingPolicyArgs
AutoScalingGroupArgs
AutoScalingLaunchConfigurationArgs
AutoScalingUserData
cronExpression
CustomMetricTargetTrackingPolicyArgs
DayOfWeek
metrics
Month
ScalingStep
ScalingSteps
ScheduleArgs
ScheduleRecurrenceArgs
StepScalingPolicyArgs
TargetTrackingPolicyArgs
TemplateParameters
UserDataLine

Resources

Resource AutoScalingGroup

class AutoScalingGroup extends ComponentResource

constructor

new AutoScalingGroup(name: string, args: AutoScalingGroupArgs, opts: ComponentResourceOptions)

method getData

protected getData(): Promise<TData>

Retrieves the data produces by [initialize]. The data is immediately available in a derived class’s constructor after the super(...) call to ComponentResource.

method getProvider

getProvider(moduleMember: string): ProviderResource | undefined

method initialize

protected initialize(args: Inputs): Promise<TData>

Can be overridden by a subclass to asynchronously initialize data for this Component automatically when constructed. The data will be available immediately for subclass constructors to use. To access the data use .getData.

method isInstance

static isInstance(obj: any): obj is ComponentResource

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method registerOutputs

protected registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void

registerOutputs registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

ComponentResources can call this at the end of their constructor to indicate that they are done creating child resources. This is not strictly necessary as this will automatically be called after the initialize method completes.

method scaleInSteps

public scaleInSteps(name: string, args: StepScalingPolicyArgs, opts?: pulumi.ComponentResourceOptions): StepScalingPolicy

Creates a [StepScalingPolicy] that increases or decreases the current capacity of this AutoScalingGroup based on a set of scaling adjustments, known as step adjustments. The adjustments vary based on the size of the alarm breach.

See [StepScalingPolicy] for more details.

method scaleOnSchedule

public scaleOnSchedule(name: string, args: ScheduleArgs, opts: CustomResourceOptions): Schedule

method scaleToTrackAverageCPUUtilization

public scaleToTrackAverageCPUUtilization(name: string, args: TargetTrackingPolicyArgs, opts?: pulumi.ComponentResourceOptions): Policy

Scales in response to the average CPU utilization of the [AutoScalingGroup].

method scaleToTrackAverageNetworkIn

public scaleToTrackAverageNetworkIn(name: string, args: TargetTrackingPolicyArgs, opts?: pulumi.ComponentResourceOptions): Policy

Scales in response to the average number of bytes received on all network interfaces by the [AutoScalingGroup].

method scaleToTrackAverageNetworkOut

public scaleToTrackAverageNetworkOut(name: string, args: TargetTrackingPolicyArgs, opts?: pulumi.ComponentResourceOptions): Policy

Scales in response to the average number of bytes sent out on all network interfaces by the [AutoScalingGroup].

method scaleToTrackMetric

public scaleToTrackMetric(name: string, args: CustomMetricTargetTrackingPolicyArgs, opts?: pulumi.ComponentResourceOptions): Policy

For example, you can use target tracking scaling to:

Configure a target tracking scaling policy to keep the average aggregate CPU utilization of your Auto Scaling group at 50 percent.
Configure a target tracking scaling policy to keep the request count per target of your Elastic Load Balancing target group at 1000 for your Auto Scaling group.

See https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-scaling-target-tracking.html for more details.

method scaleToTrackRequestCountPerTarget

public scaleToTrackRequestCountPerTarget(name: string, args: ApplicationTargetGroupTrackingPolicyArgs, opts?: pulumi.ComponentResourceOptions): Policy

Scales in response to the number of requests completed per target in an [TargetGroup]. [AutoScalingGroup]. These [TargetGroup]s must have been provided to the [AutoScalingGroup] when constructed using [AutoScalingGroupArgs.targetGroups].

property group

public group: Group;

Underlying [autoscaling.Group] that is created by cloudformation.

property launchConfiguration

public launchConfiguration: AutoScalingLaunchConfiguration;

The launch configuration for this auto scaling group.

property stack

public stack: Stack;

The [cloudformation.Stack] that was used to create this [AutoScalingGroup]. [CloudFormation] is used here as the existing AWS apis for creating [AutoScalingGroup]s are not rich enough to express everything that can be configured through [CloudFormation] itself.

property targetGroups

public targetGroups: TargetGroup[];

Target groups this [AutoScalingGroup] is attached to. See https://docs.aws.amazon.com/autoscaling/ec2/userguide/attach-load-balancer-asg.html for more details.

property urn

urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

property vpc

public vpc: Vpc;

Resource AutoScalingLaunchConfiguration

class AutoScalingLaunchConfiguration extends ComponentResource

constructor

new AutoScalingLaunchConfiguration(name: string, vpc: Vpc, args: AutoScalingLaunchConfigurationArgs, opts: ComponentResourceOptions)

method createInstanceProfile

public static createInstanceProfile(name: string, assumeRolePolicy?: string | PolicyDocument, policyArns?: string[], opts?: pulumi.ComponentResourceOptions): InstanceProfile

Creates the [instanceProfile] for a [ClusterAutoScalingLaunchConfiguration] if not provided explicitly. If [assumeRolePolicy] is provided it will be used when creating the task, otherwise [defaultInstanceProfilePolicyDocument] will be used. If [policyArns] are provided, they will be used to create [RolePolicyAttachment]s for the Role. Otherwise, [defaultInstanceProfilePolicyARNs] will be used.

method defaultInstanceProfilePolicyARNs

public static defaultInstanceProfilePolicyARNs(): string[]

method defaultInstanceProfilePolicyDocument

public static defaultInstanceProfilePolicyDocument(): PolicyDocument

method getData

protected getData(): Promise<TData>

Retrieves the data produces by [initialize]. The data is immediately available in a derived class’s constructor after the super(...) call to ComponentResource.

method getProvider

getProvider(moduleMember: string): ProviderResource | undefined

method initialize

protected initialize(args: Inputs): Promise<TData>

method isInstance

static isInstance(obj: any): obj is ComponentResource

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method registerOutputs

protected registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void

registerOutputs registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

property id

public id: pulumi.Output<string>;

property instanceProfile

public instanceProfile: InstanceProfile;

property launchConfiguration

public launchConfiguration: LaunchConfiguration;

property securityGroups

public securityGroups: SecurityGroup[];

property stackName

public stackName: pulumi.Output<string>;

Name to give the auto-scaling-group’s cloudformation stack name.

property urn

urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Resource StepScalingPolicy

class StepScalingPolicy extends ComponentResource

 const policy = {
     // ... other values
     adjustmentType: "PercentChangeInCapacity",
     steps: {
         upper: [{ value: 60, adjustment: 10 }, { value: 70, adjustment: 30 }],
         lower: [{ value: 40, adjustment: -10 }, { value: 30, adjustment: -30 }]
     },
 };

If the metric value gets to 60, Application Auto Scaling increases the desired capacity of the group by 1, to 11. That’s based on the second step adjustment of the scale-out policy (add 10 percent of 10). After the new capacity is added, Application Auto Scaling increases the current capacity to 11. If the metric value rises to 70 even after this increase in capacity, Application Auto Scaling increases the target capacity by 3, to 14. That’s based on the third step adjustment of the scale-out policy (add 30 percent of 11, 3.3, rounded down to 3).

constructor

new StepScalingPolicy(name: string, group: AutoScalingGroup, args: StepScalingPolicyArgs, opts: ComponentResourceOptions)

method getData

protected getData(): Promise<TData>

Retrieves the data produces by [initialize]. The data is immediately available in a derived class’s constructor after the super(...) call to ComponentResource.

method getProvider

getProvider(moduleMember: string): ProviderResource | undefined

method initialize

protected initialize(args: Inputs): Promise<TData>

method isInstance

static isInstance(obj: any): obj is ComponentResource

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method registerOutputs

protected registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void

registerOutputs registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

property lowerAlarm

public lowerAlarm: MetricAlarm | undefined;

Alarm that invokes [lowerPolicy] when the metric goes below the highest value of the lower range of steps.

property lowerPolicy

public lowerPolicy: Policy | undefined;

Underlying [Policy] created to define the scaling strategy for the lower set of steps.

property upperAlarm

public upperAlarm: MetricAlarm | undefined;

Alarm that invokes [upperPolicy] when the metric goes above the lowest value of the upper range of steps.

property upperPolicy

public upperPolicy: Policy | undefined;

Underlying [Policy] created to define the scaling strategy for the upper set of steps.

property urn

urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Others

type AdjustmentType

type AdjustmentType = "ChangeInCapacity" | "ExactCapacity" | "PercentChangeInCapacity";

interface ApplicationTargetGroupTrackingPolicyArgs

interface ApplicationTargetGroupTrackingPolicyArgs extends TargetTrackingPolicyArgs

property disableScaleIn

disableScaleIn?: pulumi.Input<boolean>;

Indicates whether scaling in by the target tracking scaling policy is disabled. If scaling in is disabled, the target tracking scaling policy doesn’t remove instances from the Auto Scaling group. Otherwise, the target tracking scaling policy can remove instances from the Auto Scaling group. Defaults to [false] if unspecified.

property estimatedInstanceWarmup

estimatedInstanceWarmup?: pulumi.Input<number>;

The estimated time, in seconds, until a newly launched instance will contribute CloudWatch metrics. Without a value, AWS will default to the group’s specified cooldown period.

property targetGroup

targetGroup: ApplicationTargetGroup;

The target group to scale [AutoScalingGroup] in response to number of requests to. This must be a [TargetGroup] that the [AutoScalingGroup] was created with. These can be provided to the [AutoScalingGroup] using [AutoScalingGroupArgs.targetGroups].

property targetValue

targetValue: pulumi.Input<number>;

The target value for the metric.

interface AutoScalingGroupArgs

interface AutoScalingGroupArgs

property disableRollback

disableRollback?: pulumi.Input<boolean>;

Set to true to disable rollback of the underlying aws.cloudformation.Stack if that Stack creation failed. Defaults to ‘false’. Conflicts with onFailure.

property launchConfiguration

launchConfiguration?: AutoScalingLaunchConfiguration;

The config to use when creating the auto scaling group.

[launchConfiguration] or [launchConfigurationArgs] can be provided. And, if either are provided will be used as the launch configuration for the auto scaling group.

If neither are provided, a default instance will be create by calling [cluster.createAutoScalingConfig()].

property launchConfigurationArgs

launchConfigurationArgs?: AutoScalingLaunchConfigurationArgs;

The config to use when creating the auto scaling group.

[launchConfiguration] or [launchConfigurationArgs] can be provided. And, if either are provided will be used as the launch configuration for the auto scaling group.

If neither are provided, a default instance will be create by calling [cluster.createAutoScalingConfig()].

property onFailure

onFailure?: pulumi.Input<"DO_NOTHING" | "ROLLBACK" | "DELETE">;

Action to be taken if stack creation fails. This must be one of: DO_NOTHING, ROLLBACK, or DELETE. Conflicts with disableRollback.

property subnetIds

subnetIds?: pulumi.Input<pulumi.Input<string>[]>;

The subnets to use for the autoscaling group. If not provided, the private subnets of the vpc will be used.

property targetGroups

targetGroups?: TargetGroup[];

A list of target groups to associate with the Auto Scaling group. All target groups must have the “instance” [targetType].

property templateParameters

templateParameters?: pulumi.Input<TemplateParameters>;

Parameters to control the cloud formation stack template that is created. If not provided the defaults specified in TemplateParameters will be used.

property vpc

vpc?: ec2.Vpc;

The vpc this autoscaling group is for. If not provided this autoscaling group will be created for the default vpc.

interface AutoScalingLaunchConfigurationArgs

interface AutoScalingLaunchConfigurationArgs

The set of arguments when creating the launch configuration for a cluster’s autoscaling group.

property associatePublicIpAddress

associatePublicIpAddress?: pulumi.Input<boolean>;

Associate a public ip address with an instance in a VPC.

property ebsBlockDevices

ebsBlockDevices?;

Additional EBS block devices to attach to the instance. See Block Devices below for details.

If not provided, a 5gb ‘gp2’ device will be mounted at ‘/dev/xvdb’ and a 50gb ‘gp2’ device will be mounted at ‘/dev/xvdcz’. Both devices will be deleted upon termination.

property ebsOptimized

ebsOptimized?: pulumi.Input<boolean>;

If true, the launched EC2 instance will be EBS-optimized.

property ecsOptimizedAMIName

ecsOptimizedAMIName?: undefined | string;

The name of the ECS-optimzed AMI to use for the Container Instances in this cluster, e.g. “amzn-ami-2017.09.l-amazon-ecs-optimized”. Defaults to using the latest recommended ECS Linux Optimized AMI, which may change over time and cause recreation of EC2 instances when new versions are release. To control when these changes are adopted, set this parameter explicitly to the version you would like to use.

See http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html for valid values.

property enableMonitoring

enableMonitoring?: pulumi.Input<boolean>;

Enables/disables detailed monitoring. This is enabled by default.

property ephemeralBlockDevices

ephemeralBlockDevices?;

Customize Ephemeral (also known as “Instance Store”) volumes on the instance. See Block Devices below for details.

property iamInstanceProfile

iamInstanceProfile?: pulumi.Input<string | InstanceProfile>;

The name attribute of the IAM instance profile to associate with launched instances.

property imageId

imageId?: pulumi.Input<string>;

The EC2 image ID to launch. If this is not provided, then [ecsOptimizedAMIName] will be used. If neither are provided the imageId for Amazon’ "/aws/service/ecs/optimized-ami/amazon-linux/recommended" image will be used.

property instanceProfile

instanceProfile?: aws.iam.InstanceProfile;

The instance profile to use for the autoscaling group. If not provided, a default one will be created.

property instanceType

instanceType?: pulumi.Input<aws.ec2.InstanceType>;

The size of instance to launch. Defaults to t2.micro if unspecified.

property keyName

keyName?: pulumi.Input<string>;

The key name that should be used for the instance.

property name

name?: pulumi.Input<string>;

The name of the launch configuration. If you leave this blank, Terraform will auto-generate a unique name.

property namePrefix

namePrefix?: pulumi.Input<string>;

Creates a unique name beginning with the specified prefix. Conflicts with name.

property placementTenancy

placementTenancy?: pulumi.Input<"default" | "dedicated">;

The tenancy of the instance. Valid values are "default" or "dedicated", see http://docs.aws.amazon.com/AutoScaling/latest/APIReference/API_CreateLaunchConfiguration.html for more details. Default is “default” if unspecified.

property rootBlockDevice

rootBlockDevice?;

Customize details about the root block device of the instance. See Block Devices below for details.

If not provided, an 32gb ‘gp2’ root device will be created. This device will be deleted upon termination.

property securityGroups

securityGroups?: ec2.SecurityGroupOrId[];

A list of associated security group IDs.

property spotPrice

spotPrice?: pulumi.Input<string>;

The maximum price to use for reserving spot instances.

property stackName

stackName?: pulumi.Input<string>;

The name of the stack the launch configuration will signal.

property userData

userData?: pulumi.Input<string> | AutoScalingUserData;

The user data to provide when launching the instance. Do not pass gzip-compressed data via this argument; see user_data_base64 instead.

property userDataBase64

userDataBase64?: pulumi.Input<string>;

Can be used instead of user_data to pass base64-encoded binary data directly. Use this instead of user_data whenever the value is not a valid UTF-8 string. For example, gzip-encoded user data must be base64-encoded and passed via this argument to avoid corruption.

property vpcClassicLinkId

vpcClassicLinkId?: pulumi.Input<string>;

The ID of a ClassicLink-enabled VPC. Only applies to EC2-Classic instances. (eg. vpc-2730681a)

property vpcClassicLinkSecurityGroups

vpcClassicLinkSecurityGroups?: pulumi.Input<pulumi.Input<string>[]>;

The IDs of one or more security groups for the specified ClassicLink-enabled VPC (eg. sg-46ae3d11).

interface AutoScalingUserData

interface AutoScalingUserData

method extraBootcmdLines

extraBootcmdLines(): pulumi.Input<UserDataLine[]>

Additional lines to be placed in the bootcmd section of the launch configuration.

method extraRuncmdLines

extraRuncmdLines(): pulumi.Input<UserDataLine[]>

Additional lines to be placed in the runcmd section of the launch configuration.

function cronExpression

cronExpression(a: ScheduleRecurrenceArgs): string

Creates an appropriate Cron format string that can be used as the [recurrence] property of [ScheduleArgs].

interface CustomMetricTargetTrackingPolicyArgs

interface CustomMetricTargetTrackingPolicyArgs extends TargetTrackingPolicyArgs

Represents a CloudWatch metric of your choosing for a target tracking scaling policy to use with Amazon EC2 Auto Scaling.

To create your customized metric specification:

Add values for each required parameter from CloudWatch. You can use an existing metric, or a new metric that you create. To use your own metric, you must first publish the metric to CloudWatch. For more information, see Publish-Custom-Metrics in the Amazon CloudWatch User Guide.
Choose a metric that changes proportionally with capacity. The value of the metric should increase or decrease in inverse proportion to the number of capacity units. That is, the value of the metric should decrease when capacity increases.

property disableScaleIn

disableScaleIn?: pulumi.Input<boolean>;

property estimatedInstanceWarmup

estimatedInstanceWarmup?: pulumi.Input<number>;

The estimated time, in seconds, until a newly launched instance will contribute CloudWatch metrics. Without a value, AWS will default to the group’s specified cooldown period.

property metric

metric: Metric;

The metric to track

property targetValue

targetValue: pulumi.Input<number>;

The target value for the metric.

type DayOfWeek

type DayOfWeek = number | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday";

If a number, it must be between 0 to 7 (inclusive). (0 and 7 both represent Sunday). Leave undefined to indicate no specific value.

namespace metrics

interface AutoScalingMetricChange

interface AutoScalingMetricChange extends MetricChange

property color

color?: pulumi.Input<string>;

The six-digit HTML hex color code to be used for this metric.

Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].

property dimensions

dimensions?: pulumi.Input<Record<string, pulumi.Input<string>>>;

The new dimension for this metric. If this object is missing this property, then no change will be made. However, if the property is there by set to [undefined] then the value will be cleared.

property extendedStatistic

extendedStatistic?: pulumi.Input<number>;

The new percentile statistic for the metric associated with the alarm. If this object is missing this property, then no change will be made. However, if the property is there by set to [undefined] then the value will be set to the default.

property group

group?: aws.autoscaling.Group;

Optional [Group] to filter down events to.

property label

label?: pulumi.Input<string>;

The label to display for this metric in the graph legend. If this is not specified, the metric is given an autogenerated label that distinguishes it from the other metrics in the widget.

Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].

property period

period?: pulumi.Input<number>;

The new period in seconds over which the specified stat is applied. If this object is missing this property, then no change will be made. However, if the property is there by set to [undefined] then the value will be set to the default (300s).

property statistic

statistic?: pulumi.Input<MetricStatistic>;

The new statistic to apply to the alarm’s associated metric. If this object is missing this property, then no change will be made. However, if the property is there by set to [undefined] then the value will be set to the default.

property unit

unit?: pulumi.Input<MetricUnit>;

The new unit for this metric. If this object is missing this property, then no change will be made. However, if the property is there by set to [undefined] then the value will be set to the default.

property visible

visible?: pulumi.Input<boolean>;

Set this to true to have the metric appear in the graph, or false to have it be hidden. The default is true.

Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].

property yAxis

yAxis?: pulumi.Input<"left" | "right">;

Where on the graph to display the y-axis for this metric. The default is left.

Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].

function groupDesiredCapacity

groupDesiredCapacity(change?: AutoScalingMetricChange): Metric

The number of instances that the Auto Scaling group attempts to maintain.

function groupInServiceInstances

groupInServiceInstances(change?: AutoScalingMetricChange): Metric

The number of instances that are running as part of the Auto Scaling group. This metric does not include instances that are pending or terminating.

function groupMaxSize

groupMaxSize(change?: AutoScalingMetricChange): Metric

The maximum size of the Auto Scaling group.

function groupMinSize

groupMinSize(change?: AutoScalingMetricChange): Metric

The minimum size of the Auto Scaling group.

function groupPendingInstances

groupPendingInstances(change?: AutoScalingMetricChange): Metric

The number of instances that are pending. A pending instance is not yet in service. This metric does not include instances that are in service or terminating.

function groupStandbyInstances

groupStandbyInstances(change?: AutoScalingMetricChange): Metric

The number of instances that are in a Standby state. Instances in this state are still running but are not actively in service.

function groupTerminatingInstances

groupTerminatingInstances(change?: AutoScalingMetricChange): Metric

The number of instances that are in the process of terminating. This metric does not include instances that are in service or pending.

function groupTotalInstances

groupTotalInstances(change?: AutoScalingMetricChange): Metric

The total number of instances in the Auto Scaling group. This metric identifies the number of instances that are in service, pending, and terminating.

function metric

metric(metricName: aws.autoscaling.Metric, change: AutoScalingMetricChange): Metric

Creates an AWS/AutoScaling metric with the requested [metricName]. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html for list of all metric-names.

Note, individual metrics can easily be obtained without supplying the name using the other [metricXXX] functions.

Amazon CloudWatch enables you to retrieve statistics as an ordered set of time-series data, known as metrics. You can use these metrics to verify that your system is performing as expected.

Amazon EC2 sends metrics to CloudWatch that describe your Auto Scaling instances. These metrics are available for any EC2 instance, not just those in an Auto Scaling group. For more information, see Instance Metrics in the Amazon EC2 User Guide for Linux Instances.

Auto Scaling groups can send metrics to CloudWatch that describe the group itself. You must enable these metrics.

To filter the metrics for your Auto Scaling group by group name, use the “AutoScalingGroupName” dimension.

type Month

type Month = number | "January" | "February" | "March" | "April" | "May" | "June" | "July" | "August" | "September" | "October" | "November" | "December";

If a number, it must be between 1 to 12 (inclusive). Leave undefined to indicate no specific value.

interface ScalingStep

interface ScalingStep

property adjustment

adjustment: pulumi.Input<number>;

The number of members by which to scale, when [value] breached. A positive value scales up. A negative value scales down.

property value

value: pulumi.Input<number>;

The threshold value that causes this step to be followed. If this an upperStep then values >= to this will trigger this step’s [scalingAdjustment]. If this is a lowerStep then values <= to this will trigger this step’s [scalingAdjustment].

interface ScalingSteps

interface ScalingSteps

property lower

lower?: pulumi.Input<ScalingStep>[];

Optional lower steps for this step policy normally used to describe how to scale-in the AutoScalingGroup. If these are provided then the step policy will create two alarms. One for when the upper steps are breached and one for when the lower steps are breached.

The latter alarm will fire when the desired metric goes less-than-or-equal-to the value of the first step’s value. Each step ranges from it’s value (inclusive) to the value of the next step (exclusive). For the last step, the end part of the range is -Infinity.

Depending on which step range the alarm triggers for will determine which particular [scalingAdjustment] will be performed.

At least one of upper or lower must be non-empty. If both are provided, upper and lower must not overlap.

property upper

upper?: pulumi.Input<ScalingStep>[];

Optional upper steps for this policy normally describing how to scale-out the AutoScalingGroup. This must be non-empty. An alarm will be created that will fire when the desired metric goes greater-than-or-equal-to the value of the first step’s value. Each step ranges from it’s value (inclusive) to the value of the next step (exclusive). For the last step, the end part of the range is Infinity.

Depending on which step range the alarm triggers for will determine which particular [scalingAdjustment] will be performed.

At least one of upper or lower must be non-empty. If both are provided, upper and lower must not overlap.

interface ScheduleArgs

interface ScheduleArgs

property desiredCapacity

desiredCapacity?: pulumi.Input<number>;

The number of EC2 instances that should be running in the group. Do not pass a value if you don’t want to change the size at the scheduled time.

property endTime

endTime?: pulumi.Input<string>;

The time for this action to end, in “YYYY-MM-DDThh:mm:ssZ” format in UTC/GMT only (for example, 2014-06-01T00:00:00Z ). If you try to schedule your action in the past, Auto Scaling returns an error message.

property maxSize

maxSize?: pulumi.Input<number>;

The maximum size for the Auto Scaling group. Do not pass a value if you don’t want to change the size at the scheduled time.

property minSize

minSize?: pulumi.Input<number>;

The minimum size for the Auto Scaling group. Do not pass a value if you don’t want to change the size at the scheduled time.

property recurrence

recurrence?: pulumi.Input<string | ScheduleRecurrenceArgs>;

The time when recurring future actions will start. Start time is specified by the user following the Unix cron syntax format. [cronExpression] can be used to easily create values of this.

property scheduledActionName

scheduledActionName?: pulumi.Input<string>;

The name of this scaling action. If not provided, the name of the requested [aws.autoscaling.Schedule] will be used for this.

property startTime

startTime?: pulumi.Input<string>;

The time for this action to start, in “YYYY-MM-DDThh:mm:ssZ” format in UTC/GMT only (for example, 2014-06-01T00:00:00Z ). If you try to schedule your action in the past, Auto Scaling returns an error message.

interface ScheduleRecurrenceArgs

interface ScheduleRecurrenceArgs

property dayOfMonth

dayOfMonth?: undefined | number;

1 to 31. Leave undefined to indicate no specific value.

property dayOfWeek

dayOfWeek?: DayOfWeek;

Day of the week to perform the scheduled action on. Leave undefined to indicate no specific value.

property hour

hour?: undefined | number;

0 to 23. Leave undefined to indicate no specific value. All times UTC

property minute

minute?: undefined | number;

0 to 59. Leave undefined to indicate no specific value.

property month

month?: Month;

Month of the year to perform the scheduled action on. Leave undefined to indicate no specific value.

interface StepScalingPolicyArgs

interface StepScalingPolicyArgs

property adjustmentType

adjustmentType: pulumi.Input<AdjustmentType>;

When a step scaling or simple scaling policy is executed, it changes the current capacity of your Auto Scaling group using the scaling adjustment specified in the policy. A scaling adjustment can’t change the capacity of the group above the maximum group size or below the minimum group size.

property estimatedInstanceWarmup

estimatedInstanceWarmup?: pulumi.Input<number>;

The estimated time, in seconds, until a newly launched instance will contribute CloudWatch metrics. Without a value, AWS will default to the group’s specified cooldown period.

property evaluationPeriods

evaluationPeriods?: pulumi.Input<number>;

The number of periods over which data is compared to the specified threshold before an alarm is fired. Defaults to 1 if unspecified.

property metric

metric: Metric;

The metric to use to watch for changes. An alarm will be created from this using [alarmArgs], which will invoke the actual autoscaling policy when triggered.

Note: the period of this metric will be set to 60s from the default of 300s to ensure events come in in a timely enough manner to allow the ASG to respond accordingly.

property minAdjustmentMagnitude

minAdjustmentMagnitude?: pulumi.Input<number>;

The minimum number of instances to scale. If the value of [adjustmentType] is [“PercentChangeInCapacity”], the scaling policy changes the DesiredCapacity of the Auto Scaling group by at least this many instances. Defaults to 1 if not specified.

property steps

steps: ScalingSteps;

A set of adjustments that manage group scaling.

interface TargetTrackingPolicyArgs

interface TargetTrackingPolicyArgs

property disableScaleIn

disableScaleIn?: pulumi.Input<boolean>;

property estimatedInstanceWarmup

estimatedInstanceWarmup?: pulumi.Input<number>;

The estimated time, in seconds, until a newly launched instance will contribute CloudWatch metrics. Without a value, AWS will default to the group’s specified cooldown period.

property targetValue

targetValue: pulumi.Input<number>;

The target value for the metric.

interface TemplateParameters

interface TemplateParameters

property defaultCooldown

defaultCooldown?: pulumi.Input<number>;

The amount of time, in seconds, after a scaling activity completes before another scaling activity can start. Defaults to 300 if unspecified.

property desiredCapacity

desiredCapacity?: pulumi.Input<number>;

The desired size of the auto scale group. Defaults to [minSize] if unspecified.

property healthCheckGracePeriod

healthCheckGracePeriod?: pulumi.Input<number>;

Time (in seconds) after instance comes into service before checking health. Defaults to 120 if unspecified.

property healthCheckType

healthCheckType?: pulumi.Input<"EC2" | "ELB">;

“EC2” or “ELB”. Controls how health checking is done. Defaults to “EC2” if unspecified.

property maxSize

maxSize?: pulumi.Input<number>;

The maximum size of the auto scale group. Defaults to 100 if unspecified.

property minSize

minSize?: pulumi.Input<number>;

The minimum size of the auto scale group. Defaults to 2 if unspecified.

property suspendedProcesses

suspendedProcesses?: pulumi.Input<pulumi.Input<"Launch" | "Terminate" | "HealthCheck" | "ReplaceUnhealthy" | "AZRebalance" | "AlarmNotification" | "ScheduledActions" | "AddToLoadBalancer">[]>;

A list of processes to suspend for the AutoScaling Group. The allowed values are Launch, Terminate, HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, ScheduledActions, AddToLoadBalancer. Note that if you suspend either the Launch or Terminate process types, it can prevent your autoscaling group from functioning properly.

Defaults to “ScheduledActions” if not specified

interface UserDataLine

interface UserDataLine

A line that should be added to the [userData] section of a LaunchConfiguration template.

property automaticallyIndent

automaticallyIndent?: undefined | false | true;

Whether the line should be automatically indented to the right level. Defaults to [true]. Set explicitly to [false] to control all indentation.

property contents

contents: string;

Actual contents of the line.

Module classic/autoscaling

On this page

On this page

Pulumi Autoscaling Components

Creating an AutoScalingGroup

Template parameters

Launch configuration

Scaling schedules

Scaling policies

Target tracking scaling

Predefined target tracking scaling

Custom metric target tracking scaling

Step scaling

Resources

Others

Resources

Others