Skip to content

terraform-aws-modules/terraform-aws-autoscaling

AWS Auto Scaling Group (ASG) Terraform module

Terraform module which creates Auto Scaling resources on AWS.

SWUbanner

Available Features

  • Autoscaling group with launch template - either created by the module or utilizing an existing launch template
  • Autoscaling group utilizing mixed instances policy
  • Ability to configure autoscaling groups to set instance refresh configuration and add lifecycle hooks
  • Ability to create an autoscaling group that respects desired_capacity or one that ignores to allow for scaling without conflicting Terraform diffs
  • IAM role and instance profile creation

Usage

module "asg" {
  source  = "terraform-aws-modules/autoscaling/aws"

  # Autoscaling group
  name = "example-asg"

  min_size                  = 0
  max_size                  = 1
  desired_capacity          = 1
  wait_for_capacity_timeout = 0
  health_check_type         = "EC2"
  vpc_zone_identifier       = ["subnet-1235678", "subnet-87654321"]

  initial_lifecycle_hooks = [
    {
      name                  = "ExampleStartupLifeCycleHook"
      default_result        = "CONTINUE"
      heartbeat_timeout     = 60
      lifecycle_transition  = "autoscaling:EC2_INSTANCE_LAUNCHING"
      notification_metadata = jsonencode({ "hello" = "world" })
    },
    {
      name                  = "ExampleTerminationLifeCycleHook"
      default_result        = "CONTINUE"
      heartbeat_timeout     = 180
      lifecycle_transition  = "autoscaling:EC2_INSTANCE_TERMINATING"
      notification_metadata = jsonencode({ "goodbye" = "world" })
    }
  ]

  instance_refresh = {
    strategy = "Rolling"
    preferences = {
      checkpoint_delay       = 600
      checkpoint_percentages = [35, 70, 100]
      instance_warmup        = 300
      min_healthy_percentage = 50
      max_healthy_percentage = 100
    }
    triggers = ["tag"]
  }

  # Launch template
  launch_template_name        = "example-asg"
  launch_template_description = "Launch template example"
  update_default_version      = true

  image_id          = "ami-ebd02392"
  instance_type     = "t3.micro"
  ebs_optimized     = true
  enable_monitoring = true

  # IAM role & instance profile
  create_iam_instance_profile = true
  iam_role_name               = "example-asg"
  iam_role_path               = "/ec2/"
  iam_role_description        = "IAM role example"
  iam_role_tags = {
    CustomIamRole = "Yes"
  }
  iam_role_policies = {
    AmazonSSMManagedInstanceCore = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
  }

  block_device_mappings = [
    {
      # Root volume
      device_name = "/dev/xvda"
      no_device   = 0
      ebs = {
        delete_on_termination = true
        encrypted             = true
        volume_size           = 20
        volume_type           = "gp2"
      }
    }, {
      device_name = "/dev/sda1"
      no_device   = 1
      ebs = {
        delete_on_termination = true
        encrypted             = true
        volume_size           = 30
        volume_type           = "gp2"
      }
    }
  ]

  capacity_reservation_specification = {
    capacity_reservation_preference = "open"
  }

  cpu_options = {
    core_count       = 1
    threads_per_core = 1
  }

  credit_specification = {
    cpu_credits = "standard"
  }

  instance_market_options = {
    market_type = "spot"
    spot_options = {
      block_duration_minutes = 60
    }
  }

  # This will ensure imdsv2 is enabled, required, and a single hop which is aws security
  # best practices
  # See https://docs.aws.amazon.com/securityhub/latest/userguide/autoscaling-controls.html#autoscaling-4
  metadata_options = {
    http_endpoint               = "enabled"
    http_tokens                 = "required"
    http_put_response_hop_limit = 1
  }

  network_interfaces = [
    {
      delete_on_termination = true
      description           = "eth0"
      device_index          = 0
      security_groups       = ["sg-12345678"]
    },
    {
      delete_on_termination = true
      description           = "eth1"
      device_index          = 1
      security_groups       = ["sg-12345678"]
    }
  ]

  placement = {
    availability_zone = "us-west-1b"
  }

  tag_specifications = [
    {
      resource_type = "instance"
      tags          = { WhatAmI = "Instance" }
    },
    {
      resource_type = "volume"
      tags          = { WhatAmI = "Volume" }
    },
    {
      resource_type = "spot-instances-request"
      tags          = { WhatAmI = "SpotInstanceRequest" }
    }
  ]

