Skip to main content
Service Catalog Version 0.85.1Last updated in version 0.85.0

Auto Scaling Group

View SourceRelease Notes

Overview​

This service contains code to deploy Auto Scaling Groups on AWS.

ASG architectureASG architecture

Features​

  • Load balancer (ELB) integration
  • Listener Rules
  • Health checks
  • Zero-downtime rolling deployment
  • Route53 record

Learn​

note

This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!

Under the hood, this is all implemented using Terraform modules from the Gruntwork terraform-aws-asg repo. If you are a subscriber and don’t have access to this repo, email support@gruntwork.io.

  • ASG Documentation: Amazon’s docs for ASG that cover core concepts such as launch templates, launch configuration and auto scaling groups.
  • User Data

Deploy​

Non-production deployment (quick start for learning)​

If you just want to try this repo out for experimenting and learning, check out the following resources:

  • examples/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment​

If you want to deploy this repo in production, check out the following resources:

Reference​

Required​

amistring(required)

The ID of the AMI to run on each instance in the ASG. The AMI needs to have ec2-baseline installed, since by default it will run start_ec2_baseline on the User Data.

ami_filtersobject(required)

Properties on the AMI that can be used to lookup a prebuilt AMI for use with the Bastion Host. You can build the AMI using the Packer template bastion-host.json. Only used if var.ami is null. One of var.ami or ami_filters is required. Set to null if passing the ami ID directly.

object({
    # List of owners to limit the search. Set to null if you do not wish to limit the search by AMI owners.
    owners = list(string)

    # Name/Value pairs to filter the AMI off of. There are several valid keys, for a full reference, check out the
    # documentation for describe-images in the AWS CLI reference
    # (https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html).
    filters = list(object({
      name   = string
      values = list(string)
    }))
  })
instance_typestring(required)

The type of instance to run in the ASG (e.g. t3.medium)

max_sizenumber(required)

The maximum number of EC2 Instances to run in this ASG

min_elb_capacitynumber(required)

Wait for this number of EC2 Instances to show up healthy in the load balancer on creation.

min_sizenumber(required)

The minimum number of EC2 Instances to run in this ASG

namestring(required)

The name for the ASG and all other resources created by these templates.

subnet_idslist(required)

The list of IDs of the subnets in which to deploy ASG. The list must only contain subnets in vpc_id.

list(string)
vpc_idstring(required)

The ID of the VPC in which to deploy the Auto Scaling Group

Optional​

A list of SNS topic ARNs to notify when the health check changes to ALARM, OK, or INSUFFICIENT_DATA state. Note: these SNS topics MUST be in us-east-1! This is because Route 53 only sends CloudWatch metrics to us-east-1, so we must create the alarm in that region, and therefore, can only notify SNS topics in that region.

list(string)
[]
alarms_sns_topic_arnlist(optional)

The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and disk space usage) should send notifications. Also used for the alarms if the Jenkins backup job fails.

list(string)
[]

The CIDR blocks from which to allow access to the ports in server_ports

list(string)
[]

The security group IDs from which to allow access to the ports in server_ports

list(string)
[]

The CIDR blocks from which to allow SSH access

list(string)
[]

The security group IDs from which to allow SSH access

list(string)
[]
cloud_init_partsmap(optional)

Cloud init scripts to run on the ASG instances during boot. See the part blocks in https://www.terraform.io/docs/providers/template/d/cloudinit_config.html for syntax

map(object({
    filename     = string
    content_type = string
    content      = string
  }))
{}

The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for encrypting log data.

null

The number of days to retain log events in the log group. Refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days for all the valid values. When null, the log events are retained forever.

null

Tags to apply on the CloudWatch Log Group, encoded as a map where the keys are tag keys and values are tag values.

map(string)
null
create_route53_entrybool(optional)

Set to true to create a DNS A record in Route 53 for this service.

false
custom_tagslist(optional)

A list of custom tags to apply to the EC2 Instances in this ASG. Each item in this list should be a map with the parameters key, value, and propagate_at_launch.

list(object({
    key                 = string
    value               = string
    propagate_at_launch = bool
  }))
[]

The ARN of the Target Group to which to route traffic.

list(any)
[]
default_userstring(optional)

The default OS user for the service AMI. For example, for AWS Ubuntu AMIs, the default OS user is 'ubuntu'.

ubuntu
desired_capacitynumber(optional)

The desired number of EC2 Instances to run in the ASG initially. Note that auto scaling policies may change this value. If you're using auto scaling policies to dynamically resize the cluster, you should actually leave this value as null.

null
domain_namestring(optional)

The domain name to register in hosted_zone_id (e.g. foo.example.com). Only used if create_route53_entry is true.

null

Set to true to enable several basic CloudWatch alarms around CPU usage, memory usage, and disk space usage. If set to true, make sure to specify SNS topics to send notifications to using alarms_sns_topic_arn.

true

Set to true to add AIM permissions to send logs to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/logs/cloudwatch-log-aggregation-scripts to do log aggregation in CloudWatch.

true

Set to true to add IAM permissions to send custom metrics to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/agents/cloudwatch-agent to get memory and disk metrics in CloudWatch for your Auto Scaling Group

true
enable_fail2banbool(optional)

Enable fail2ban to block brute force log in attempts. Defaults to true

