A Terraform module containing common configurations for an AWS Application Load Balancer (ALB) running over HTTP/HTTPS. Available through the Terraform registry.
| Branch | Build status |
|---|---|
| master |  |
- You want to create a set of resources around an application load balancer: namely associated target groups and listeners.
- You've created a Virtual Private Cloud (VPC) and subnets where you intend to put this ALB.
- You have one or more security groups to attach to the ALB.
- Additionally, if you plan to use an HTTPS listener, the ARN of an SSL certificate is required.
The module supports both (mutually exclusive):
- Internal ALBs
- External ALBs
It's recommended you use this module with terraform-aws-vpc, terraform-aws-security-group, and terraform-aws-autoscaling.
Note:
It's strongly recommended that the autoscaling module is instantiated in the same
state as the ALB module as in flight changes to active target groups need to be propagated
to the ASG immediately or will result in failure. The value of target_group[n][name] also must change any time there are modifications to existing target_groups.
ALB has the ability to replace what several ELBs can do by routing based on URI matchers. Additionally, operating at layer 7 opens the ability to shape traffic using WAF. AWS's documentation has a more exhaustive set of reasons. Alternatively, if using ALB with ECS look no further than the HashiCorp example.
A full example leveraging other community modules is contained in the examples/alb_test_fixture directory. Here's the gist of using it via the Terraform registry:
module "alb" {
source = "terraform-aws-modules/alb/aws"
load_balancer_name = "my-alb"
security_groups = ["sg-edcd9784", "sg-edcd9785"]
log_bucket_name = "logs-us-east-2-123456789012"
log_location_prefix = "my-alb-logs"
subnets = ["subnet-abcde012", "subnet-bcde012a"]
tags = "${map("Environment", "test")}"
vpc_id = "vpc-abcde012"
https_listeners = "${list(map("certificate_arn", "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012", "port", 443))}"
https_listeners_count = "1"
http_tcp_listeners = "${list(map("port", "80", "protocol", "HTTP"))}"
http_tcp_listeners_count = "1"
target_groups = "${list(map("name", "foo", "backend_protocol", "HTTP", "backend_port", "80"))}"
target_groups_count = "1"
}This module has been packaged with awspec tests through kitchen and kitchen-terraform. To run them:
-
Install bundler and the gems from our Gemfile:
gem install bundler && bundle install -
Ensure your AWS environment is configured (i.e. credentials and region) for test and set TF_VAR_region to a valid AWS region (e.g.
export TF_VAR_region=${AWS_REGION}). -
Test using
bundle exec kitchen testfrom the root of the repo.
Documentation should be modified within main.tf and generated using terraform-docs.
Generate them like so:
terraform-docs md ./ | cat -s | sed '${/^$/d;}' > README.mdReport issues/questions/feature requests on in the issues section.
Full contributing guidelines are covered here.
Testing and using this repo requires a minimum set of IAM permissions. Test permissions are listed in the alb_test_fixture README.
The changelog captures all important release notes.
Created and maintained by Brandon O'Connor - [email protected]. Many thanks to the contributors listed here!
MIT Licensed. See LICENSE for full details.
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| enable_cross_zone_load_balancing | Indicates whether cross zone load balancing should be enabled in application load balancers. | string | false |
no |
| enable_deletion_protection | If true, deletion of the load balancer will be disabled via the AWS API. This will prevent Terraform from deleting the load balancer. Defaults to false. | string | false |
no |
| enable_http2 | Indicates whether HTTP/2 is enabled in application load balancers. | string | true |
no |
| extra_ssl_certs | A list of maps describing any extra SSL certificates to apply to the HTTPS listeners. Required key/values: certificate_arn, https_listener_index (the index of the listener within https_listeners which the cert applies toward). | list | <list> |
no |
| extra_ssl_certs_count | A manually provided count/length of the extra_ssl_certs list of maps since the list cannot be computed. | string | 0 |
no |
| http_tcp_listeners | A list of maps describing the HTTPS listeners for this ALB. Required key/values: port, protocol. Optional key/values: target_group_index (defaults to 0) | list | <list> |
no |
| http_tcp_listeners_count | A manually provided count/length of the http_tcp_listeners list of maps since the list cannot be computed. | string | 0 |
no |
| https_listeners | A list of maps describing the HTTPS listeners for this ALB. Required key/values: port, certificate_arn. Optional key/values: ssl_policy (defaults to ELBSecurityPolicy-2016-08), target_group_index (defaults to 0) | list | <list> |
no |
| https_listeners_count | A manually provided count/length of the https_listeners list of maps since the list cannot be computed. | string | 0 |
no |
| idle_timeout | The time in seconds that the connection is allowed to be idle. | string | 60 |
no |
| ip_address_type | The type of IP addresses used by the subnets for your load balancer. The possible values are ipv4 and dualstack. | string | ipv4 |
no |
| listener_ssl_policy_default | The security policy if using HTTPS externally on the load balancer. See. | string | ELBSecurityPolicy-2016-08 |
no |
| load_balancer_create_timeout | Timeout value when creating the ALB. | string | 10m |
no |
| load_balancer_delete_timeout | Timeout value when deleting the ALB. | string | 10m |
no |
| load_balancer_is_internal | Boolean determining if the load balancer is internal or externally facing. | string | false |
no |
| load_balancer_name | The resource name and Name tag of the load balancer. | string | - | yes |
| load_balancer_update_timeout | Timeout value when updating the ALB. | string | 10m |
no |
| log_bucket_name | S3 bucket (externally created) for storing load balancer access logs. Required if logging_enabled is true. | string | `` | no |
| log_location_prefix | S3 prefix within the log_bucket_name under which logs are stored. | string | `` | no |
| logging_enabled | Controls if the ALB will log requests to S3. | string | true |
no |
| security_groups | The security groups to attach to the load balancer. e.g. ["sg-edcd9784","sg-edcd9785"] | list | - | yes |
| subnets | A list of subnets to associate with the load balancer. e.g. ['subnet-1a2b3c4d','subnet-1a2b3c4e','subnet-1a2b3c4f'] | list | - | yes |
| tags | A map of tags to add to all resources | map | <map> |
no |
| target_groups | A list of maps containing key/value pairs that define the target groups to be created. Order of these maps is important and the index of these are to be referenced in listener definitions. Required key/values: name, backend_protocol, backend_port. Optional key/values are in the target_groups_defaults variable. | list | <list> |
no |
| target_groups_count | A manually provided count/length of the target_groups list of maps since the list cannot be computed. | string | 0 |
no |
| target_groups_defaults | Default values for target groups as defined by the list of maps. | map | <map> |
no |
| vpc_id | VPC id where the load balancer and other resources will be deployed. | string | - | yes |
| Name | Description |
|---|---|
| dns_name | The DNS name of the load balancer. |
| http_tcp_listener_arns | The ARN of the TCP and HTTP load balancer listeners created. |
| http_tcp_listener_ids | The IDs of the TCP and HTTP load balancer listeners created. |
| https_listener_arns | The ARNs of the HTTPS load balancer listeners created. |
| https_listener_ids | The IDs of the load balancer listeners created. |
| load_balancer_arn_suffix | ARN suffix of our load balancer - can be used with CloudWatch. |
| load_balancer_id | The ID and ARN of the load balancer we created. |
| load_balancer_zone_id | The zone_id of the load balancer to assist with creating DNS records. |
| target_group_arn_suffixes | ARN suffixes of our target groups - can be used with CloudWatch. |
| target_group_arns | ARNs of the target groups. Useful for passing to your Auto Scaling group. |
| target_group_names | Name of the target group. Useful for passing to your CodeDeploy Deployment Group. |