Skip to content

terraform-aws-module-template

Module Structure

terraform-aws-arc-load-balancer

Latest Release Last Updated Terraform GitHub Actions

Quality gate

Known Vulnerabilities

Overview

This Terraform module provisions and configures an AWS Load Balancer (ALB/NLB) along with related resources such as target groups, listeners, listener rules, security groups, and logging configurations. It is designed for high availability, security, and scalability while allowing flexibility for integration with existing AWS infrastructure.

Features

  • Load Balancer
  • Supports Application Load Balancer (ALB) and Network Load Balancer (NLB)
  • Option for internal or external load balancer
  • Supports IPv4 and IPv6 addressing
  • Cross-zone load balancing for improved traffic distribution
  • Deletion protection to prevent accidental removal

Security and Access Control

  • Ability to attach security groups dynamically
  • Trust store support for managing client authentication securely

Target Groups & Attachments

  • Dynamic target group creation for EC2 instances, Lambda functions, or IP addresses
  • Supports stickiness policies for session persistence
  • Configurable health checks to monitor target availability
  • DNS failover & unhealthy state routing for improved reliability
  • Target failover handling for high availability

Logging and Monitoring

  • Access logging to Amazon S3 for audit and compliance
  • Connection logs to track network-level traffic

Listener & Listener Rules

  • Supports HTTP, HTTPS, TCP, and UDP listeners
  • Configurable SSL/TLS certificates for secure traffic
  • OIDC and Cognito authentication for secure access control
  • Supports redirect, fixed response, and forward actions

Custom Configurations

  • Subnet mappings to control network placement
  • Fine-grained control over timeouts, session stickiness, and routing policies
  • Weighted target group routing for intelligent traffic distribution

Usage

To see a full example, check out the main.tf file in the example folder. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
################################################################################
## application load balancer
################################################################################

module "alb" {
  source                         = "sourcefuse/arc-load-balancer/aws"
  version                        = "0.0.1"
  load_balancer_config           = local.load_balancer_config
  target_group_config            = local.target_group_config
  target_group_attachment_config = local.target_group_attachment_config
  alb_listener                   = local.alb_listener
  default_action                 = local.default_action
  listener_rules                 = local.listener_rules
  security_group_data            = local.security_group_data
  security_group_name            = local.security_group_name
  vpc_id                         = data.aws_vpc.default.id
  tags                           = module.tags.tags
}

################################################################################
## network load balancer
################################################################################
module "nlb" {
  source                         = "sourcefuse/arc-load-balancer/aws"
  version                        = "0.0.1"
  load_balancer_config           = local.load_balancer_config
  target_group_config            = local.target_group_config
  target_group_attachment_config = local.target_group_attachment_config
  alb_listener                   = local.alb_listener
  security_group_data            = local.security_group_data
  network_forward_action         = local.network_forward_action
  security_group_name            = local.security_group_name
  vpc_id                         = data.aws_vpc.default.id
  tags                           = module.tags.tags
}

Requirements

Name Version
terraform >= 1.5.0
aws ~> 5.0

Providers

Name Version
aws 5.84.0

Modules

Name Source Version
arc_security_group sourcefuse/arc-security-group/aws 0.0.1
tags sourcefuse/arc-tags/aws 1.2.6

Resources

Name Type
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.this resource
aws_lb_trust_store.this resource

Inputs

Name Description Type Default Required
alb_listener n/a 
object({
    port                     = optional(number, 80)
    protocol                 = optional(string, "HTTP")
    alpn_policy              = optional(string, null)
    certificate_arn          = optional(string, "")
    ssl_policy               = optional(string, "")
    tcp_idle_timeout_seconds = optional(number, 350)
  })
 n/a yes
