terraform-aws-lb-listener

A Terraform module to create and manage an Application Load Balancer Listener on Amazon Web Services (AWS).

This module supports Terraform version 1 and is compatible with the Terraform AWS Provider version 3.40.

This module is part of our Infrastructure as Code (IaC) framework that enables our users and customers to easily deploy and manage reusable, secure, and production-grade cloud infrastructure.

• Module Features
• Getting Started
• Module Argument Reference
  • Main Resource Configuration
  • Extended Resource Configuration
  • Module Configuration
• Module Outputs
• External Documentation
  • AWS Documentation
  • Terraform AWS Provider Documentation
• Module Versioning
  • Backwards compatibility in 0.0.z and 0.y.z version
• About Mineiros
• Reporting Issues
• Contributing
• Makefile Targets
• License

Module Features

This module implements the following Terraform resources:

• aws_lb_listener
• aws_lb_listener_certificate
• lb_listener_rule

Getting Started

Most common usage of the module:

module "terraform-aws-lb-listener" {
  source = "git@github.com:mineiros-io/terraform-aws-lb-listener.git?ref=v0.0.1"

  load_balancer_arn = "load-balancer-arn"
}

Module Argument Reference

See variables.tf and examples/ for details and use-cases.

Main Resource Configuration

• load_balancer_arn: (Required string)

  The ARN of the load balancer. Forces new resource creation.

• port: (Optional number)

  Port on which the load balancer is listening. Not valid for Gateway Load Balancers.

• protocol: (Optional string)

  Protocol for connections from clients to the load balancer. For Application Load Balancers, valid values are HTTP and HTTPS. For Network Load Balancers, valid values are TCP, TLS, UDP, and TCP_UDP. Not valid to use UDP or TCP_UDP if dual-stack mode is enabled. Not valid for Gateway Load Balancers.

• certificate_arn: (Optional string)

  ARN of the default SSL server certificate. Exactly one certificate is required if the protocol is HTTPS.

• alpn_policy: (Optional string)

  Name of the Application-Layer Protocol Negotiation (ALPN) policy. Can be set if protocol is set to TLS. Valid values are HTTP1Only, HTTP2Only, HTTP2Optional, HTTP2Preferred, and None.

  Default is "None".

• ssl_policy: (Optional string)

  Name of the SSL Policy for the listener. Required if protocol is HTTPS or TLS.

  Default is "ELBSecurityPolicy-2016-08".

• additional_certificates_arns: (Optional set(string))

  The ARNs of the additional certificates to attach to the listener.

  Default is [].

