Resource: aws_autoscaling_group

Provides an Auto Scaling Group resource.

Hands-on: Try the Manage AWS Auto Scaling Groups tutorial on HashiCorp Learn.

Example Usage

resource "aws_placement_group" "test" {
  name     = "test"
  strategy = "cluster"
}

resource "aws_autoscaling_group" "bar" {
  name                      = "foobar3-terraform-test"
  max_size                  = 5
  min_size                  = 2
  health_check_grace_period = 300
  health_check_type         = "ELB"
  desired_capacity          = 4
  force_delete              = true
  placement_group           = aws_placement_group.test.id
  launch_configuration      = aws_launch_configuration.foobar.name
  vpc_zone_identifier       = [aws_subnet.example1.id, aws_subnet.example2.id]

  instance_maintenance_policy {
    min_healthy_percentage = 90
    max_healthy_percentage = 120
  }

  initial_lifecycle_hook {
    name                 = "foobar"
    default_result       = "CONTINUE"
    heartbeat_timeout    = 2000
    lifecycle_transition = "autoscaling:EC2_INSTANCE_LAUNCHING"

    notification_metadata = jsonencode({
      foo = "bar"
    })

    notification_target_arn = "arn:aws:sqs:us-east-1:444455556666:queue1*"
    role_arn                = "arn:aws:iam::123456789012:role/S3Access"
  }

  tag {
    key                 = "foo"
    value               = "bar"
    propagate_at_launch = true
  }

  timeouts {
    delete = "15m"
  }

  tag {
    key                 = "lorem"
    value               = "ipsum"
    propagate_at_launch = false
  }
}

With Latest Version Of Launch Template

resource "aws_launch_template" "foobar" {
  name_prefix   = "foobar"
  image_id      = "ami-1a2b3c"
  instance_type = "t2.micro"
}

resource "aws_autoscaling_group" "bar" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 1
  min_size           = 1

  launch_template {
    id      = aws_launch_template.foobar.id
    version = "$Latest"
  }
}

Mixed Instances Policy

resource "aws_launch_template" "example" {
  name_prefix   = "example"
  image_id      = data.aws_ami.example.id
  instance_type = "c5.large"
}

resource "aws_autoscaling_group" "example" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 1
  min_size           = 1

  mixed_instances_policy {
    launch_template {
      launch_template_specification {
        launch_template_id = aws_launch_template.example.id
      }

      override {
        instance_type     = "c4.large"
        weighted_capacity = "3"
      }

      override {
        instance_type     = "c3.large"
        weighted_capacity = "2"
      }
    }
  }
}

Mixed Instances Policy with Spot Instances and Capacity Rebalance

resource "aws_launch_template" "example" {
  name_prefix   = "example"
  image_id      = data.aws_ami.example.id
  instance_type = "c5.large"
}

resource "aws_autoscaling_group" "example" {
  capacity_rebalance  = true
  desired_capacity    = 12
  max_size            = 15
  min_size            = 12
  vpc_zone_identifier = [aws_subnet.example1.id, aws_subnet.example2.id]

  mixed_instances_policy {
    instances_distribution {
      on_demand_base_capacity                  = 0
      on_demand_percentage_above_base_capacity = 25
      spot_allocation_strategy                 = "capacity-optimized"
    }

    launch_template {
      launch_template_specification {
        launch_template_id = aws_launch_template.example.id
      }

      override {
        instance_type     = "c4.large"
        weighted_capacity = "3"
      }

      override {
        instance_type     = "c3.large"
        weighted_capacity = "2"
      }
    }
  }
}

Mixed Instances Policy with Instance level LaunchTemplateSpecification Overrides

When using a diverse instance set, some instance types might require a launch template with configuration values unique to that instance type such as a different AMI (Graviton2), architecture specific user data script, different EBS configuration, or different networking configuration.

resource "aws_launch_template" "example" {
  name_prefix   = "example"
  image_id      = data.aws_ami.example.id
  instance_type = "c5.large"
}

