Skip to content

terraform-aws-modules/terraform-aws-alb

BranchesTags

Repository files navigation

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

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

Name Version
terraform >= 1.5.7
aws >= 6.5

Providers

Name Version
aws >= 6.5

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
access_logs Map containing access logging configuration for load balancer 
object({
    bucket  = string
    enabled = optional(bool, true)
    prefix  = optional(string)
  })
 null no
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 
map(object({
    target_group_key  = string
    target_id         = string
    target_type       = optional(string)
    port              = optional(number)
    availability_zone = optional(string)
  }))
 null no
associate_web_acl Indicates whether a Web Application Firewall (WAF) ACL should be associated with the load balancer bool false no
client_keep_alive Client keep alive value in seconds. The valid range is 60-604800 seconds. The default is 3600 seconds number null no
connection_logs Map containing access logging configuration for load balancer 
object({
    bucket  = string
    enabled = optional(bool, true)
    prefix  = optional(string)
  })
 null no
create Controls if resources should be created (affects nearly all resources) bool true no
create_security_group Determines if a security group is created bool true no
customer_owned_ipv4_pool The ID of the customer owned ipv4 pool to use for this load balancer string null no
default_port Default port used across the listener and target group number 80 no
default_protocol Default protocol used across the listener and target group string "HTTP" no
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
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
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
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
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
enable_http2 Indicates whether HTTP/2 is enabled in application load balancers. Defaults to true bool null no
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
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
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
enable_zonal_shift Whether zonal shift is enabled bool null no
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
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
internal If true, the LB will be internal. Defaults to false bool null 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 null no
ipam_pools The IPAM pools to use with the load balancer 
object({
    ipv4_ipam_pool_id = string
  })
 null no
listeners Map 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)
    }))
    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
        }))
        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 = list(string)
        }))
        http_header = optional(object({
          http_header_name = string
          values           = list(string)
        }))
        http_request_method = optional(object({
          values = list(string)
        }))
        path_pattern = optional(object({
          values = 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)
      tags         = optional(map(string), {})
    })), {})
  }))
 {} no
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
minimum_load_balancer_capacity Minimum capacity for a load balancer. Only valid for Load Balancers of type application or network 
object({
    capacity_units = number
  })
 null no
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
name_prefix Creates a unique name beginning with the specified prefix. Conflicts with name string null no
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
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
region Region where the resource(s) will be managed. Defaults to the Region set in the provider configuration string null no
route53_records Map 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
  }))
 null no
security_group_description Description of the security group created string null no
security_group_egress_rules Security 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)
  }))
 null no
security_group_ingress_rules Security 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)
  }))
 null no
security_group_name Name to use on security group created string null no
security_group_tags A map of additional tags to add to the security group created map(string) {} no
security_group_use_name_prefix Determines whether the security group name (security_group_name) is used as a prefix bool true no
security_groups A list of security group IDs to assign to the LB list(string) [] no
subnet_mapping A 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
  }))
 null no
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
tags A map of tags to add to all resources map(string) {} no
target_groups Map 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)
  }))
 null no
timeouts Create, update, and delete timeout configurations for the load balancer 
object({
    create = optional(string)
    update = optional(string)
    delete = optional(string)
  })
 null no
vpc_id Identifier of the VPC where the security group will be created string null no
web_acl_arn Web Application Firewall (WAF) ARN of the resource to associate with the load balancer string null no
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
arn The ID and ARN of the load balancer we created
arn_suffix ARN suffix of our load balancer - can be used with CloudWatch
dns_name The DNS name of the load balancer
id The ID and ARN of the load balancer we created
listener_rules Map of listeners rules created and their attributes
listeners Map of listeners created and their attributes
route53_records The Route53 records created and attached to the load balancer
security_group_arn Amazon Resource Name (ARN) of the security group
security_group_id ID of the security group
target_groups Map of target groups created and their attributes
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

About

Terraform module to create AWS Application/Network Load Balancer (ALB/NLB) resources 🇺🇦

registry.terraform.io/modules/terraform-aws-modules/alb/aws

Topics

aws alb application-load-balancer nlb terraform-module network-load-balancer

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

455 stars

Watchers

20 watching

Forks

703 forks
Report repository

Releases 59

v10.0.2 Latest
Oct 21, 2025
+ 58 releases

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

No packages published

Contributors 79

+ 65 contributors

Languages