• default_action: (Optional object(default_action))

  Configuration block for default actions.

  Default is {"fixed_response":{"content_type":"plain/text","message_body":"Nothing to see here!","status_code":418}}.

  The default_action object accepts the following attributes:

  • target_group_arn: (Optional string)

    ARN of the Target Group to which to route traffic. Specify only if type is forward and you want to route to a single target group. To route to one or more target groups, use a forward block instead.

  • order: (Optional number)

    Order for the action. This value is required for rules with multiple actions. The action with the lowest value for order is performed first. Valid values are between 1 and 50000.

  • authenticate_cognito: (Optional object(authenticate_cognito))

    Configuration block for using Amazon Cognito to authenticate users.

    The authenticate_cognito object accepts the following attributes:

    • user_pool_arn: (Required string)

      ARN of the Cognito user pool.

    • user_pool_domain: (Required string)

      Domain prefix or fully-qualified domain name of the Cognito user pool.

    • user_pool_client_id: (Required string)

      Domain prefix or fully-qualified domain name of the Cognito user pool.

    • authentication_request_extra_params: (Optional map(string))

      Query parameters to include in the redirect request to the authorization endpoint. Max: 10.

    • on_unauthenticated_request: (Optional string)

      Behavior if the user is not authenticated. Valid values are deny, allow and authenticate.

    • scope: (Optional string)

      Set of user claims to be requested from the IdP.

    • session_cookie_name: (Optional string)

      Name of the cookie used to maintain session information.

    • session_timeout: (Optional number)

      Maximum duration of the authentication session, in seconds.

  • authenticate_oidc: (Optional object(authenticate_oidc))

    Configuration block for an identity provider that is compliant with OpenID Connect (OIDC).

    Default is [].

    The authenticate_oidc object accepts the following attributes:

    • authorization_endpoint: (Required string)

      Authorization endpoint of the IdP.

    • client_id: (Required string)

      OAuth 2.0 client identifier.

    • client_secret: (Required string)

      OAuth 2.0 client secret.

    • issuer: (Required string)

      OIDC issuer identifier of the IdP.

    • authentication_request_extra_params: (Optional map(string))

      Query parameters to include in the redirect request to the authorization endpoint. Max: 10.

    • on_unauthenticated_request: (Optional string)

      Behavior if the user is not authenticated. Valid values: deny, allow and authenticate.

    • scope: (Optional string)

      Set of user claims to be requested from the IdP.

    • session_cookie_name: (Optional string)

      Name of the cookie used to maintain session information.

    • session_timeout: (Optional number)

      Maximum duration of the authentication session, in seconds.

    • token_endpoint: (Required string)

      Token endpoint of the IdP.

    • user_info_endpoint: (Required string)

      User info endpoint of the IdP.

  • fixed_response: (Optional object(fixed_response))

    Information for creating an action that returns a custom HTTP response.

    The fixed_response object accepts the following attributes:

    • content_type: (Required string)

      Content type. Valid values are text/plain, text/css, text/html, application/javascript and application/json.

    • message_body: (Optional string)

      Message body.

    • status_code: (Optional string)

      HTTP response code. Valid values are 2XX, 4XX, or 5XX.

  • forward: (Optional object(forward))

    Configuration block for creating an action that distributes requests among one or more target groups. If you specify both forward block and target_group_arn attribute, you can specify only one target group using forward and it must be the same target group specified in target_group_arn.

    The forward object accepts the following attributes:

    • target_groups: (Optional set(target_group))

      Set of 1-5 target group blocks.

      Each target_group object in the set accepts the following attributes:

      • arn: (Required string)

        ARN of the target group.

      • weight: (Optional number)

        Weight. The range is 0 to 999.

    • stickiness: (Optional object(stickiness))

      Configuration block for target group stickiness for the rule.

      The stickiness object accepts the following attributes:

      • duration: (Required number)

        Time period, in seconds, during which requests from a client should be routed to the same target group. The range is 1-604800 seconds (7 days).

      • enabled: (Optional bool)

        Whether target group stickiness is enabled.

        Default is false.

  • redirect: (Optional object(redirect))

    Configuration block for creating a redirect action.

    The redirect object accepts the following attributes:

    • status_code: (Optional string)

      HTTP redirect code. The redirect is either permanent (HTTP_301) or temporary (HTTP_302).

      Default is "HTTP_302".

    • host: (Optional string)

      Hostname. This component is not percent-encoded. The hostname can contain #{host}.

      Default is "{host}".

    • path: (Optional string)

      Absolute path, starting with the leading "/". This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}.

      Default is "#{path}".

    • port: (Optional string)

      The port. Specify a value from 1 to 65535 or #{port}.

      Default is "#{port}".

    • protocol: (Optional string)

      The protocol. Valid values are HTTP, HTTPS, or #{protocol}.

      Default is "#{protocol}".

    • query: (Optional string)

      The query parameters, URL-encoded when necessary, but not percent-encoded. Do not include the leading "?".

      Default is "#{query".

• tags: (Optional map(string))

  A map of tags to apply to the aws_lb_listener resource.

  Default is {}.

Extended Resource Configuration