default_action Default actions for the ALB listener. 
list(object({
    type = string

    authenticate_oidc = optional(object({
      authorization_endpoint              = string
      authentication_request_extra_params = optional(map(string), {})
      client_id                           = string
      client_secret                       = string
      issuer                              = string
      token_endpoint                      = string
      user_info_endpoint                  = string
      on_unauthenticated_request          = optional(string, "deny")
      scope                               = optional(string)
      session_cookie_name                 = optional(string)
      session_timeout                     = optional(number)
    }))

    authenticate_cognito = optional(object({
      user_pool_arn                       = string
      user_pool_client_id                 = string
      user_pool_domain                    = string
      authentication_request_extra_params = optional(map(string), {})
      on_unauthenticated_request          = optional(string, "deny")
      scope                               = optional(string)
      session_cookie_name                 = optional(string)
      session_timeout                     = optional(number)
    }))

    fixed_response = optional(object({
      status_code  = string
      content_type = optional(string, "text/plain")
      message_body = optional(string, "")
    }))
    forward = optional(object({
      target_groups = list(object({
        # arn    = string
        weight = optional(number, null)
      }))
      stickiness = optional(object({
        duration = number
        enabled  = optional(bool, false)
      }))
    }))

    redirect = optional(object({
      host        = optional(string)
      path        = optional(string)
      query       = optional(string)
      protocol    = optional(string)
      port        = optional(number)
      status_code = string
    }))
  }))
 [] no
lb_trust_store_config The configuration for the Load Balancer Trust Stores 
list(object({
    name                                     = string
    name_prefix                              = optional(string)
    ca_certificates_bundle_s3_bucket         = string
    ca_certificates_bundle_s3_key            = string
    ca_certificates_bundle_s3_object_version = optional(string)
  }))
 null no
listener_certificates A map of listener certificates with their ARN 
map(object({
    certificate_arn = string
  }))
 {} no
listener_rules A map of listener rules 
map(object({
    priority = number
    authenticate_oidc = optional(object({
      authorization_endpoint              = string
      client_id                           = string
      client_secret                       = string
      issuer                              = string
      token_endpoint                      = string
      user_info_endpoint                  = string
      authentication_request_extra_params = map(string)
      on_unauthenticated_request          = string
      scope                               = string
      session_cookie_name                 = string
      session_timeout                     = number
    }))
    actions = list(object({
      type  = string
      order = number
      redirect = optional(object({
        host        = string
        path        = string
        query       = string
        protocol    = string
        port        = number
        status_code = string
      }))
      fixed_response = optional(object({
        status_code  = string
        content_type = string
        message_body = string
      }))
      authenticate_cognito = optional(object({
        user_pool_arn              = string
        user_pool_client_id        = string
        user_pool_domain           = string
        on_unauthenticated_request = string
      }))
    }))
    conditions = list(object({
      host_header = optional(object({
        values = list(string)
      }))
      path_pattern = optional(object({
        values = list(string)
      }))
    }))
  }))
 {} no
load_balancer_config ######### alb security group config ########## 
object({
    name                                                         = optional(string, null)
    name_prefix                                                  = optional(string, null)
    type                                                         = optional(string, "application")
    internal                                                     = optional(bool, false)
    ip_address_type                                              = optional(string, "ipv4")
    enable_deletion_protection                                   = optional(bool, true)
    enable_cross_zone_load_balancing                             = optional(bool, true)
    enable_http2                                                 = optional(bool, true)
    enable_waf_fail_open                                         = optional(bool, false)
    enable_xff_client_port                                       = optional(bool, true)
    enable_zonal_shift                                           = optional(bool, true)
    desync_mitigation_mode                                       = optional(string, "defensive")
    drop_invalid_header_fields                                   = optional(bool, false)
    enforce_security_group_inbound_rules_on_private_link_traffic = optional(string, "off")
    idle_timeout                                                 = optional(number, 60)
    preserve_host_header                                         = optional(bool, true)
    xff_header_processing_mode                                   = optional(string, "append")
    customer_owned_ipv4_pool                                     = optional(string, null)
    dns_record_client_routing_policy                             = optional(string, "any_availability_zone")
    client_keep_alive                                            = optional(number, 60)
    enable_tls_version_and_cipher_suite_headers                  = optional(bool, true)

    subnet_mapping = optional(list(object({
      subnet_id            = string
      allocation_id        = optional(string, null)
      ipv6_address         = optional(string, null)
      private_ipv4_address = optional(string, null)
    })))

    access_logs = optional(object({
      enabled = optional(bool, false)
      bucket  = string
      prefix  = optional(string, "access-logs")
    }))

    connection_logs = optional(object({
      enabled = optional(bool, false)
      bucket  = string
      prefix  = optional(string, "connection-logs")
    }), )
  })
 n/a yes
