terraform-aws-alb

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

Terraform versions

Terraform 0.12. Pin module version to ~> v4.0. Submit pull-requests to master branch.

Terraform 0.11. Pin module version to ~> v3.0. Submit pull-requests to terraform011 branch.

Assumptions

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.

Why ALB instead of ELB

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.

Usage 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"
  version = "~> 4.0"

  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"
}

Conditional creation

Sometimes you need to have a way to create ALB resources conditionally but Terraform does not allow to use count inside module block, so the solution is to specify argument create_alb.

# This ALB will not be created
module "alb" {
 source = "terraform-aws-modules/alb/aws"

 create_alb = false
 # ... omitted
}

Testing

This module has been packaged with awspec tests through kitchen and kitchen-terraform. To run them:

Install rvm and the ruby version specified in the Gemfile.
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 test from the root of the repo.

Doc generation

Documentation should be modified within main.tf and generated using terraform-docs. Generate them like so:

terraform-docs md ./ | cat -s | sed '${/^$/d;}' > README.md

Contributing

Report issues/questions/feature requests on in the issues section.

Full contributing guidelines are covered here.

IAM Permissions

Testing and using this repo requires a minimum set of IAM permissions. Test permissions are listed in the alb_test_fixture README.

Change log

The changelog captures all important release notes.

Authors

Created and maintained by Brandon O'Connor - brandon@atscale.run. Many thanks to the contributors listed here!

License

MIT Licensed. See LICENSE for full details.

Inputs

Name	Description	Type	Default	Required
create_alb	Controls if the ALB should be created	bool	`true`	no
enable_cross_zone_load_balancing	Indicates whether cross zone load balancing should be enabled in application load balancers.	bool	`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.	bool	`false`	no
enable_http2	Indicates whether HTTP/2 is enabled in application load balancers.	bool	`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(object)	`<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.	number	`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(object)	`<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.	number	`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(object)	`<list>`	no
https_listeners_count	A manually provided count/length of the https_listeners list of maps since the list cannot be computed.	number	`0`	no
idle_timeout	The time in seconds that the connection is allowed to be idle.	number	`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.	bool	`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(string)	-	yes
tags	A map of tags to add to all resources	map(string)	`<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(object)	`<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.	object	`<object>`	no
vpc_id	VPC id where the load balancer and other resources will be deployed.	string	-	yes

Outputs

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.

vpotap/terraform-aws-alb