Skip to main content
Service Catalog Version 0.130.5Last updated in version 0.129.0

Auto Scaling Group

View Source Release 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.

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:

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S ASG-SERVICE MODULE
# ------------------------------------------------------------------------------------------------------

module "asg_service" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/asg-service?ref=v0.130.5"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # 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 = <string>

  # 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
  # var.ami_filters is required. Set to null if passing the ami ID directly.
  ami_filters = <object(
    owners = list(string)
    filters = list(object(
      name   = string
      values = list(string)
    ))
  )>

  # The type of instance to run in the ASG (e.g. t3.medium)
  instance_type = <string>

  # The maximum number of EC2 Instances to run in this ASG
  max_size = <number>

  # Wait for this number of EC2 Instances to show up healthy in the load
  # balancer on creation.
  min_elb_capacity = <number>

  # The minimum number of EC2 Instances to run in this ASG
  min_size = <number>

  # The name for the ASG and all other resources created by these templates.
  name = <string>

  # The list of IDs of the subnets in which to deploy ASG. The list must only
  # contain subnets in var.vpc_id.
  subnet_ids = <list(string)>

  # The ID of the VPC in which to deploy the Auto Scaling Group
  vpc_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # 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.
  alarm_sns_topic_arns_us_east_1 = []

  # 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.
  alarms_sns_topic_arn = []

  # The CIDR blocks from which to allow access to the ports in var.server_ports
  allow_inbound_from_cidr_blocks = []

  # The security group IDs from which to allow access to the ports in
  # var.server_ports
  allow_inbound_from_security_group_ids = []

  # The CIDR blocks from which to allow SSH access
  allow_ssh_from_cidr_blocks = []

  # The security group IDs from which to allow SSH access
  allow_ssh_security_group_ids = []

  # The name of the device to mount the volume on the instance.
  block_device_mappings_device_name = "/dev/xvda"

  # Whether the root volume should be encrypted.
  block_device_mappings_root_volume_encrypted = null

  # The number of IOPS to provision for the root volume.
  block_device_mappings_root_volume_iops = null

  # The size of the root volume in GB.
  block_device_mappings_root_volume_size = null

  # The throughput to provision for the root volume.
  block_device_mappings_root_volume_throughput = null

  # 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
  cloud_init_parts = {}

  # The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for
  # encrypting log data.
  cloudwatch_log_group_kms_key_id = 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.
  cloudwatch_log_group_retention_in_days = null

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

  # Set to true to create a DNS A record in Route 53 for this service.
  create_route53_entry = false

  # 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.
  custom_tags = []

  # Optional override that can be used to specify a custom user data. Note that
  # setting this will disable the module's cloud_init user data. This override
  # is useful for deploying Windows servers that may need custom user data
  # scripts not covered by this module's user_data.sh.
  custom_user_data_override = null

  # The ARN of the Target Group to which to route traffic.
  default_forward_target_group_arns = []

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

  # 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.
  desired_capacity = null

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

  # Specify volumes to attach to the instance besides the volumes specified by
  # the AMI
  ebs_block_device_mappings = {}

  # 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 var.alarms_sns_topic_arn.
  enable_cloudwatch_alarms = 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.
  enable_cloudwatch_log_aggregation = 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
  enable_cloudwatch_metrics = true

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

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

  # If set to true, use Route 53 to perform health checks on var.domain_name.
  enable_route53_health_check = false

  # 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.
  enabled_metrics = []

  # 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.
  external_account_ssh_grunt_role_arn = ""

  # Listener rules for a fixed-response action. See comments below for
  # information about the parameters.
  fixed_response_listener_rules = {}

  # 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 var.server_ports. See comments below for information about
  # the parameters.
  forward_listener_rules = {}

  # Time, in seconds, after an EC2 Instance comes into service before checking
  # health.
  health_check_grace_period = 300

  # The period, in seconds, over which to measure the CPU utilization percentage
  # for the ASG.
  high_asg_cpu_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster CPU utilization
  # percentage above this threshold.
  high_asg_cpu_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_cpu_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the root disk utilization
  # percentage for the ASG.
  high_asg_disk_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster root disk utilization
  # percentage above this threshold.
  high_asg_disk_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_disk_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the Memory utilization
  # percentage for the ASG.
  high_asg_memory_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster Memory utilization
  # percentage above this threshold.
  high_asg_memory_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_memory_utilization_treat_missing_data = "missing"

  # 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.
  hosted_zone_id = null

  # 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.
  iam_policy = null

  # 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.
  key_pair_name = null

  # When true, the launch template will be updated to the default version. When
  # false, the launch template will be updated to the latest version.
  launch_template_update_default_version = true

  # 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.
  lb_hosted_zone_id = null

  # 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.
  listener_arns = {}

  # The ports the ALB listens on for requests
  listener_ports = []

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

  # Whether the metadata service is available. Valid values include enabled or
  # disabled. Defaults to enabled.
  metadata_http_endpoint = "enabled"

  # Desired HTTP PUT response hop limit for instance metadata requests. The
  # larger the number, the further instance metadata requests can travel. Valid
  # values are integer from 1 to 64. Defaults to 1.
  metadata_http_put_response_hop_limit = 1

  # Whether or not the metadata service requires session tokens, also referred
  # to as Instance Metadata Service Version 2 (IMDSv2). Valid values include
  # optional or required. Defaults to optional.
  metadata_http_tokens = "optional"

  # Enables or disables access to instance tags from the instance metadata
  # service. Valid values include enabled or disabled. Defaults to disabled.
  metadata_tags = "disabled"

  # List of users on the ASG EC2 instances that should be permitted access to
  # the EC2 metadata.
  metadata_users = []

  # The DNS name that was assigned by AWS to the load balancer upon creation
  original_lb_dns_name = null

  # Listener rules for a redirect action. See comments below for information
  # about the parameters.
  redirect_listener_rules = {}

  # 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.
  route53_health_check_provider_external_id = 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.
  route53_health_check_provider_profile = 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.
  route53_health_check_provider_role_arn = 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.
  route53_health_check_provider_session_name = 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.
  route53_health_check_provider_shared_credentials_file = null

  # 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.
  secrets_access = []

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

  # 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.
  should_create_cloudwatch_log_group = true

  # 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_iam_group = "ssh-grunt-sudo-users"

  # 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_iam_group_sudo = "ssh-grunt-sudo-users"

  # The port at which SSH will be allowed from var.allow_ssh_from_cidr_blocks
  # and var.allow_ssh_security_group_ids
  ssh_port = 22

  # 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.
  tag_asg_id_key = "AsgId"

  # 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.
  termination_policies = []

  # 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.
  use_elb_health_checks = 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.
  use_managed_iam_policies = true

  # A maximum duration that Terraform should wait for the EC2 Instances to be
  # healthy before timing out.
  wait_for_capacity_timeout = "10m"

}


