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

• Complete Application Load Balancer
• Complete Network Load Balancer

See patterns.md for additional configuration snippets for common usage patterns.

Requirements

Name	Version
terraform	>= 1.0
aws	>= 5.73

Providers

Name	Version
aws	>= 5.73

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
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	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
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
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!