terraform-aws-modules Auto Scaling Group

The complete example demonstrates eight distinct configuration patterns for using this module:

• disabled: Completely disables the creation of both the ASG and the associated launch template.
• template only: Creates a launch template without creating an ASG.
• default: Uses the bare minimum information required to create an ASG, relying on default values.
• external: Uses an existing, externally created launch template for the ASG.
• complete: Demonstrates the full range of available module functionality.
• mixed instance: Configures the ASG to use a mixed instance policy.
• warm pool: Demonstrates using warm pools with capacity reservations.
• efa: Demonstrates using Elastic Fabric Adapter (EFA) type network interfaces.

The module allows for conditional resource creation to support different deployment patterns:

• Disable all resources: Set create = false and create_launch_template = false.
• Create only a launch template: Set create = false.
• Use an existing launch template: Set create_launch_template = false and provide the name via launch_template = aws_launch_template.my_launch_template.name.
• Use Mixed Instance Policy: Set use_mixed_instances_policy = true.

Instead of specifying a fixed instance_type, you can use instance_requirements to define the attributes your instances must have.

Note: You cannot use both instance_type and instance_requirements in the same configuration.

Supported requirements include:

• cpu_manufacturers, vcpu_count, memory_mib (with min/max)
• network_bandwidth_gbps, network_interface_count
• accelerator_count, accelerator_types, accelerator_names
• local_storage, local_storage_types, total_local_storage_gb
• ebs_bandwidth_mbps
• allowed_instance_types, excluded_instance_types
• burstable_performance, bare_metal, require_hibernate_support

In v3.x, recreating the ASG was often forced using a random_pet resource and the recreate_asg_when_lc_changes variable. In v4.x, this is replaced by the native AWS instance_refresh functionality.

By default, an instance refresh is triggered by changes to launch_configuration, launch_template, or mixed_instances_policy. To trigger a refresh on additional changes, add the relevant attribute to the triggers list. This allows instances to be replaced without destroying and recreating the entire Auto Scaling Group.

instance_refresh = {
  strategy = "Rolling"
  preferences = {
    min_healthy_percentage = 50
  }
  triggers = ["tag"]
}

To deploy the complete example configuration, which demonstrates various Auto Scaling Group (ASG) setups, execute the standard Terraform workflow. Note that this example may create resources that incur costs; ensure you run terraform destroy when finished.

$ terraform init
$ terraform plan
$ terraform apply

If you enable ignore_desired_capacity_changes = true in your v5.x configuration, you may need to move your existing Auto Scaling Group resource in the Terraform state from the this resource to the idc resource to avoid recreation.

Example Migration Command:

terraform state mv 'module.example.aws_autoscaling_group.this[0]' 'module.example.aws_autoscaling_group.idc[0]'

To use the wrapper directly in Terraform, call the module and provide defaults and items arguments. The items map keys define the unique identifiers for each instance, and the values are the configuration arguments for the root module.

module "wrapper" {
  source = "terraform-aws-modules/autoscaling/aws//wrappers"

  defaults = {
    create = true
    tags = {
      Terraform   = "true"
      Environment = "dev"
    }
  }

  items = {
    my-item = {
      # can be any argument supported by the root module
    }
    my-second-item = {
      # can be any argument supported by the root module
    }
  }
}

When upgrading from version 3.x to 4.x, be aware that due to the default use of name_prefix, most upgrade paths will require recreating the resources provisioned by the module.

Launch Configuration Configuration

If you want the module to create the launch configuration (the most common use case), add these variables:

  lc_name   = "module-will-create"
  use_lc    = true
  create_lc = true

If you are providing an externally created launch configuration, use:

  lc_name   = "externally-created"
  use_lc    = true

  # For module-managed launch configuration
  lc_name   = "module-will-create"
  use_lc    = true
  create_lc = true

  # OR for externally managed launch configuration
  # lc_name   = "externally-created"
  # use_lc    = true