true
enable_ip_lockdownbool(optional)

Enable ip-lockdown to block access to the instance metadata. Defaults to true

true

If set to true, use Route 53 to perform health checks on domain_name.

false
enabled_metricslist(optional)

A list of metrics the ASG should enable for monitoring all instances in a group. The allowed values are GroupMinSize, GroupMaxSize, GroupDesiredCapacity, GroupInServiceInstances, GroupPendingInstances, GroupStandbyInstances, GroupTerminatingInstances, GroupTotalInstances.

list(string)
[]

Since our IAM users are defined in a separate AWS account, this variable is used to specify the ARN of an IAM role that allows ssh-grunt to retrieve IAM group and public SSH key info from that account.

""

Listener rules for a fixed-response action. See comments below for information about the parameters.

map(any)
{}

Listener rules for a forward action that distributes requests among one or more target groups. By default, sends traffic to the target groups created for the ports in server_ports. See comments below for information about the parameters.

{}

Time, in seconds, after an EC2 Instance comes into service before checking health.

300
hosted_zone_idstring(optional)

The ID of the Route 53 Hosted Zone in which to create a DNS A record for the Auto Scaling Group. Optional if create_route53_entry = false.

null
iam_policymap(optional)

An object defining the policy to attach to iam_role_name if the IAM role is going to be created. Accepts a map of objects, where the map keys are sids for IAM policy statements, and the object fields are the resources, actions, and the effect ('Allow' or 'Deny') of the statement. Ignored if iam_role_arn is provided. Leave as null if you do not wish to use IAM role with Service Accounts.

map(object({
    resources = list(string)
    actions   = list(string)
    effect    = string
  }))
null
key_pair_namestring(optional)

The name of a Key Pair that can be used to SSH to the EC2 Instances in the ASG. Set to null if you don't want to enable Key Pair auth.

null
lb_hosted_zone_idstring(optional)

The ID of the Route 53 Hosted Zone in which to create a DNS A record for the Auto Scaling Group. Optional if create_route53_entry = false.

null
listener_arnsmap(optional)

A map of all the listeners on the load balancer. The keys should be the port numbers and the values should be the ARN of the listener for that port.

map(string)
{}
listener_portslist(optional)

The ports the ALB listens on for requests

list(number)
[]
load_balancerslist(optional)

A list of Elastic Load Balancer (ELB) names to associate with this ASG. If you're using the Application Load Balancer (ALB), see target_group_arns.

list(string)
[]
metadata_userslist(optional)

List of users on the ASG EC2 instances that should be permitted access to the EC2 metadata.

list(string)
[]
original_lb_dns_namestring(optional)

The DNS name that was assigned by AWS to the load balancer upon creation

null

Listener rules for a redirect action. See comments below for information about the parameters.

map(any)
{}

The optional external_id to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional AWS profile to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional role_arn to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional session_name to be used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null

The optional path to a credentials file used in the us-east-1 provider block defined in the route53-health-check-alarms module. This module configures its own AWS provider to ensure resources are created in us-east-1.

null
secrets_accesslist(optional)

A list of ARNs of Secrets Manager secrets that the task should have permissions to read. The IAM role for the task will be granted secretsmanager:GetSecretValue for each secret in the list. The ARN can be either the complete ARN, including the randomly generated suffix, or the ARN without the suffix. If the latter, the module will look up the full ARN automatically. This is helpful in cases where you don't yet know the randomly generated suffix because the rest of the ARN is a predictable value.

list(string)
[]
server_portsany(optional)

The ports the EC2 instances listen on for requests. A Target Group will be created for each port and any rules specified in forward_rules will forward traffic to these Target Groups.

{}

When true, precreate the CloudWatch Log Group to use for log aggregation from the EC2 instances. This is useful if you wish to customize the CloudWatch Log Group with various settings such as retention periods and KMS encryption. When false, the CloudWatch agent will automatically create a basic log group to use.

true
ssh_grunt_iam_groupstring(optional)

If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to the instances. To omit this variable, set it to an empty string (do NOT use null, or Terraform will complain).

ssh-grunt-sudo-users
ssh_grunt_iam_group_sudostring(optional)

If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to the instances with sudo permissions. To omit this variable, set it to an empty string (do NOT use null, or Terraform will complain).

ssh-grunt-sudo-users
ssh_portstring(optional)

The port at which SSH will be allowed from allow_ssh_from_cidr_blocks and allow_ssh_security_group_ids

22
tag_asg_id_keystring(optional)

The key for the tag that will be used to associate a unique identifier with this ASG. This identifier will persist between redeploys of the ASG, even though the underlying ASG is being deleted and replaced with a different one.

AsgId
termination_policieslist(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.

list(string)
[]
use_elb_health_checksbool(optional)

Whether or not ELB or ALB health checks should be enabled. If set to true, the load_balancers or target_groups_arns variable should be set depending on the load balancer type you are using. Useful for testing connectivity before health check endpoints are available.

true

When true, all IAM policies will be managed as dedicated policies rather than inline policies attached to the IAM roles. Dedicated managed policies are friendlier to automated policy checkers, which may scan a single resource for findings. As such, it is important to avoid inline policies when targeting compliance with various security standards.

true

A maximum duration that Terraform should wait for the EC2 Instances to be healthy before timing out.

10m