Awesome
AWS Application and Network Load Balancer (ALB & NLB) Terraform module
Terraform module which creates Application and Network Load Balancer resources on AWS.
Usage
When you're using ALB Listener rules, make sure that every rule's actions
block ends in a forward
, redirect
, or fixed-response
action so that every rule will resolve to some sort of an HTTP response. Checkout the AWS documentation for more information.
Application Load Balancer
HTTP to HTTPS redirect
module "alb" {
source = "terraform-aws-modules/alb/aws"
name = "my-alb"
vpc_id = "vpc-abcde012"
subnets = ["subnet-abcde012", "subnet-bcde012a"]
# Security Group
security_group_ingress_rules = {
all_http = {
from_port = 80
to_port = 80
ip_protocol = "tcp"
description = "HTTP web traffic"
cidr_ipv4 = "0.0.0.0/0"
}
all_https = {
from_port = 443
to_port = 443
ip_protocol = "tcp"
description = "HTTPS web traffic"
cidr_ipv4 = "0.0.0.0/0"
}
}
security_group_egress_rules = {
all = {
ip_protocol = "-1"
cidr_ipv4 = "10.0.0.0/16"
}
}
access_logs = {
bucket = "my-alb-logs"
}
listeners = {
ex-http-https-redirect = {
port = 80
protocol = "HTTP"
redirect = {
port = "443"
protocol = "HTTPS"
status_code = "HTTP_301"
}
}
ex-https = {
port = 443
protocol = "HTTPS"
certificate_arn = "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012"
forward = {
target_group_key = "ex-instance"
}
}
}
target_groups = {
ex-instance = {
name_prefix = "h1"
protocol = "HTTP"
port = 80
target_type = "instance"
target_id = "i-0f6d38a07d50d080f"
}
}
tags = {
Environment = "Development"
Project = "Example"
}
}
Cognito authentication
module "alb" {
source = "terraform-aws-modules/alb/aws"
# Truncated for brevity ...
listeners = {
ex-http-https-redirect = {
port = 80
protocol = "HTTP"
redirect = {
port = "443"
protocol = "HTTPS"
status_code = "HTTP_301"
}
}
ex-cognito = {
port = 444
protocol = "HTTPS"
certificate_arn = "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012"
authenticate_cognito = {
authentication_request_extra_params = {
display = "page"
prompt = "login"
}
on_unauthenticated_request = "authenticate"
session_cookie_name = "session-${local.name}"
session_timeout = 3600
user_pool_arn = "arn:aws:cognito-idp:us-west-2:123456789012:userpool/us-west-2_abcdefghi"
user_pool_client_id = "us-west-2_fak3p001B"
user_pool_domain = "https://fak3p001B.auth.us-west-2.amazoncognito.com"
}
forward = {
target_group_key = "ex-instance"
}
rules = {
ex-oidc = {
priority = 2
actions = [
{
type = "authenticate-oidc"
authentication_request_extra_params = {
display = "page"
prompt = "login"
}
authorization_endpoint = "https://foobar.com/auth"
client_id = "client_id"
client_secret = "client_secret"
issuer = "https://foobar.com"
token_endpoint = "https://foobar.com/token"
user_info_endpoint = "https://foobar.com/user_info"
},
{
type = "forward"
target_group_key = "ex-instance"
}
]
}
}
}
}
}
Cognito authentication on certain paths, redirects for others
module "alb" {
source = "terraform-aws-modules/alb/aws"
# Truncated for brevity ...
listeners = {
https = {
port = 443
protocol = "HTTPS"
certificate_arn = "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012"
forward = {
target_group_key = "instance"
}
rules = {
redirect = {
priority = 5000
actions = [{
type = "redirect"
status_code = "HTTP_302"
host = "www.youtube.com"
path = "/watch"
query = "v=dQw4w9WgXcQ"
protocol = "HTTPS"
}]
conditions = [{
path_pattern = {
values = ["/onboarding", "/docs"]
}
}]
}
cognito = {
priority = 2
actions = [
{
type = "authenticate-cognito"
user_pool_arn = "arn:aws:cognito-idp::123456789012:userpool/test-pool"
user_pool_client_id = "6oRmFiS0JHk="
user_pool_domain = "test-domain-com"
},
{
type = "forward"
target_group_key = "instance"
}
]
conditions = [{
path_pattern = {
values = ["/protected-route", "private/*"]
}
}]
}
}
}
}
target_groups = {
instance = {
name_prefix = "default"
protocol = "HTTPS"
port = 443
target_type = "instance"
target_id = "i-0f6d38a07d50d080f"
}
}
}
Network Load Balancer
TCP_UDP, UDP, TCP and TLS listeners
module "nlb" {
source = "terraform-aws-modules/alb/aws"
name = "my-nlb"
load_balancer_type = "network"
vpc_id = "vpc-abcde012"
subnets = ["subnet-abcde012", "subnet-bcde012a"]
# Security Group
enforce_security_group_inbound_rules_on_private_link_traffic = "on"
security_group_ingress_rules = {
all_http = {
from_port = 80
to_port = 82
ip_protocol = "tcp"
description = "HTTP web traffic"
cidr_ipv4 = "0.0.0.0/0"
}
all_https = {
from_port = 443
to_port = 445
ip_protocol = "tcp"
description = "HTTPS web traffic"
cidr_ipv4 = "0.0.0.0/0"
}
}
security_group_egress_rules = {
all = {
ip_protocol = "-1"
cidr_ipv4 = "10.0.0.0/16"
}
}
access_logs = {
bucket = "my-nlb-logs"
}
listeners = {
ex-tcp-udp = {
port = 81
protocol = "TCP_UDP"
forward = {
target_group_key = "ex-target"
}
}
ex-udp = {
port = 82
protocol = "UDP"
forward = {
target_group_key = "ex-target"
}
}
ex-tcp = {
port = 83
protocol = "TCP"
forward = {
target_group_key = "ex-target"
}
}
ex-tls = {
port = 84
protocol = "TLS"
certificate_arn = "arn:aws:iam::123456789012:server-certificate/test_cert-123456789012"
forward = {
target_group_key = "ex-target"
}
}
}
target_groups = {
ex-target = {
name_prefix = "pref-"
protocol = "TCP"
port = 80
target_type = "ip"
target_id = "10.0.47.1"
}
}
tags = {
Environment = "Development"
Project = "Example"
}
}
Conditional creation
The following values are provided to toggle on/off creation of the associated resources as desired:
module "alb" {
source = "terraform-aws-modules/alb/aws"
# Disable creation of the LB and all resources
create = false
# ... omitted
}
Examples
See patterns.md for additional configuration snippets for common usage patterns.
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->Requirements
Name | Version |
---|---|
<a name="requirement_terraform"></a> terraform | >= 1.0 |
<a name="requirement_aws"></a> aws | >= 5.62 |
Providers
Name | Version |
---|---|
<a name="provider_aws"></a> aws | >= 5.62 |
Modules
No modules.
Resources
Name | Type |
---|---|
aws_lambda_permission.this | resource |
aws_lb.this | resource |
aws_lb_listener.this | resource |
aws_lb_listener_certificate.this | resource |
aws_lb_listener_rule.this | resource |
aws_lb_target_group.this | resource |
aws_lb_target_group_attachment.additional | resource |
aws_lb_target_group_attachment.this | resource |
aws_route53_record.this | resource |
aws_security_group.this | resource |
aws_vpc_security_group_egress_rule.this | resource |
aws_vpc_security_group_ingress_rule.this | resource |
aws_wafv2_web_acl_association.this | resource |
aws_partition.current | data source |
Inputs
Name | Description | Type | Default | Required |
---|---|---|---|---|
<a name="input_access_logs"></a> access_logs | Map containing access logging configuration for load balancer | map(string) | {} | no |
<a name="input_additional_target_group_attachments"></a> additional_target_group_attachments | Map of additional target group attachments to create. Use target_group_key to attach to the target group created in target_groups | any | {} | no |
<a name="input_associate_web_acl"></a> associate_web_acl | Indicates whether a Web Application Firewall (WAF) ACL should be associated with the load balancer | bool | false | no |
<a name="input_client_keep_alive"></a> client_keep_alive | Client keep alive value in seconds. The valid range is 60-604800 seconds. The default is 3600 seconds. | number | null | no |
<a name="input_connection_logs"></a> connection_logs | Map containing access logging configuration for load balancer | map(string) | {} | no |
<a name="input_create"></a> create | Controls if resources should be created (affects nearly all resources) | bool | true | no |
<a name="input_create_security_group"></a> create_security_group | Determines if a security group is created | bool | true | no |
<a name="input_customer_owned_ipv4_pool"></a> customer_owned_ipv4_pool | The ID of the customer owned ipv4 pool to use for this load balancer | string | null | no |
<a name="input_default_port"></a> default_port | Default port used across the listener and target group | number | 80 | no |
<a name="input_default_protocol"></a> default_protocol | Default protocol used across the listener and target group | string | "HTTP" | no |
<a name="input_desync_mitigation_mode"></a> desync_mitigation_mode | Determines how the load balancer handles requests that might pose a security risk to an application due to HTTP desync. Valid values are monitor , defensive (default), strictest | string | null | no |
<a name="input_dns_record_client_routing_policy"></a> dns_record_client_routing_policy | Indicates how traffic is distributed among the load balancer Availability Zones. Possible values are any_availability_zone (default), availability_zone_affinity, or partial_availability_zone_affinity. Only valid for network type load balancers. | string | null | no |
<a name="input_drop_invalid_header_fields"></a> drop_invalid_header_fields | Indicates whether HTTP headers with header fields that are not valid are removed by the load balancer (true ) or routed to targets (false ). The default is true . Elastic Load Balancing requires that message header names contain only alphanumeric characters and hyphens. Only valid for Load Balancers of type application | bool | true | no |
<a name="input_enable_cross_zone_load_balancing"></a> enable_cross_zone_load_balancing | If true , cross-zone load balancing of the load balancer will be enabled. For application load balancer this feature is always enabled (true ) and cannot be disabled. Defaults to true | bool | true | no |
<a name="input_enable_deletion_protection"></a> 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 true | bool | true | no |
<a name="input_enable_http2"></a> enable_http2 | Indicates whether HTTP/2 is enabled in application load balancers. Defaults to true | bool | null | no |
<a name="input_enable_tls_version_and_cipher_suite_headers"></a> enable_tls_version_and_cipher_suite_headers | Indicates whether the two headers (x-amzn-tls-version and x-amzn-tls-cipher-suite ), which contain information about the negotiated TLS version and cipher suite, are added to the client request before sending it to the target. Only valid for Load Balancers of type application . Defaults to false | bool | null | no |
<a name="input_enable_waf_fail_open"></a> enable_waf_fail_open | Indicates whether to allow a WAF-enabled load balancer to route requests to targets if it is unable to forward the request to AWS WAF. Defaults to false | bool | null | no |
<a name="input_enable_xff_client_port"></a> enable_xff_client_port | Indicates whether the X-Forwarded-For header should preserve the source port that the client used to connect to the load balancer in application load balancers. Defaults to false | bool | null | no |
<a name="input_enforce_security_group_inbound_rules_on_private_link_traffic"></a> enforce_security_group_inbound_rules_on_private_link_traffic | Indicates whether inbound security group rules are enforced for traffic originating from a PrivateLink. Only valid for Load Balancers of type network. The possible values are on and off. | string | null | no |
<a name="input_idle_timeout"></a> idle_timeout | The time in seconds that the connection is allowed to be idle. Only valid for Load Balancers of type application . Default: 60 | number | null | no |
<a name="input_internal"></a> internal | If true, the LB will be internal. Defaults to false | bool | null | no |
<a name="input_ip_address_type"></a> ip_address_type | The type of IP addresses used by the subnets for your load balancer. The possible values are ipv4 and dualstack | string | null | no |
<a name="input_listeners"></a> listeners | Map of listener configurations to create | any | {} | no |
<a name="input_load_balancer_type"></a> load_balancer_type | The type of load balancer to create. Possible values are application , gateway , or network . The default value is application | string | "application" | no |
<a name="input_name"></a> name | The name of the LB. This name must be unique within your AWS account, can have a maximum of 32 characters, must contain only alphanumeric characters or hyphens, and must not begin or end with a hyphen | string | null | no |
<a name="input_name_prefix"></a> name_prefix | Creates a unique name beginning with the specified prefix. Conflicts with name | string | null | no |
<a name="input_preserve_host_header"></a> preserve_host_header | Indicates whether the Application Load Balancer should preserve the Host header in the HTTP request and send it to the target without any change. Defaults to false | bool | null | no |
<a name="input_putin_khuylo"></a> putin_khuylo | Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo! | bool | true | no |
<a name="input_route53_records"></a> route53_records | Map of Route53 records to create. Each record map should contain zone_id , name , and type | any | {} | no |
<a name="input_security_group_description"></a> security_group_description | Description of the security group created | string | null | no |
<a name="input_security_group_egress_rules"></a> security_group_egress_rules | Security group egress rules to add to the security group created | any | {} | no |
<a name="input_security_group_ingress_rules"></a> security_group_ingress_rules | Security group ingress rules to add to the security group created | any | {} | no |
<a name="input_security_group_name"></a> security_group_name | Name to use on security group created | string | null | no |
<a name="input_security_group_tags"></a> security_group_tags | A map of additional tags to add to the security group created | map(string) | {} | no |
<a name="input_security_group_use_name_prefix"></a> security_group_use_name_prefix | Determines whether the security group name (security_group_name ) is used as a prefix | bool | true | no |
<a name="input_security_groups"></a> security_groups | A list of security group IDs to assign to the LB | list(string) | [] | no |
<a name="input_subnet_mapping"></a> subnet_mapping | A list of subnet mapping blocks describing subnets to attach to load balancer | list(map(string)) | [] | no |
<a name="input_subnets"></a> subnets | A list of subnet IDs to attach to the LB. Subnets cannot be updated for Load Balancers of type network . Changing this value for load balancers of type network will force a recreation of the resource | list(string) | null | no |
<a name="input_tags"></a> tags | A map of tags to add to all resources | map(string) | {} | no |
<a name="input_target_groups"></a> target_groups | Map of target group configurations to create | any | {} | no |
<a name="input_timeouts"></a> timeouts | Create, update, and delete timeout configurations for the load balancer | map(string) | {} | no |
<a name="input_vpc_id"></a> vpc_id | Identifier of the VPC where the security group will be created | string | null | no |
<a name="input_web_acl_arn"></a> web_acl_arn | Web Application Firewall (WAF) ARN of the resource to associate with the load balancer | string | null | no |
<a name="input_xff_header_processing_mode"></a> xff_header_processing_mode | Determines how the load balancer modifies the X-Forwarded-For header in the HTTP request before sending the request to the target. The possible values are append , preserve , and remove . Only valid for Load Balancers of type application . The default is append | string | null | no |
Outputs
Name | Description |
---|---|
<a name="output_arn"></a> arn | The ID and ARN of the load balancer we created |
<a name="output_arn_suffix"></a> arn_suffix | ARN suffix of our load balancer - can be used with CloudWatch |
<a name="output_dns_name"></a> dns_name | The DNS name of the load balancer |
<a name="output_id"></a> id | The ID and ARN of the load balancer we created |
<a name="output_listener_rules"></a> listener_rules | Map of listeners rules created and their attributes |
<a name="output_listeners"></a> listeners | Map of listeners created and their attributes |
<a name="output_route53_records"></a> route53_records | The Route53 records created and attached to the load balancer |
<a name="output_security_group_arn"></a> security_group_arn | Amazon Resource Name (ARN) of the security group |
<a name="output_security_group_id"></a> security_group_id | ID of the security group |
<a name="output_target_groups"></a> target_groups | Map of target groups created and their attributes |
<a name="output_zone_id"></a> zone_id | The zone_id of the load balancer to assist with creating DNS records |
Authors
Module is maintained by Anton Babenko with help from these awesome contributors.
License
Apache 2 Licensed. See LICENSE for full details.
Additional information for users from Russia and Belarus
- Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
- Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
- Putin khuylo!