terraform/website/source/docs/providers/aws/r/autoscaling_group.html.mark...

11 KiB

layout page_title sidebar_current description
aws AWS: aws_autoscaling_group docs-aws-resource-autoscaling-group Provides an AutoScaling Group resource.

aws_autoscaling_group

Provides an AutoScaling Group resource.

Example Usage

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

resource "aws_autoscaling_group" "bar" {
  availability_zones        = ["us-east-1a"]
  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}"

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

    notification_metadata = <<EOF
{
  "foo": "bar"
}
EOF

    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
  }

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

Argument Reference

The following arguments are supported:

  • name - (Optional) The name of the auto scaling group. By default generated by Terraform.
  • name_prefix - (Optional) Creates a unique name beginning with the specified prefix. Conflicts with name.
  • max_size - (Required) The maximum size of the auto scale group.
  • min_size - (Required) The minimum size of the auto scale group. (See also Waiting for Capacity below.)
  • availability_zones - (Optional) A list of AZs to launch resources in. Required only if you do not specify any vpc_zone_identifier
  • default_cooldown - (Optional) The amount of time, in seconds, after a scaling activity completes before another scaling activity can start.
  • launch_configuration - (Required) The name of the launch configuration to use.
  • initial_lifecycle_hook - (Optional) One or more Lifecycle Hooks to attach to the autoscaling 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 autoscaling group. For all other use-cases, please use aws_autoscaling_lifecycle_hook resource.
  • health_check_grace_period - (Optional, Default: 300) Time (in seconds) after instance comes into service before checking health.
  • health_check_type - (Optional) "EC2" or "ELB". Controls how health checking is done.
  • desired_capacity - (Optional) The number of Amazon EC2 instances that should be running in the group. (See also Waiting for Capacity below.)
  • force_delete - (Optional) Allows deleting the autoscaling group without waiting for all instances in the pool to terminate. You can force an autoscaling 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.
  • load_balancers (Optional) A list of load balancer names to add to the autoscaling group names.
  • vpc_zone_identifier (Optional) A list of subnet IDs to launch resources in.
  • target_group_arns (Optional) A list of aws_alb_target_group ARNs, for use with Application Load Balancing
  • termination_policies (Optional) A list of policies to decide how the instances in the auto scale group should be terminated. The allowed values are OldestInstance, NewestInstance, OldestLaunchConfiguration, ClosestToNextInstanceHour, Default.
  • suspended_processes - (Optional) 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.
  • tag (Optional) A list of tag blocks. Tags documented below.
  • placement_group (Optional) The name of the placement group into which you'll launch your instances, if any.
  • metrics_granularity - (Optional) The granularity to associate with the metrics to collect. The only valid value is 1Minute. Default is 1Minute.
  • enabled_metrics - (Optional) A list of metrics to collect. The allowed values are GroupMinSize, GroupMaxSize, GroupDesiredCapacity, GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances, GroupTerminatingInstances, GroupTotalInstances.
  • wait_for_capacity_timeout (Default: "10m") 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.
  • min_elb_capacity - (Optional) 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. (See also Waiting for Capacity below.)
  • wait_for_elb_capacity - (Optional) 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.) (See also Waiting for Capacity below.)
  • protect_from_scale_in (Optional) Allows setting instance protection. The autoscaling group will not select instances with this setting for terminination during scale in events.

Tags support the following:

  • key - (Required) Key
  • value - (Required) Value
  • propagate_at_launch - (Required) Enables propagation of the tag to Amazon EC2 instances launched via this ASG

Attributes Reference

The following attributes are exported:

  • id - The autoscaling group id.
  • arn - The ARN for this AutoScaling Group
  • availability_zones - The availability zones of the autoscale group.
  • min_size - The minimum size of the autoscale group
  • max_size - The maximum size of the autoscale group
  • default_cooldown - Time between a scaling activity and the succeeding scaling activity.
  • name - The name of the autoscale group
  • health_check_grace_period - Time after instance comes into service before checking health.
  • health_check_type - "EC2" or "ELB". Controls how health checking is done.
  • desired_capacity -The number of Amazon EC2 instances that should be running in the group.
  • launch_configuration - The launch configuration of the autoscale group
  • vpc_zone_identifier (Optional) - The VPC zone identifier
  • load_balancers (Optional) The load balancer names associated with the autoscaling group.
  • target_group_arns (Optional) list of Target Group ARNs that apply to this AutoScaling Group

~> NOTE: When using ELB as the health_check_type, health_check_grace_period is required.

~> NOTE: Terraform has two types of ways you can add lifecycle hooks - via the initial_lifecycle_hook attribute from this resource, or via the separate aws_autoscaling_lifecycle_hook resource. initial_lifecycle_hook exists here because any lifecycle hooks added with aws_autoscaling_lifecycle_hook will not be added until the autoscaling group has been created, and depending on your capacity settings, after the initial instances have been launched, creating unintended behavior. If you need hooks to run on all instances, add them with initial_lifecycle_hook here, but take care to not duplicate these hooks in aws_autoscaling_lifecycle_hook.

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.

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

AutoScaling Groups can be imported using the name, e.g.

$ terraform import aws_autoscaling_group.web web-asg