• rules: (Optional list(rule))

  A list of rules to be attached to the created listener.

  Default is [].

  Each rule object in the list accepts the following attributes:

  • id: (Required string)

    A unique identifier for the rule

  • priority: (Optional number)

    The priority for the rule between 1 and 50000. Leaving it unset will automatically set the rule with next available priority after currently existing highest rule. A listener can't have multiple rules with the same priority.

  • action: (Required object(action))

    Configuration block for the action of the rule.

    Default is {"fixed_response":{"content_type":"plain/text","message_body":"Nothing to see here!","status_code":418}}.

    The action object accepts the following attributes:

    • target_group_arn: (Optional string)

      ARN of the Target Group to which to route traffic. Specify only if type is forward and you want to route to a single target group. To route to one or more target groups, use a forward block instead.

    • fixed_response: (Optional object(fixed_response))

      Information for creating an action that returns a custom HTTP response. Required if type is fixed-response.

      The fixed_response object accepts the following attributes:

      • content_type: (Required string)

        Content type. Valid values are text/plain, text/css, text/html, application/javascript and application/json.

      • message_body: (Optional string)

        Message body.

      • status_code: (Optional string)

        HTTP response code. Valid values are 2XX, 4XX, or 5XX.

    • forward: (Optional object(forward))

      Configuration block for creating an action that distributes requests among one or more target groups. If you specify both forward block and target_group_arn attribute, you can specify only one target group using forward and it must be the same target group specified in target_group_arn.

      The forward object accepts the following attributes:

      • target_groups: (Optional set(target_group))

        Set of 1-5 target group blocks.

        Each target_group object in the set accepts the following attributes:

        • arn: (Required string)

          ARN of the target group.

        • weight: (Optional number)

          Weight. The range is 0 to 999.

      • stickiness: (Optional object(stickiness))

        Configuration block for target group stickiness for the rule.

        The stickiness object accepts the following attributes:

        • duration: (Required number)

          Time period, in seconds, during which requests from a client should be routed to the same target group. The range is 1-604800 seconds (7 days).

        • enabled: (Optional bool)

          Whether target group stickiness is enabled.

          Default is false.

    • redirect: (Optional object(redirect))

      Configuration block for creating a redirect action. Required if type is redirect.

      The redirect object accepts the following attributes:

      • status_code: (Optional string)

        HTTP redirect code. The redirect is either permanent (HTTP_301) or temporary (HTTP_302).

        Default is "HTTP_302".

      • host: (Optional string)

        Hostname. This component is not percent-encoded. The hostname can contain #{host}.

        Default is "#{host}".

      • path: (Optional string)

        Absolute path, starting with the leading "/". This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}.

        Default is "#{path}".

      • port: (Optional string)

        The port. Specify a value from 1 to 65535 or #{port}.

        Default is "#{port}".

      • protocol: (Optional string)

        The protocol. Valid values are HTTP, HTTPS, or #{protocol}.

        Default is "#{protocol}".

      • query: (Optional string)

        The query parameters, URL-encoded when necessary, but not percent-encoded. Do not include the leading "?".

        Default is "#{query".

  • conditions: (Required set(conditions))

    A Condition block. Multiple condition blocks of different types can be set and all must be satisfied for the rule to match.

    Each conditions object in the set accepts the following attributes:

    • host_header: (Optional object(host_header))

      The maximum size of each pattern is 128 characters. Comparison is case insensitive. Wildcard characters supported: * (matches 0 or more characters) and ? (matches exactly 1 character). Only one pattern needs to match for the condition to be satisfied.

      The host_header object accepts the following attributes:

      • values: (Required set(string))

        List of host header patterns to match.

    • http_header: (Optional object(http_header))

      HTTP headers to match.

      The http_header object accepts the following attributes:

      • http_header_name: (Required string)

        Name of HTTP header to search. The maximum size is 40 characters. Comparison is case insensitive. Only RFC7240 characters are supported. Wildcards are not supported. You cannot use HTTP header condition to specify the host header, use a host-header condition instead.

      • values: (Required set(string))

        List of header value patterns to match. Maximum size of each pattern is 128 characters. Comparison is case insensitive. Wildcard characters supported: * (matches 0 or more characters) and ? (matches exactly 1 character). If the same header appears multiple times in the request they will be searched in order until a match is found. Only one pattern needs to match for the condition to be satisfied. To require that all of the strings are a match, create one condition block per string.

    • http_request_method: (Optional object(http_request_method))

      Maximum size is 40 characters. Only allowed characters are A-Z, hyphen (-) and underscore (_). Comparison is case sensitive. Wildcards are not supported. Only one needs to match for the condition to be satisfied. AWS recommends that GET and HEAD requests are routed in the same way because the response to a HEAD request may be cached.

      Default is [].

      The http_request_method object accepts the following attributes:

      • values: (Required set(string))

        List of HTTP request methods or verbs to match.

    • path_pattern: (Optional object(path_pattern))

      Maximum size of each pattern is 128 characters. Comparison is case sensitive. Wildcard characters supported: * (matches 0 or more characters) and ? (matches exactly 1 character). Only one pattern needs to match for the condition to be satisfied. Path pattern is compared only to the path of the URL, not to its query string. To compare against the query string, use a query_string condition.

      Default is [].

      The path_pattern object accepts the following attributes:

      • values: (Required set(string))

        List of path patterns to match against the request URL.

    • query_string: (Optional set(query_string))

      Query strings to match.

      Default is [].

      Each query_string object in the set accepts the following attributes:

      • key: (Optional string)

        Query string key pattern to match.

      • value: (Required string)

        Query string value pattern to match.

    • source_ip: (Optional object(source_ip))

      You can use both IPv4 and IPv6 addresses. Wildcards are not supported. Condition is satisfied if the source IP address of the request matches one of the CIDR blocks. Condition is not satisfied by the addresses in the X-Forwarded-For header, use http_header condition instead.

      Default is [].

      The source_ip object accepts the following attributes:

      • values: (Required set(string))

        List of source IP CIDR notations to match.

  • authenticate_cognito: (Optional object(authenticate_cognito))

    Configuration block for using Amazon Cognito to authenticate users.

    Default is [].

    The authenticate_cognito object accepts the following attributes:

    • user_pool_arn: (Required string)

      ARN of the Cognito user pool.

    • user_pool_domain: (Required string)

      Domain prefix or fully-qualified domain name of the Cognito user pool.

    • user_pool_client_id: (Required string)

      Domain prefix or fully-qualified domain name of the Cognito user pool.

    • authentication_request_extra_params: (Optional map(string))

      Query parameters to include in the redirect request to the authorization endpoint. Accepts a maximum of 10 extra parameters.

    • on_unauthenticated_request: (Optional string)

      Behavior if the user is not authenticated. Valid values are deny, allow and authenticate.

    • scope: (Optional string)

      Set of user claims to be requested from the IdP.

    • session_cookie_name: (Optional string)

      Name of the cookie used to maintain session information.

    • session_timeout: (Optional number)

      Maximum duration of the authentication session, in seconds.

  • authenticate_oidc: (Optional object(authenticate_oidc))

    Configuration block for an identity provider that is compliant with OpenID Connect (OIDC).

    Default is [].

    The authenticate_oidc object accepts the following attributes:

    • authorization_endpoint: (Required string)

      Authorization endpoint of the IdP.

    • client_id: (Required string)

      OAuth 2.0 client identifier.

    • client_secret: (Required string)

      OAuth 2.0 client secret.

    • issuer: (Required string)

      OIDC issuer identifier of the IdP.

    • authentication_request_extra_params: (Optional map(string))

      Query parameters to include in the redirect request to the authorization endpoint. Max: 10.

    • on_unauthenticated_request: (Optional string)

      Behavior if the user is not authenticated. Valid values: deny, allow and authenticate.

    • scope: (Optional string)

      Set of user claims to be requested from the IdP.

    • session_cookie_name: (Optional string)

      Name of the cookie used to maintain session information.

    • session_timeout: (Optional number)

      Maximum duration of the authentication session, in seconds.

    • token_endpoint: (Required string)

      Token endpoint of the IdP.

    • user_info_endpoint: (Required string)

      User info endpoint of the IdP.