Reference​

Required​

amistringrequired

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 ami is null. One of 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)
    }))
  })
Details

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

instance_typestringrequired

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

max_sizenumberrequired

The maximum number of EC2 Instances to run in this ASG

min_elb_capacitynumberrequired

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

min_sizenumberrequired

The minimum number of EC2 Instances to run in this ASG

namestringrequired

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

subnet_idslist(string)required

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

vpc_idstringrequired

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

Optional​

alarm_sns_topic_arns_us_east_1list(string)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.

[]
alarms_sns_topic_arnlist(string)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.

[]
allow_inbound_from_cidr_blockslist(string)optional

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

[]

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

[]
allow_ssh_from_cidr_blockslist(string)optional

The CIDR blocks from which to allow SSH access

[]
allow_ssh_security_group_idslist(string)optional

The security group IDs from which to allow SSH access

[]

The name of the device to mount the volume on the instance.

"/dev/xvda"

Whether the root volume should be encrypted.

null

The number of IOPS to provision for the root volume.

null

The size of the root volume in GB.

null

The throughput to provision for the root volume.

null
cloud_init_partsmap(object(…))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
cloudwatch_log_group_tagsmap(string)optional

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

null

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

false
custom_tagslist(object(…))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
  }))
[]
Example
   default = [
     {
       key = "foo"
       value = "bar"
       propagate_at_launch = true
     },
     {
       key = "baz"
       value = "blah"
       propagate_at_launch = true
     }
   ]

Optional override that can be used to specify a custom user data. Note that setting this will disable the module's cloud_init user data. This override is useful for deploying Windows servers that may need custom user data scripts not covered by this module's user_data.sh.

null

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

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
[]
Details

   Each entry in the map supports the following attributes:
   REQUIRED:
   - arn    [string]: The ARN of the target group.
   OPTIONAL:
   - weight [number]: The weight. The range is 0 to 999. Only applies if len(target_group_arns) > 1.

default_userstringoptional

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

"ubuntu"
desired_capacitynumberoptional

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_namestringoptional

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

null
ebs_block_device_mappingsmap(object(…))optional

Specify volumes to attach to the instance besides the volumes specified by the AMI