  tags = {
    Environment = "dev"
    Project     = "megasecret"
  }
}

Conditional creation

The following combinations are supported to conditionally create resources and/or use externally created resources within the module:

Note: the default behavior of the module is to create an autoscaling group and launch template.

  • Disable resource creation (no resources created):
  create                 = false
  create_launch_template = false
  • Create only a launch template:
  create = false
  • Create an autoscaling group using an externally created launch template:
  create_launch_template = false
  launch_template        = aws_launch_template.my_launch_template.name
  • Create an autoscaling group with a mixed instance policy:
  use_mixed_instances_policy = true
  • Create the autoscaling policies:
  scaling_policies = {
    my-policy = {
      policy_type               = "TargetTrackingScaling"
      target_tracking_configuration = {
        predefined_metric_specification = {
          predefined_metric_type = "ASGAverageCPUUtilization"
          resource_label         = "MyLabel"
        }
        target_value = 50.0
      }
    }
  }

Examples

  • Complete - Creates several variations of resources for autoscaling groups and launch templates.

Requirements

Name Version
terraform >= 1.3
aws >= 5.55

Providers

Name Version
aws >= 5.55

Modules

No modules.

Resources

Name Type
aws_autoscaling_group.idc resource
aws_autoscaling_group.this resource
aws_autoscaling_policy.this resource
aws_autoscaling_schedule.this resource
aws_autoscaling_traffic_source_attachment.this resource
aws_iam_instance_profile.this resource
aws_iam_role.this resource
aws_iam_role_policy_attachment.this resource
aws_launch_template.this resource
aws_iam_policy_document.assume_role_policy data source
aws_partition.current data source

Inputs