• rules_tags: (Optional map(string))

  A map of tags to apply to all aws_lb_listener_rule resources.

  Default is {}.

Module Configuration

• module_enabled: (Optional bool)

  Specifies whether resources in the module will be created.

  Default is true.

• module_tags: (Optional map(string))

  A map of tags that will be applied to all created resources that accept tags. Tags defined with module_tags can be overwritten by resource-specific tags.

  Default is {}.

  Example:

  module_tags = {
    environment = "staging"
    team        = "platform"
  }

• module_depends_on: (Optional list(dependency))

  A list of dependencies. Any object can be assigned to this list to define a hidden external dependency.

  Default is [].

  Example:

  module_depends_on = [
    null_resource.name
  ]

Module Outputs

The following attributes are exported in the outputs of the module:

• lb_listener_rule: (object(lb_listener_rule))

  All outputs of the created 'aws_lb_listener_rule' resource.

• module_enabled: (bool)

  Whether this module is enabled.

• module_tags: (map(string))

  The map of tags that are being applied to all created resources that accept tags.

External Documentation

AWS Documentation

• https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html

Terraform AWS Provider Documentation

• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_listener
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_listener_certificate
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_listener_rule

Module Versioning

This Module follows the principles of Semantic Versioning (SemVer).

Given a version number MAJOR.MINOR.PATCH, we increment the:

1. MAJOR version when we make incompatible changes,
2. MINOR version when we add functionality in a backwards compatible manner, and
3. PATCH version when we make backwards compatible bug fixes.

Backwards compatibility in 0.0.z and 0.y.z version

• Backwards compatibility in versions 0.0.z is not guaranteed when z is increased. (Initial development)
• Backwards compatibility in versions 0.y.z is not guaranteed when y is increased. (Pre-release)

About Mineiros

Mineiros is a remote-first company headquartered in Berlin, Germany that solves development, automation and security challenges in cloud infrastructure.

Our vision is to massively reduce time and overhead for teams to manage and deploy production-grade and secure cloud infrastructure.

We offer commercial support for all of our modules and encourage you to reach out if you have any questions or need help. Feel free to email us at hello@mineiros.io or join our Community Slack channel.

Reporting Issues

We use GitHub Issues to track community reported issues and missing features.

Contributing

Contributions are always encouraged and welcome! For the process of accepting changes, we use Pull Requests. If you'd like more information, please see our Contribution Guidelines.

Makefile Targets

This repository comes with a handy Makefile. Run make help to see details on each available target.

License

This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.

Copyright © 2020-2022 Mineiros GmbH