README.md

AWS Auto Scaling Group (ASG) Terraform module

Terraform module which creates Auto Scaling resources on AWS.

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.82.1

Providers

Name	Version
aws	>= 5.82.1

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_zone_distribution	A map of configuration for capacity distribution across availability zones	any	{}	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

• Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
• Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
• Putin khuylo!