Name Description Type Default Required
autoscaling_group_tags A map of additional tags to add to the autoscaling group map(string) {} no
availability_zones A list of one or more availability zones for the group. Used for EC2-Classic and default subnets when not specified with vpc_zone_identifier argument. Conflicts with vpc_zone_identifier list(string) null no
block_device_mappings Specify volumes to attach to the instance besides the volumes specified by the AMI list(any) [] no
capacity_rebalance Indicates whether capacity rebalance is enabled bool null no
capacity_reservation_specification Targeting for EC2 capacity reservations any {} no
cpu_options The CPU options for the instance map(string) {} no
create Determines whether to create autoscaling group or not bool true no
create_iam_instance_profile Determines whether an IAM instance profile is created or to use an existing IAM instance profile bool false no
create_launch_template Determines whether to create launch template or not bool true no
create_scaling_policy Determines whether to create target scaling policy schedule or not bool true no
create_schedule Determines whether to create autoscaling group schedule or not bool true no
credit_specification Customize the credit specification of the instance map(string) {} no
default_cooldown The amount of time, in seconds, after a scaling activity completes before another scaling activity can start number null no
default_instance_warmup Amount of time, in seconds, until a newly launched instance can contribute to the Amazon CloudWatch metrics. This delay lets an instance finish initializing before Amazon EC2 Auto Scaling aggregates instance metrics, resulting in more reliable usage data. Set this value equal to the amount of time that it takes for resource consumption to become stable after an instance reaches the InService state. number null no
default_version Default Version of the launch template string null no
delete_timeout Delete timeout to wait for destroying autoscaling group string null no
desired_capacity The number of Amazon EC2 instances that should be running in the autoscaling group number null no
desired_capacity_type The unit of measurement for the value specified for desired_capacity. Supported for attribute-based instance type selection only. Valid values: units, vcpu, memory-mib. string null no
disable_api_stop If true, enables EC2 instance stop protection bool null no
disable_api_termination If true, enables EC2 instance termination protection bool null no
ebs_optimized If true, the launched EC2 instance will be EBS-optimized bool null no
elastic_gpu_specifications The elastic GPU to attach to the instance map(string) {} no
elastic_inference_accelerator Configuration block containing an Elastic Inference Accelerator to attach to the instance map(string) {} no
enable_monitoring Enables/disables detailed monitoring bool true no
enabled_metrics A list of metrics to collect. The allowed values are GroupDesiredCapacity, GroupInServiceCapacity, GroupPendingCapacity, GroupMinSize, GroupMaxSize, GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances, GroupStandbyCapacity, GroupTerminatingCapacity, GroupTerminatingInstances, GroupTotalCapacity, GroupTotalInstances list(string) [] no
enclave_options Enable Nitro Enclaves on launched instances map(string) {} no
force_delete Allows deleting the Auto Scaling Group without waiting for all instances in the pool to terminate. You can force an Auto Scaling Group to delete even if it's in the process of scaling a resource. Normally, Terraform drains all the instances before deleting the group. This bypasses that behavior and potentially leaves resources dangling bool null no
health_check_grace_period Time (in seconds) after instance comes into service before checking health number null no
health_check_type EC2 or ELB. Controls how health checking is done string null no
hibernation_options The hibernation options for the instance map(string) {} no
iam_instance_profile_arn Amazon Resource Name (ARN) of an existing IAM instance profile. Used when create_iam_instance_profile = false string null no
iam_instance_profile_name The name of the IAM instance profile to be created (create_iam_instance_profile = true) or existing (create_iam_instance_profile = false) string null no
iam_role_description Description of the role string null no
iam_role_name Name to use on IAM role created string null no
iam_role_path IAM role path string null no
iam_role_permissions_boundary ARN of the policy that is used to set the permissions boundary for the IAM role string null no
iam_role_policies IAM policies to attach to the IAM role map(string) {} no
iam_role_tags A map of additional tags to add to the IAM role created map(string) {} no
iam_role_use_name_prefix Determines whether the IAM role name (iam_role_name) is used as a prefix bool true no
ignore_desired_capacity_changes Determines whether the desired_capacity value is ignored after initial apply. See README note for more details bool false no
ignore_failed_scaling_activities Whether to ignore failed Auto Scaling scaling activities while waiting for capacity. The default is false -- failed scaling activities cause errors to be returned. bool false no
image_id The AMI from which to launch the instance string "" no
initial_lifecycle_hooks One or more Lifecycle Hooks to attach to the Auto Scaling Group before instances are launched. The syntax is exactly the same as the separate aws_autoscaling_lifecycle_hook resource, without the autoscaling_group_name attribute. Please note that this will only work when creating a new Auto Scaling Group. For all other use-cases, please use aws_autoscaling_lifecycle_hook resource list(map(string)) [] no
instance_initiated_shutdown_behavior Shutdown behavior for the instance. Can be stop or terminate. (Default: stop) string null no
instance_maintenance_policy If this block is configured, add a instance maintenance policy to the specified Auto Scaling group map(any) {} no
instance_market_options The market (purchasing) option for the instance any {} no
instance_name Name that is propogated to launched EC2 instances via a tag - if not provided, defaults to var.name string "" no
instance_refresh If this block is configured, start an Instance Refresh when this Auto Scaling Group is updated any {} no
instance_requirements The attribute requirements for the type of instance. If present then instance_type cannot be present any {} no
instance_type The type of the instance. If present then instance_requirements cannot be present string null no
kernel_id The kernel ID string null no
key_name The key name that should be used for the instance string null no
launch_template_description Description of the launch template string null no
launch_template_id ID of an existing launch template to be used (created outside of this module) string null no
launch_template_name Name of launch template to be created string "" no
launch_template_use_name_prefix Determines whether to use launch_template_name as is or create a unique name beginning with the launch_template_name as the prefix bool true no
launch_template_version Launch template version. Can be version number, $Latest, or $Default string null no
license_specifications A list of license specifications to associate with map(string) {} no
maintenance_options The maintenance options for the instance any {} no
max_instance_lifetime The maximum amount of time, in seconds, that an instance can be in service, values must be either equal to 0 or between 86400 and 31536000 seconds number null no
max_size The maximum size of the autoscaling group number null no
metadata_options Customize the metadata options for the instance map(string) {} no
metrics_granularity The granularity to associate with the metrics to collect. The only valid value is 1Minute string null no
min_elb_capacity Setting this causes Terraform to wait for this number of instances to show up healthy in the ELB only on creation. Updates will not wait on ELB instance number changes number null no
min_size The minimum size of the autoscaling group number null no
mixed_instances_policy Configuration block containing settings to define launch targets for Auto Scaling groups any null no
name Name used across the resources created string n/a yes
network_interfaces Customize network interfaces to be attached at instance boot time list(any) [] no
placement The placement of the instance map(string) {} no
placement_group The name of the placement group into which you'll launch your instances, if any string null no
private_dns_name_options The options for the instance hostname. The default values are inherited from the subnet map(string) {} no
protect_from_scale_in Allows setting instance protection. The autoscaling group will not select instances with this setting for termination during scale in events. bool false no
putin_khuylo Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo! bool true no
ram_disk_id The ID of the ram disk string null no
scaling_policies Map of target scaling policy schedule to create any {} no
schedules Map of autoscaling group schedule to create map(any) {} no
security_groups A list of security group IDs to associate list(string) [] no
service_linked_role_arn The ARN of the service-linked role that the ASG will use to call other AWS services string null no
suspended_processes A list of processes to suspend for the Auto Scaling Group. The allowed values are Launch, Terminate, HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, ScheduledActions, AddToLoadBalancer, InstanceRefresh. Note that if you suspend either the Launch or Terminate process types, it can prevent your Auto Scaling Group from functioning properly list(string) [] no
tag_specifications The tags to apply to the resources during launch list(any) [] no
tags A map of tags to assign to resources map(string) {} no
termination_policies A list of policies to decide how the instances in the Auto Scaling Group should be terminated. The allowed values are OldestInstance, NewestInstance, OldestLaunchConfiguration, ClosestToNextInstanceHour, OldestLaunchTemplate, AllocationStrategy, Default list(string) [] no
traffic_source_attachments Map of traffic source attachment definitions to create any {} no
update_default_version Whether to update Default Version each update. Conflicts with default_version bool null no
use_mixed_instances_policy Determines whether to use a mixed instances policy in the autoscaling group or not bool false no
use_name_prefix Determines whether to use name as is or create a unique name beginning with the name as the prefix bool true no
user_data The Base64-encoded user data to provide when launching the instance string null no
vpc_zone_identifier A list of subnet IDs to launch resources in. Subnets automatically determine which availability zones the group will reside. Conflicts with availability_zones list(string) null no
wait_for_capacity_timeout A maximum duration that Terraform should wait for ASG instances to be healthy before timing out. (See also Waiting for Capacity below.) Setting this to '0' causes Terraform to skip all Capacity Waiting behavior. string null no
wait_for_elb_capacity Setting this will cause Terraform to wait for exactly this number of healthy instances in all attached load balancers on both create and update operations. Takes precedence over min_elb_capacity behavior. number null no
warm_pool If this block is configured, add a Warm Pool to the specified Auto Scaling group any {} no

