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

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

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

  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.0
aws	>= 5.33

Providers

Name	Version
aws	>= 5.33

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	`map(string)`	`{}`	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`	`any`	`{}`	no
associate_web_acl	Indicates whether a Web Application Firewall (WAF) ACL should be associated with the load balancer	`bool`	`false`	no
connection_logs	Map containing access logging configuration for load balancer	`map(string)`	`{}`	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
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
listeners	Map of listener configurations to create	`any`	`{}`	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
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
route53_records	Map of Route53 records to create. Each record map should contain `zone_id`, `name`, and `type`	`any`	`{}`	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	`any`	`{}`	no
security_group_ingress_rules	Security group ingress rules to add to the security group created	`any`	`{}`	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(map(string))`	`[]`	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	`any`	`{}`	no
timeouts	Create, update, and delete timeout configurations for the load balancer	`map(string)`	`{}`	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

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!

imhyeons/terraform-aws-alb-public