AWS Application and Network Load Balancer (ALB & NLB) Terraform module

January 8, 2026 ยท View on GitHub

Terraform module which creates Application and Network Load Balancer resources on AWS.

SWUbanner

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 = [
            {
              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"
              }
            },
            {
              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 = [{
            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 = [
            {
              authenticate-cognito = {
                user_pool_arn       = "arn:aws:cognito-idp::123456789012:userpool/test-pool"
                user_pool_client_id = "6oRmFiS0JHk="
                user_pool_domain    = "test-domain-com"
              }
            },
            {
              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.

Requirements

NameVersion
terraform>= 1.5.7
aws>= 6.28

Providers

NameVersion
aws>= 6.28

Modules

No modules.

Resources

NameType
aws_lambda_permission.thisresource
aws_lb.thisresource
aws_lb_listener.thisresource
aws_lb_listener_certificate.thisresource
aws_lb_listener_rule.thisresource
aws_lb_target_group.thisresource
aws_lb_target_group_attachment.additionalresource
aws_lb_target_group_attachment.thisresource
aws_route53_record.thisresource
aws_security_group.thisresource
aws_vpc_security_group_egress_rule.thisresource
aws_vpc_security_group_ingress_rule.thisresource
aws_wafv2_web_acl_association.thisresource
aws_partition.currentdata source

Inputs

NameDescriptionTypeDefaultRequired
access_logsMap containing access logging configuration for load balancer
object({
bucket = string
enabled = optional(bool, true)
prefix = optional(string)
})
nullno
additional_target_group_attachmentsMap of additional target group attachments to create. Use target_group_key to attach to the target group created in target_groups
map(object({
target_group_key = string
target_id = string
target_type = optional(string)
port = optional(number)
availability_zone = optional(string)
}))
nullno
associate_web_aclIndicates whether a Web Application Firewall (WAF) ACL should be associated with the load balancerboolfalseno
client_keep_aliveClient keep alive value in seconds. The valid range is 60-604800 seconds. The default is 3600 secondsnumbernullno
connection_logsMap containing access logging configuration for load balancer
object({
bucket = string
enabled = optional(bool, true)
prefix = optional(string)
})
nullno
createControls if resources should be created (affects nearly all resources)booltrueno
create_security_groupDetermines if a security group is createdbooltrueno
customer_owned_ipv4_poolThe ID of the customer owned ipv4 pool to use for this load balancerstringnullno
default_portDefault port used across the listener and target groupnumber80no
default_protocolDefault protocol used across the listener and target groupstring"HTTP"no
desync_mitigation_modeDetermines 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), stricteststringnullno
dns_record_client_routing_policyIndicates 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 balancersstringnullno
drop_invalid_header_fieldsIndicates 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 applicationbooltrueno
enable_cross_zone_load_balancingIf 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 truebooltrueno
enable_deletion_protectionIf true, deletion of the load balancer will be disabled via the AWS API. This will prevent Terraform from deleting the load balancer. Defaults to truebooltrueno
enable_http2Indicates whether HTTP/2 is enabled in application load balancers. Defaults to trueboolnullno
enable_tls_version_and_cipher_suite_headersIndicates 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 falseboolnullno
enable_waf_fail_openIndicates 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 falseboolnullno
enable_xff_client_portIndicates 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 falseboolnullno
enable_zonal_shiftWhether zonal shift is enabledboolnullno
enforce_security_group_inbound_rules_on_private_link_trafficIndicates 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 offstringnullno
health_check_logsMap containing health check logging configuration for application load balancers
object({
bucket = string
enabled = optional(bool, true)
prefix = optional(string)
})
nullno
idle_timeoutThe time in seconds that the connection is allowed to be idle. Only valid for Load Balancers of type application. Default: 60numbernullno
internalIf true, the LB will be internal. Defaults to falseboolnullno
ip_address_typeThe type of IP addresses used by the subnets for your load balancer. The possible values are ipv4 and dualstackstringnullno
ipam_poolsThe IPAM pools to use with the load balancer
object({
ipv4_ipam_pool_id = string
})
nullno
listenersMap of listener configurations to create
map(object({
alpn_policy = optional(string)
certificate_arn = optional(string)
additional_certificate_arns = optional(list(string), [])
authenticate_cognito = optional(object({
authentication_request_extra_params = optional(map(string))
on_unauthenticated_request = optional(string)
scope = optional(string)
session_cookie_name = optional(string)
session_timeout = optional(number)
user_pool_arn = optional(string)
user_pool_client_id = optional(string)
user_pool_domain = optional(string)
}))
authenticate_oidc = optional(object({
authentication_request_extra_params = optional(map(string))
authorization_endpoint = string
client_id = string
client_secret = string
issuer = string
on_unauthenticated_request = optional(string)
scope = optional(string)
session_cookie_name = optional(string)
session_timeout = optional(number)
token_endpoint = string
user_info_endpoint = string
}))
fixed_response = optional(object({
content_type = string
message_body = optional(string)
status_code = optional(string)
}))
forward = optional(object({
target_group_arn = optional(string)
target_group_key = optional(string)
}))
jwt_validation = optional(object({
issuer = string
jwks_endpoint = string
additional_claim = optional(list(object({
format = string
name = string
values = list(string)
})))
}))
weighted_forward = optional(object({
target_groups = optional(list(object({
target_group_arn = optional(string)
target_group_key = optional(string)
weight = optional(number)
})))
stickiness = optional(object({
duration = optional(number)
enabled = optional(bool)
}))
}))
redirect = optional(object({
host = optional(string)
path = optional(string)
port = optional(string)
protocol = optional(string)
query = optional(string)
status_code = string
}))
mutual_authentication = optional(object({
advertise_trust_store_ca_names = optional(string)
ignore_client_certificate_expiry = optional(bool)
mode = string
trust_store_arn = optional(string)
}))
order = optional(number)
port = optional(number)
protocol = optional(string)
routing_http_request_x_amzn_mtls_clientcert_header_name = optional(string)
routing_http_request_x_amzn_mtls_clientcert_issuer_header_name = optional(string)
routing_http_request_x_amzn_mtls_clientcert_leaf_header_name = optional(string)
routing_http_request_x_amzn_mtls_clientcert_serial_number_header_name = optional(string)
routing_http_request_x_amzn_mtls_clientcert_subject_header_name = optional(string)
routing_http_request_x_amzn_mtls_clientcert_validity_header_name = optional(string)
routing_http_request_x_amzn_tls_cipher_suite_header_name = optional(string)
routing_http_request_x_amzn_tls_version_header_name = optional(string)
routing_http_response_access_control_allow_credentials_header_value = optional(string)
routing_http_response_access_control_allow_headers_header_value = optional(string)
routing_http_response_access_control_allow_methods_header_value = optional(string)
routing_http_response_access_control_allow_origin_header_value = optional(string)
routing_http_response_access_control_expose_headers_header_value = optional(string)
routing_http_response_access_control_max_age_header_value = optional(string)
routing_http_response_content_security_policy_header_value = optional(string)
routing_http_response_server_enabled = optional(bool)
routing_http_response_strict_transport_security_header_value = optional(string)
routing_http_response_x_content_type_options_header_value = optional(string)
routing_http_response_x_frame_options_header_value = optional(string)
ssl_policy = optional(string)
tcp_idle_timeout_seconds = optional(number)
tags = optional(map(string), {})

# Listener rules
rules = optional(map(object({
actions = list(object({
authenticate_cognito = optional(object({
authentication_request_extra_params = optional(map(string))
on_unauthenticated_request = optional(string)
scope = optional(string)
session_cookie_name = optional(string)
session_timeout = optional(number)
user_pool_arn = string
user_pool_client_id = string
user_pool_domain = string
}))
authenticate_oidc = optional(object({
authentication_request_extra_params = optional(map(string))
authorization_endpoint = string
client_id = string
client_secret = string
issuer = string
on_unauthenticated_request = optional(string)
scope = optional(string)
session_cookie_name = optional(string)
session_timeout = optional(number)
token_endpoint = string
user_info_endpoint = string
}))
jwt_validation = optional(object({
issuer = string
jwks_endpoint = string
additional_claim = optional(list(object({
format = string
name = string
values = list(string)
})))
}))
fixed_response = optional(object({
content_type = string
message_body = optional(string)
status_code = optional(string)
}))
forward = optional(object({
target_group_arn = optional(string)
target_group_key = optional(string)
}))
order = optional(number)
redirect = optional(object({
host = optional(string)
path = optional(string)
port = optional(string)
protocol = optional(string)
query = optional(string)
status_code = string
}))
weighted_forward = optional(object({
stickiness = optional(object({
duration = optional(number)
enabled = optional(bool)
}))
target_groups = optional(list(object({
target_group_arn = optional(string)
target_group_key = optional(string)
weight = optional(number)
})))
}))
}))
conditions = list(object({
host_header = optional(object({
values = optional(list(string))
regex_values = optional(list(string))
}))
http_header = optional(object({
http_header_name = string
values = optional(list(string))
regex_values = optional(list(string))
}))
http_request_method = optional(object({
values = list(string)
}))
path_pattern = optional(object({
values = optional(list(string))
regex_values = optional(list(string))
}))
query_string = optional(list(object({
key = optional(string)
value = string
})))
source_ip = optional(object({
values = list(string)
}))
}))
listener_arn = optional(string)
listener_key = optional(string)
priority = optional(number)
transform = optional(map(object({
type = optional(string)
host_header_rewrite_config = optional(object({
rewrite = optional(object({
regex = string
replace = string
}))
}))
url_rewrite_config = optional(object({
rewrite = optional(object({
regex = string
replace = string
}))
}))
})))
tags = optional(map(string), {})
})), {})
}))
{}no
load_balancer_typeThe type of load balancer to create. Possible values are application, gateway, or network. The default value is applicationstring"application"no
minimum_load_balancer_capacityMinimum capacity for a load balancer. Only valid for Load Balancers of type application or network
object({
capacity_units = number
})
nullno
nameThe 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 hyphenstringnullno
name_prefixCreates a unique name beginning with the specified prefix. Conflicts with namestringnullno
preserve_host_headerIndicates 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 falseboolnullno
putin_khuyloDo you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Putin_khuylo!booltrueno
regionRegion where the resource(s) will be managed. Defaults to the Region set in the provider configurationstringnullno
route53_recordsMap of Route53 records to create. Each record map should contain zone_id, name, and type
map(object({
zone_id = string
name = optional(string)
type = string
evaluate_target_health = optional(bool, true)
}))
nullno
security_group_descriptionDescription of the security group createdstringnullno
security_group_egress_rulesSecurity group egress rules to add to the security group created
map(object({
name = optional(string)

cidr_ipv4 = optional(string)
cidr_ipv6 = optional(string)
description = optional(string)
from_port = optional(string)
ip_protocol = optional(string, "tcp")
prefix_list_id = optional(string)
referenced_security_group_id = optional(string)
tags = optional(map(string), {})
to_port = optional(string)
}))
nullno
security_group_ingress_rulesSecurity group ingress rules to add to the security group created
map(object({
name = optional(string)

cidr_ipv4 = optional(string)
cidr_ipv6 = optional(string)
description = optional(string)
from_port = optional(string)
ip_protocol = optional(string, "tcp")
prefix_list_id = optional(string)
referenced_security_group_id = optional(string)
tags = optional(map(string), {})
to_port = optional(string)
}))
nullno
security_group_nameName to use on security group createdstringnullno
security_group_tagsA map of additional tags to add to the security group createdmap(string){}no
security_group_use_name_prefixDetermines whether the security group name (security_group_name) is used as a prefixbooltrueno
security_groupsA list of security group IDs to assign to the LBlist(string)[]no
subnet_mappingA list of subnet mapping blocks describing subnets to attach to load balancer
list(object({
allocation_id = optional(string)
ipv6_address = optional(string)
private_ipv4_address = optional(string)
subnet_id = string
}))
nullno
subnetsA 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 resourcelist(string)nullno
tagsA map of tags to add to all resourcesmap(string){}no
target_groupsMap of target group configurations to create
map(object({
connection_termination = optional(bool)
deregistration_delay = optional(number)
health_check = optional(object({
enabled = optional(bool)
healthy_threshold = optional(number)
interval = optional(number)
matcher = optional(string)
path = optional(string)
port = optional(string)
protocol = optional(string)
timeout = optional(number)
unhealthy_threshold = optional(number)
}))
ip_address_type = optional(string)
lambda_multi_value_headers_enabled = optional(bool)
load_balancing_algorithm_type = optional(string)
load_balancing_anomaly_mitigation = optional(string)
load_balancing_cross_zone_enabled = optional(string)
name = optional(string)
name_prefix = optional(string)
port = optional(number)
preserve_client_ip = optional(bool)
protocol = optional(string)
protocol_version = optional(string)
proxy_protocol_v2 = optional(bool)
slow_start = optional(number)
stickiness = optional(object({
cookie_duration = optional(number)
cookie_name = optional(string)
enabled = optional(bool)
type = string
}))
tags = optional(map(string))
target_failover = optional(list(object({
on_deregistration = string
on_unhealthy = string
})))
target_group_health = optional(object({
dns_failover = optional(object({
minimum_healthy_targets_count = optional(string)
minimum_healthy_targets_percentage = optional(string)
}))
unhealthy_state_routing = optional(object({
minimum_healthy_targets_count = optional(number)
minimum_healthy_targets_percentage = optional(string)
}))
}))
target_health_state = optional(object({
enable_unhealthy_connection_termination = bool
unhealthy_draining_interval = optional(number)
}))
target_type = optional(string)
target_id = optional(string)
vpc_id = optional(string)
# Attachment
create_attachment = optional(bool, true)
availability_zone = optional(string)
# Lambda
attach_lambda_permission = optional(bool, false)
lambda_qualifier = optional(string)
lambda_statement_id = optional(string)
lambda_action = optional(string)
lambda_principal = optional(string)
lambda_source_account = optional(string)
lambda_event_source_token = optional(string)
}))
nullno
timeoutsCreate, update, and delete timeout configurations for the load balancer
object({
create = optional(string)
update = optional(string)
delete = optional(string)
})
nullno
vpc_idIdentifier of the VPC where the security group will be createdstringnullno
web_acl_arnWeb Application Firewall (WAF) ARN of the resource to associate with the load balancerstringnullno
xff_header_processing_modeDetermines 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 appendstringnullno

Outputs

NameDescription
arnThe ID and ARN of the load balancer we created
arn_suffixARN suffix of our load balancer - can be used with CloudWatch
dns_nameThe DNS name of the load balancer
idThe ID and ARN of the load balancer we created
listener_rulesMap of listeners rules created and their attributes
listenersMap of listeners created and their attributes
route53_recordsThe Route53 records created and attached to the load balancer
security_group_arnAmazon Resource Name (ARN) of the security group
security_group_idID of the security group
target_groupsMap of target groups created and their attributes
zone_idThe 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