Outputs

Name Description
autoscaling_group_arn The ARN for this AutoScaling Group
autoscaling_group_availability_zones The availability zones of the autoscale group
autoscaling_group_default_cooldown Time between a scaling activity and the succeeding scaling activity
autoscaling_group_desired_capacity The number of Amazon EC2 instances that should be running in the group
autoscaling_group_enabled_metrics List of metrics enabled for collection
autoscaling_group_health_check_grace_period Time after instance comes into service before checking health
autoscaling_group_health_check_type EC2 or ELB. Controls how health checking is done
autoscaling_group_id The autoscaling group id
autoscaling_group_load_balancers The load balancer names associated with the autoscaling group
autoscaling_group_max_size The maximum size of the autoscale group
autoscaling_group_min_size The minimum size of the autoscale group
autoscaling_group_name The autoscaling group name
autoscaling_group_target_group_arns List of Target Group ARNs that apply to this AutoScaling Group
autoscaling_group_vpc_zone_identifier The VPC zone identifier
autoscaling_policy_arns ARNs of autoscaling policies
autoscaling_schedule_arns ARNs of autoscaling group schedules
iam_instance_profile_arn ARN assigned by AWS to the instance profile
iam_instance_profile_id Instance profile's ID
iam_instance_profile_unique Stable and unique string identifying the IAM instance profile
iam_role_arn The Amazon Resource Name (ARN) specifying the IAM role
iam_role_name The name of the IAM role
iam_role_unique_id Stable and unique string identifying the IAM role
launch_template_arn The ARN of the launch template
launch_template_default_version The default version of the launch template
launch_template_id The ID of the launch template
launch_template_latest_version The latest version of the launch template
launch_template_name The name of the launch template

Notes

  • A refresh will not start if launch_template_version is set to $Latest when using an external launch template. To trigger the refresh when the external launch template is changed, set this to latest_version of that aws_launch_template resource.

Authors

Module is maintained by Anton Babenko with help from these awesome contributors.

License

Apache 2 Licensed. See LICENSE for full details.

Additional information for users from Russia and Belarus