network_forward_action Default forward action for the ALB listener. bool false no
security_group_data (optional) Security Group data 
object({
    security_group_ids_to_attach = optional(list(string), [])
    create                       = optional(bool, true)
    description                  = optional(string, null)
    ingress_rules = optional(list(object({
      description              = optional(string, null)
      cidr_block               = optional(string, null)
      source_security_group_id = optional(string, null)
      from_port                = number
      ip_protocol              = string
      to_port                  = string
      self                     = optional(bool, false)
    })), [])
    egress_rules = optional(list(object({
      description                   = optional(string, null)
      cidr_block                    = optional(string, null)
      destination_security_group_id = optional(string, null)
      from_port                     = number
      ip_protocol                   = string
      to_port                       = string
      prefix_list_id                = optional(string, null)
    })), [])
  })
 
{
  "create": false
}
 no
security_group_name alb security group name string n/a yes
security_groups n/a list(string) [] no
tags Tags to assign to the resource. map(string) {} no
target_group_attachment_config List of target group attachment configurations 
list(object({
    target_id         = string
    target_type       = string # Values: "instance", "ip", or "lambda"
    port              = optional(number)
    availability_zone = optional(string)
  }))
 null no
target_group_config ######### alb target group config ########## 
object({
    name                              = optional(string)
    name_prefix                       = optional(string)
    port                              = optional(number)
    protocol                          = optional(string)
    ip_address_type                   = optional(string)
    load_balancing_anomaly_mitigation = optional(bool)
    load_balancing_cross_zone_enabled = optional(bool)
    preserve_client_ip                = optional(bool)
    protocol_version                  = optional(string)
    load_balancing_algorithm_type     = optional(string)
    target_type                       = optional(string)
    proxy_protocol_v2                 = optional(bool)
    slow_start                        = optional(number)

    health_check = optional(object({
      enabled             = bool
      interval            = number
      path                = string
      port                = number
      protocol            = string
      timeout             = number
      unhealthy_threshold = number
      healthy_threshold   = number
      matcher             = string
    }))

    stickiness = optional(object({
      type            = string
      cookie_duration = number
      cookie_name     = optional(string)
      enabled         = bool
    }))

    target_group_health = optional(object({
      dns_failover = optional(object({
        minimum_healthy_targets_count      = number
        minimum_healthy_targets_percentage = number
      }))

      unhealthy_state_routing = optional(object({
        minimum_healthy_targets_count      = number
        minimum_healthy_targets_percentage = number
      }))
    }))

    target_failover = optional(object({
      on_deregistration = string
      on_unhealthy      = string
    }))

    target_health_state = optional(object({
      enable_unhealthy_connection_termination = bool
      unhealthy_draining_interval             = number
    }))
  })
 null no
vpc_id The VPC ID for the resources string n/a yes

Outputs

Name Description
arn ARN of the load balancer
dns_name DNS name of the load balancer
id ID of the load balancer
listener_arn ARN of the load balancer listener
security_group_ids Security group IDs created
target_group_arn ARN of the target group
target_group_health_check Health check configuration of the target group
target_group_stickiness Stickiness configuration of the target group

Versioning

This project uses a .version file at the root of the repo which the pipeline reads from and does a git tag.

When you intend to commit to main, you will need to increment this version. Once the project is merged, the pipeline will kick off and tag the latest git commit.

Development

Prerequisites

Configurations

  • Configure pre-commit hooks 
    1
    pre-commit install

Versioning

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

1
git commit -m "your commit message #major"
By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests

  • Tests are available in test directory
  • Configure the dependencies 
    1
2
3
    cd test/
go mod init github.com/sourcefuse/terraform-aws-refarch-<module_name>
go get github.com/gruntwork-io/terratest/modules/terraform
  • Now execute the test
    1
    go test -timeout  30m

Authors

This project is authored by: - SourceFuse ARC Team