map(object({
    # Whether the volume should be destroyed on instance termination.
    delete_on_termination = optional(bool)

    # Enables EBS encryption on the volume.
    encrypted = optional(bool)

    # The amount of provisioned IOPS. This must be set with a volume_type of "io1/io2/gp3".
    iops = optional(number)

    # The ARN of the AWS KMS customer master key (CMK) to use when creating the encrypted volume.
    # "encrypted" must be set to true when this is set.
    kms_key_id = optional(string)

    # The throughput to provision for a gp3 volume in MiB/s (specified as an integer, e.g., 500), with a maximum of 1,000 MiB/s.
    throughput = optional(number)

    # The size of the volume in gigabytes.
    volume_size = optional(number)

    # The volume type.
    # Allowed values: standard, gp2, gp3, io1, io2, sc1 or st1.
    volume_type = optional(string)

    # The Snapshot ID to mount.
    snapshot_id = optional(string)

  }))
{}
Details

     Enables EBS encryption on the volume.

Details

     The amount of provisioned IOPS. This must be set with a volume_type of "io1/io2/gp3".

Details

     The ARN of the AWS KMS customer master key (CMK) to use when creating the encrypted volume.
     "encrypted" must be set to true when this is set.

Details

     The throughput to provision for a gp3 volume in MiB/s (specified as an integer, e.g., 500), with a maximum of 1,000 MiB/s.

Details

     The size of the volume in gigabytes.

Details

     The volume type.
     Allowed values: standard, gp2, gp3, io1, io2, sc1 or st1.

Details

     The Snapshot ID to mount.

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_fail2banbooloptional

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

true
enable_ip_lockdownbooloptional

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(string)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.

[]
Example
   enabled_metrics = [
      "GroupDesiredCapacity",
      "GroupInServiceInstances",
      "GroupMaxSize",
      "GroupMinSize",
      "GroupPendingInstances",
      "GroupStandbyInstances",
      "GroupTerminatingInstances",
      "GroupTotalInstances"
    ]

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.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
      "health-path" = {
        priority     = 130
  
        content_type = "text/plain"
        message_body = "HEALTHY"
        status_code  = "200"
  
      Conditions:
      You need to provide *at least ONE* per set of rules. It should contain one of the following:
        host_headers         = ["foo.com", "www.foo.com"]
        path_patterns        = ["/health"]
        source_ips           = ["127.0.0.1"]
        http_request_methods = ["GET"]
        query_strings = [
          {
            key   = "foo"   Key is optional, this can be ommited.
            value = "bar"
          }, {
            value = "hello"
          }
        ]
      }
    }

Details

   Each entry in the map supports the following attributes:
  
   REQUIRED
   - content_type [string]: The content type. Valid values are `text/plain`, `text/css`, `text/html`, `application/javascript`
                            and `application/json`.
  
   OPTIONAL (defaults to value of corresponding module input):
   - priority      [number]       : A value between 1 and 50000. Leaving it unset will automatically set the rule with the next
                                   available priority after currently existing highest rule. This value must be unique for each
                                   listener.
   - listener_arns [list(string)]: A list of listener ARNs to override `var.listener_arns`
   - message_body  [string]      : The message body.
   - status_code   [string]      : The HTTP response code. Valid values are `2XX`, `4XX`, or `5XX`.
  
   Wildcard characters:
   * - matches 0 or more characters
   ? - matches exactly 1 character
   To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).
  
   Conditions (need to specify at least one):
   - path_patterns        [list(string)]     : A list of paths to match (note that "/foo" is different than "/foo/").
                                              Comparison is case sensitive. Wildcard characters supported: * and ?.
                                              It is compared to the path of the URL, not it's query string. To compare
                                              against query string, use the `query_strings` condition.
   - host_headers         [list(string)]     : A list of host header patterns to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?.
   - source_ips           [list(string)]     : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
                                              addresses. Wildcards are not supported. Condition is not satisfied by the
                                              addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
   - query_strings        [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?. Only one pair needs to match for
                                              the condition to be satisfied.
   - http_request_methods [list(string)]     : A list of HTTP request methods or verbs to match. Only allowed characters are
                                              A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
                                              are not supported. AWS recommends that GET and HEAD requests are routed in the
                                              same way because the response to a HEAD request may be cached.

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.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
      "foo" = {
        priority = 120
  
        host_headers         = ["www.foo.com", "*.foo.com"]
        path_patterns        = ["/foo/*"]
        source_ips           = ["127.0.0.1/32"]
        http_request_methods = ["GET"]
        query_strings = [
          {
             key   = "foo"   Key is optional, this can be ommited.
            value = "bar"
          }, {
            value = "hello"
          }
       ]
     }
   }