resource "aws_launch_template" "example2" {
  name_prefix = "example2"
  image_id    = data.aws_ami.example2.id
}

resource "aws_autoscaling_group" "example" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 1
  min_size           = 1

  mixed_instances_policy {
    launch_template {
      launch_template_specification {
        launch_template_id = aws_launch_template.example.id
      }

      override {
        instance_type     = "c4.large"
        weighted_capacity = "3"
      }

      override {
        instance_type = "c6g.large"
        launch_template_specification {
          launch_template_id = aws_launch_template.example2.id
        }
        weighted_capacity = "2"
      }
    }
  }
}

Mixed Instances Policy with Attribute-based Instance Type Selection

As an alternative to manually choosing instance types when creating a mixed instances group, you can specify a set of instance attributes that describe your compute requirements.

resource "aws_launch_template" "example" {
  name_prefix   = "example"
  image_id      = data.aws_ami.example.id
  instance_type = "c5.large"
}

resource "aws_autoscaling_group" "example" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 1
  min_size           = 1

  mixed_instances_policy {
    launch_template {
      launch_template_specification {
        launch_template_id = aws_launch_template.example.id
      }

      override {
        instance_requirements {
          memory_mib {
            min = 1000
          }

          vcpu_count {
            min = 4
          }
        }
      }
    }
  }
}

Dynamic tagging

variable "extra_tags" {
  default = [
    {
      key                 = "Foo"
      value               = "Bar"
      propagate_at_launch = true
    },
    {
      key                 = "Baz"
      value               = "Bam"
      propagate_at_launch = true
    },
  ]
}

resource "aws_autoscaling_group" "test" {
  name                 = "foobar3-terraform-test"
  max_size             = 5
  min_size             = 2
  launch_configuration = aws_launch_configuration.foobar.name
  vpc_zone_identifier  = [aws_subnet.example1.id, aws_subnet.example2.id]

  tag {
    key                 = "explicit1"
    value               = "value1"
    propagate_at_launch = true
  }
  tag {
    key                 = "explicit2"
    value               = "value2"
    propagate_at_launch = true
  }

  dynamic "tag" {
    for_each = var.extra_tags
    content {
      key                 = tag.value.key
      propagate_at_launch = tag.value.propagate_at_launch
      value               = tag.value.value
    }
  }
}

Automatically refresh all instances after the group is updated

resource "aws_autoscaling_group" "example" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 2
  min_size           = 1

  launch_template {
    id      = aws_launch_template.example.id
    version = aws_launch_template.example.latest_version
  }

  tag {
    key                 = "Key"
    value               = "Value"
    propagate_at_launch = true
  }

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

data "aws_ami" "example" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn-ami-hvm-*-x86_64-gp2"]
  }
}

resource "aws_launch_template" "example" {
  image_id      = data.aws_ami.example.id
  instance_type = "t3.nano"
}

Auto Scaling group with Warm Pool

resource "aws_launch_template" "example" {
  name_prefix   = "example"
  image_id      = data.aws_ami.example.id
  instance_type = "c5.large"
}

resource "aws_autoscaling_group" "example" {
  availability_zones = ["us-east-1a"]
  desired_capacity   = 1
  max_size           = 5
  min_size           = 1

  warm_pool {
    pool_state                  = "Hibernated"
    min_size                    = 1
    max_group_prepared_capacity = 10

    instance_reuse_policy {
      reuse_on_scale_in = true
    }
  }
}

Auto Scaling group with Traffic Sources

resource "aws_autoscaling_group" "test" {
  vpc_zone_identifier = aws_subnet.test.id
  max_size            = 1
  min_size            = 1

  force_delete = true
  dynamic "traffic_source" {
    for_each = aws_vpclattice_target_group.test[*]
    content {
      identifier = traffic_source.value.arn
      type       = "vpc-lattice"
    }
  }

}

Argument Reference

This resource supports the following arguments:

launch_template

The top-level launch_template block supports the following:

mixed_instances_policy

mixed_instances_policy instances_distribution

This configuration block supports the following:

mixed_instances_policy launch_template

This configuration block supports the following:

mixed_instances_policy launch_template launch_template_specification

This configuration block supports the following:

mixed_instances_policy launch_template override

This configuration block supports the following:

mixed_instances_policy launch_template override instance_requirements

This configuration block supports the following:

  Valid names:
    * amazon-web-services
    * amd
    * nvidia
    * xilinx
  Valid names:
    * a100            - NVIDIA A100 GPUs
    * v100            - NVIDIA V100 GPUs
    * k80             - NVIDIA K80 GPUs
    * t4              - NVIDIA T4 GPUs
    * m60             - NVIDIA M60 GPUs
    * radeon-pro-v520 - AMD Radeon Pro V520 GPUs
    * vu9p            - Xilinx VU9P FPGAs
  Valid types:
    * fpga
    * gpu
    * inference
  Valid names:
    * amazon-web-services
    * amd
    * intel
  Valid names:
    * current  - Recommended for best performance.
    * previous - For existing applications optimized for older instance types.
  Value names:
    * hdd - hard disk drive
    * ssd - solid state drive

tag

The tag attribute accepts exactly one tag declaration with the following fields:

To declare multiple tags, additional tag blocks can be specified.

instance_refresh

This configuration block supports the following:

warm_pool

This configuration block supports the following:

instance_maintenance_policy

This configuration block supports the following:

traffic_source

instance_reuse_policy

This configuration block supports the following:

Attribute Reference

This resource exports the following attributes in addition to the arguments above:

Timeouts

Configuration options:

Waiting for Capacity

A newly-created ASG is initially empty and begins to scale to min_size (or desired_capacity, if specified) by launching instances using the provided Launch Configuration. These instances take time to launch and boot.

On ASG Update, changes to these values also take time to result in the target number of instances providing service.

Terraform provides two mechanisms to help consistently manage ASG scale up time across dependent resources.

Waiting for ASG Capacity

The first is default behavior. Terraform waits after ASG creation for min_size (or desired_capacity, if specified) healthy instances to show up in the ASG before continuing.

If min_size or desired_capacity are changed in a subsequent update, Terraform will also wait for the correct number of healthy instances before continuing.

Terraform considers an instance "healthy" when the ASG reports HealthStatus: "Healthy" and LifecycleState: "InService". See the AWS AutoScaling Docs for more information on an ASG's lifecycle.

Terraform will wait for healthy instances for up to wait_for_capacity_timeout. If ASG creation is taking more than a few minutes, it's worth investigating for scaling activity errors, which can be caused by problems with the selected Launch Configuration.

Setting wait_for_capacity_timeout to "0" disables ASG Capacity waiting.

Waiting for ELB Capacity

The second mechanism is optional, and affects ASGs with attached ELBs specified via the load_balancers attribute or with ALBs specified with target_group_arns.

The min_elb_capacity parameter causes Terraform to wait for at least the requested number of instances to show up "InService" in all attached ELBs during ASG creation. It has no effect on ASG updates.

If wait_for_elb_capacity is set, Terraform will wait for exactly that number of Instances to be "InService" in all attached ELBs on both creation and updates.

These parameters can be used to ensure that service is being provided before Terraform moves on. If new instances don't pass the ELB's health checks for any reason, the Terraform apply will time out, and the ASG will be marked as tainted (i.e., marked to be destroyed in a follow up run).

As with ASG Capacity, Terraform will wait for up to wait_for_capacity_timeout for the proper number of instances to be healthy.

Troubleshooting Capacity Waiting Timeouts

If ASG creation takes more than a few minutes, this could indicate one of a number of configuration problems. See the AWS Docs on Load Balancer Troubleshooting for more information.

Import

In Terraform v1.5.0 and later, use an import block to import Auto Scaling Groups using the name. For example:

import {
  to = aws_autoscaling_group.web
  id = "web-asg"
}

Using terraform import, import Auto Scaling Groups using the name. For example:

% terraform import aws_autoscaling_group.web web-asg