Details

   Each entry in the map supports the following attributes:
  
   OPTIONAL (defaults to value of corresponding module input):
   - priority          [number]                    : A value between 1 and 50000. Leaving it unset will automatically set
                                                    the rule with the next available priority after currently existing highest
                                                     rule. This value must be unique for each listener.
   - listener_arns     [list(string)]              : A list of listener ARNs to override `var.listener_arns`
   - stickiness        [map(object[Stickiness])]   : Target group stickiness for the rule. Only applies if more than one
                                                    target_group_arn is defined.

Details

   Wildcard characters:
   * - matches 0 or more characters
   ? - matches exactly 1 character
   To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).

Details

   Conditions (need to specify at least one):
   - path_patterns        [list(string)]     : A list of paths to match (note that "/foo" is different than "/foo/").
                                              Comparison is case sensitive. Wildcard characters supported: * and ?.
                                              It is compared to the path of the URL, not it's query string. To compare
                                              against query string, use the `query_strings` condition.
   - host_headers         [list(string)]     : A list of host header patterns to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?.
   - source_ips           [list(string)]     : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
                                              addresses. Wildcards are not supported. Condition is not satisfied by the
                                              addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
   - query_strings        [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?. Only one pair needs to match for
                                              the condition to be satisfied.
   - http_request_methods [list(string)]     : A list of HTTP request methods or verbs to match. Only allowed characters are
                                              A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
                                              are not supported. AWS recommends that GET and HEAD requests are routed in the
                                              same way because the response to a HEAD request may be cached.

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

300

The period, in seconds, over which to measure the CPU utilization percentage for the ASG.

60

Trigger an alarm if the ASG has an average cluster CPU utilization percentage above this threshold.

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

The period, in seconds, over which to measure the root disk utilization percentage for the ASG.

60

Trigger an alarm if the ASG has an average cluster root disk utilization percentage above this threshold.

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"

The period, in seconds, over which to measure the Memory utilization percentage for the ASG.

60

Trigger an alarm if the ASG has an average cluster Memory utilization percentage above this threshold.

90

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

"missing"
hosted_zone_idstringoptional

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(object(…))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
Example
   iam_policy = {
     S3Access = {
       actions = ["s3:*"]
       resources = ["arn:aws:s3:::mybucket"]
       effect = "Allow"
     },
     SecretsManagerAccess = {
       actions = ["secretsmanager:GetSecretValue"],
       resources = ["arn:aws:secretsmanager:us-east-1:0123456789012:secret:mysecert"]
       effect = "Allow"
     }
   }

key_pair_namestringoptional

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

When true, the launch template will be updated to the default version. When false, the launch template will be updated to the latest version.

true
lb_hosted_zone_idstringoptional

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(string)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.

{}
listener_portslist(number)optional

The ports the ALB listens on for requests

[]
load_balancerslist(string)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.

[]

Whether the metadata service is available. Valid values include enabled or disabled. Defaults to enabled.

"enabled"

Desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel. Valid values are integer from 1 to 64. Defaults to 1.

1
metadata_http_tokensstringoptional

Whether or not the metadata service requires session tokens, also referred to as Instance Metadata Service Version 2 (IMDSv2). Valid values include optional or required. Defaults to optional.

"optional"
metadata_tagsstringoptional

Enables or disables access to instance tags from the instance metadata service. Valid values include enabled or disabled. Defaults to disabled.

"disabled"
metadata_userslist(string)optional

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

[]
original_lb_dns_namestringoptional

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

null
redirect_listener_rulesmap(any)optional

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

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
    {
      "old-website" = {
        priority = 120
        port     = 443
        protocol = "HTTPS"
  
        status_code = "HTTP_301"
        host  = "gruntwork.in"
        path  = "/signup"
        query = "foo"
  
      Conditions:
        host_headers         = ["foo.com", "www.foo.com"]
        path_patterns        = ["/health"]
        source_ips           = ["127.0.0.1"]
        http_request_methods = ["GET"]
        query_strings = [
          {
            key   = "foo"   Key is optional, this can be ommited.
            value = "bar"
          }, {
            value = "hello"
          }
        ]
      }
    }

Details

   Each entry in the map supports the following attributes:
  
   OPTIONAL (defaults to value of corresponding module input):
   - priority       [number]: A value between 1 and 50000. Leaving it unset will automatically set the rule with the next
                           available priority after currently existing highest rule. This value must be unique for each
                           listener.
   - listener_arns [list(string)]: A list of listener ARNs to override `var.listener_arns`
   - status_code   [string]: The HTTP redirect code. The redirect is either permanent `HTTP_301` or temporary `HTTP_302`.
  
   The URI consists of the following components: `protocol://hostname:port/path?query`. You must modify at least one of
   the following components to avoid a redirect loop: protocol, hostname, port, or path. Any components that you do not
   modify retain their original values.
   - host        [string]: The hostname. The hostname can contain {host}.
   - path        [string]: The absolute path, starting with the leading "/". The path can contain `host`, `path`, and `port`.
   - port        [string]: The port. Specify a value from 1 to 65525.
   - protocol    [string]: The protocol. Valid values are `HTTP` and `HTTPS`. You cannot redirect HTTPS to HTTP.
   - query       [string]: The query params. Do not include the leading "?".
  
   Wildcard characters:
   * - matches 0 or more characters
   ? - matches exactly 1 character
   To search for a literal '*' or '?' character in a query string, escape the character with a backslash (\).
  
   Conditions (need to specify at least one):
   - path_patterns        [list(string)]     : A list of paths to match (note that "/foo" is different than "/foo/").
                                              Comparison is case sensitive. Wildcard characters supported: * and ?.
                                              It is compared to the path of the URL, not it's query string. To compare
                                              against query string, use the `query_strings` condition.
   - host_headers         [list(string)]     : A list of host header patterns to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?.
   - source_ips           [list(string)]     : A list of IP CIDR notations to match. You can use both IPv4 and IPv6
                                              addresses. Wildcards are not supported. Condition is not satisfied by the
                                              addresses in the `X-Forwarded-For` header, use `http_headers` condition instead.
   - query_strings        [list(map(string))]: Query string pairs or values to match. Comparison is case insensitive.
                                              Wildcard characters supported: * and ?. Only one pair needs to match for
                                              the condition to be satisfied.
   - http_request_methods [list(string)]     : A list of HTTP request methods or verbs to match. Only allowed characters are
                                              A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards
                                              are not supported. AWS recommends that GET and HEAD requests are routed in the
                                              same way because the response to a HEAD request may be cached.

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(string)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.

[]
server_portsanyoptional

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.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
   server_ports = {
     "default-http" = {
       server_port            = "8080"
       protocol               = "HTTP"
       health_check_path      = "/health"
       r53_health_check_path  = "/health"
       enable_lb_health_check = false
     }
   }

Details

   Each entry in the map supports the following attributes:
  
   REQUIRED:
   - server_port        number      : The port of the endpoint to be checked (e.g. 80).
  
   OPTIONAL (defaults to value of corresponding module input):
   - target_group_name                   string      : A unique name to use for the corresponding target group. If
                                                       omitted, defaults to "SERVICE_NAME-ENTRY_KEY" where SERVICE_NAME
                                                       corresponds to var.name and ENTRY_KEY corresponds to the map key
                                                       for this server port entry.
   - tags                                map(string) : A map of tags to apply to the metric alarm. The key is the tag
                                                       name and the value is the tag value.
   - protocol                            string      : The protocol to use for health checks. See:
                                                       https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_target_groupprotocol
   - health_check_path                   string      : The path that the health check should use for requests (e.g. /health or /status).
   - r53_health_check_path               string      : The path that you want Amazon Route 53 to request when
                                                         performing health checks (e.g. /status). Defaults to "/".
   - r53_health_check_type               string      : The protocol to use when performing health checks. Valid
                                                       values are HTTP, HTTPS, HTTP_STR_MATCH, HTTPS_STR_MATCH,
                                                       TCP, CALCULATED and CLOUDWATCH_METRIC. Defaults to HTTP.
   - r53_health_check_failure_threshold  number      : The number of consecutive health checks that must pass
                                                       or fail for the health check to declare your site up or
                                                       down. Defaults to 2.
   - r53_health_check_request_interval   number      : The number of seconds between health checks. Defaults to 30.
  
   - enable_lb_health_check  bool   : Set to false if you want to disable Target Group health's check.
                                      Defaults to true.
   - lb_healthy_threshold    number : The number of consecutive health checks *successes* required before
                                      considering an unhealthy target healthy. Defaults to 3.
   - lb_unhealthy_threshold  number : The number of consecutive health check *failures* required before
                                      considering the target unhealthy. Defaults to 3.
   - lb_request_interval     number : The approximate amount of time, in seconds, between health checks
                                      of an individual target. Defaults to 30.
   - lb_timeout              number : The amount of time, in seconds, during which no response means a
                                      failed health check. Defaults to 10.

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_groupstringoptional

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"

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_portstringoptional

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

22
tag_asg_id_keystringoptional

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(string)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.

[]

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"