AWS CloudFront Distribution

Creates an AWS CloudFront distribution for a Rabbit-backed service.

Use this module when a site needs CloudFront in front of one or more origins, optional failover, ordered path-specific cache behavior, custom origin headers, Lambda@Edge or CloudFront Function hooks, WAF, ACM certificates, and CloudFront access logging.

Supported Features

• Multiple origins with custom headers.
• Origin groups for failover.
• Ordered cache behaviors sorted by order.
• Lambda@Edge and CloudFront Function associations.
• Custom cache policies and origin request policies.
• Custom error responses.
• CloudFront access log delivery to S3.
• WAF integration.
• SSL/TLS through ACM certificates.
• Distribution tags.

Prerequisites

• AWS credentials with permission to manage CloudFront distributions, CloudFront policies, CloudFront log delivery, WAF lookups, and S3 bucket metadata.
• An origin host that CloudFront can reach.
• An ACM certificate in us-east-1 when using custom aliases.
• A CloudFront access log S3 bucket and prefix when access logging is enabled.
• Any referenced Lambda@Edge function versions or CloudFront Functions must already exist.
• Any referenced managed policy IDs, custom cache policy names, or custom origin request policy names must exist or be defined in this module config.

Important Notes

• configurations is the main module input object.
• R2A may merge module defaults with service configuration before Terraform runs.
• Placeholders such as #{Environment}, #{Lifecycle}, #{Repository}, #{Owner}, and #{Project} can be resolved by R2A during deployment.
• web_acl_name takes precedence over web_acl_id when both are set.
• Use cache_policy_id and origin_request_policy_id for existing or AWS-managed policies.
• Use cache_policy_name and origin_request_policy_name only for policies created in the same config under cache_policies and origin_request_policies.
• Ordered cache behaviors are sorted by order; lower numbers run first.
• Set enabled: false on an ordered cache behavior to exclude it from the generated distribution.
• Lambda@Edge associations are enabled by default when a function ARN is present. Set lambda_enabled: false on a behavior association to disable it.
• Lambda@Edge ARNs must reference a published function version, not $LATEST.
• CloudFront viewer certificates for custom aliases require ACM certificates in us-east-1.

Minimal Example

services:
  - name: "AWS CloudFront Distribution"
    module: "aws-cloudfront-distribution"
    id: "my-site-cloudfront"
    configurations:
      region: "us-east-1"
      branch: "#{Environment}"
      enabled: true
      is_ipv6_enabled: true
      comment: "My site CloudFront distribution"
      default_root_object: "index.html"
      price_class: "PriceClass_100"
      aliases:
        - "www.example.com"
      acm_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/example"
      httpVersion: "http2"

      origins:
        app:
          origin_id: "app"
          domain_name: "app.example.com"
          origin_path: ""
          custom_origin_config:
            http_port: 80
            https_port: 443
            origin_protocol_policy: "https-only"
            origin_ssl_protocols: ["TLSv1.2"]
            origin_read_timeout: 60
            origin_keepalive_timeout: 5
          custom_headers:
            "x-set-lifecycle": "#{Lifecycle}"

      cache_policies:
        - name: "site-cache-policy"
          comment: "Default cache policy for www.example.com"
          default_ttl: 86400
          max_ttl: 31536000
          min_ttl: 0
          parameters_in_cache_key_and_forwarded_to_origin:
            enable_accept_encoding_brotli: true
            enable_accept_encoding_gzip: true
            query_strings_config:
              query_string_behavior: "none"
            headers_config:
              header_behavior: "none"
            cookies_config:
              cookie_behavior: "none"

      origin_request_policies:
        - name: "site-origin-request-policy"
          comment: "Forward request values needed by the origin"
          headers_config:
            header_behavior: "none"
          query_strings_config:
            query_string_behavior: "all"
          cookies_config:
            cookie_behavior: "none"

      default_cache_behavior:
        target_origin_id: "app"
        viewer_protocol_policy: "redirect-to-https"
        allowed_methods: ["GET", "HEAD", "OPTIONS"]
        cached_methods: ["GET", "HEAD"]
        compress: true
        # These names reference policies created above in this same config.
        # Use cache_policy_id/origin_request_policy_id for existing or AWS-managed policies.
        cache_policy_name: "site-cache-policy"
        origin_request_policy_name: "site-origin-request-policy"

      logging_s3:
        bucket: "cloudfront-logs.example.com"
        prefix: "www.example.com"
        output_format: "w3c"

      restrictions:
        geo_restriction:
          restriction_type: "none"

      viewer_certificate:
        ssl_support_method: "sni-only"
        minimum_protocol_version: "TLSv1.2_2021"
        cloudfront_default_certificate: false

      tags:
        lifecycle: "#{Lifecycle}"
        owner: "#{Owner}"
        repository: "#{Repository}"

Full Configuration Schema

The fields below are public module inputs under configurations.

Complete structure:

configurations:
  region: "us-east-1"
  branch: "#{Environment}"
  enabled: true
  is_ipv6_enabled: true
  comment: "My CloudFront distribution"
  default_root_object: "index.html"
  price_class: "PriceClass_100"
  aliases: ["www.example.com"]
  web_acl_id: "arn:aws:wafv2:..."
  web_acl_name: "example-web-acl"
  acm_certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/example"
  httpVersion: "http2"
  origins: {}
  origin_groups: {}
  default_cache_behavior: {}
  cache_behaviors: {}
  lambda_function_associations: {}
  cloudfront_function_associations: {}
  custom_error_responses: {}
  logging_s3: {}
  restrictions: {}
  viewer_certificate: {}
  cache_policies: []
  origin_request_policies: []
  tags: {}

Top-Level Fields

Field	Type	Required	Description
region	string	Yes	AWS region used for CloudWatch log delivery resources. CloudFront is global, but log delivery resources are regional.
branch	string	Yes	Environment or branch label used in log delivery resource names and S3 log suffix paths.
enabled	boolean	Yes	Enables or disables the CloudFront distribution.
is_ipv6_enabled	boolean	Yes	Enables IPv6 support for the distribution.
comment	string	Yes	CloudFront distribution comment.
default_root_object	string	Yes	Default object returned by CloudFront for root requests.
price_class	string	Yes	CloudFront price class, such as PriceClass_100, PriceClass_200, or PriceClass_All.
aliases	array[string]	Yes	Alternate domain names for the distribution.
acm_certificate_arn	string	Required for custom aliases	ACM certificate ARN used by the viewer certificate. Custom alias certificates must be in us-east-1.
httpVersion	string	Yes	CloudFront HTTP version, such as http2.
web_acl_id	string	No	WAF Web ACL ARN/ID to associate with the distribution. Used when web_acl_name is not set.
web_acl_name	string	No	WAF Web ACL name looked up with CloudFront scope. Takes precedence over web_acl_id.
origins	map[origin]	Yes	Origin definitions keyed by local origin name.
origin_groups	map[origin_group]	No	Failover origin groups keyed by local group name.
default_cache_behavior	cache_behavior	Yes	Default cache behavior for requests that do not match an ordered behavior.
cache_behaviors	map[cache_behavior]	No	Ordered cache behaviors keyed by local behavior name.
lambda_function_associations	map[lambda_association]	No	Global Lambda@Edge associations used by default and ordered behaviors unless overridden.
cloudfront_function_associations	map[function_association]	No	Global CloudFront Function associations used by default and ordered behaviors unless overridden.
custom_error_responses	map[custom_error_response]	No	Custom error response definitions keyed by local name.
logging_s3	logging_s3	Yes	CloudFront access log delivery destination.
restrictions	restrictions	Yes	Geographic restrictions block.
viewer_certificate	viewer_certificate	Yes	Viewer certificate options. The certificate ARN is read from acm_certificate_arn.
cache_policies	array[cache_policy]	No	Custom CloudFront cache policies created by the module.
origin_request_policies	array[origin_request_policy]	No	Custom CloudFront origin request policies created by the module.
tags	map[string]	No	Tags applied to the CloudFront distribution.

origins

Map of CloudFront origins.

Field	Type	Required	Description
<origin>.origin_id	string	Yes	CloudFront origin ID. Cache behaviors reference this value with target_origin_id.
<origin>.domain_name	string	Yes	DNS name for the origin.
<origin>.origin_path	string	Yes	Optional origin path prefix. Use an empty string when not needed.
<origin>.custom_origin_config	object	Yes	Custom origin connection settings.
<origin>.custom_headers	map[string]	No	Headers CloudFront sends to this origin.

origins.<origin>.custom_origin_config

Field	Type	Required	Description
http_port	number	No	HTTP port. Falls back to the module kubernetes_service_port variable when omitted.
https_port	number	Yes	HTTPS port.
origin_protocol_policy	string	Yes	Origin protocol policy, such as http-only, https-only, or match-viewer.
origin_ssl_protocols	array[string]	Yes	TLS protocols CloudFront may use with the origin.
origin_read_timeout	number	Yes	Origin read timeout in seconds.
origin_keepalive_timeout	number	Yes	Origin keep-alive timeout in seconds.

origin_groups

Map of failover origin groups.

Field	Type	Required	Description
<group>.origin_group_id	string	Yes	CloudFront origin group ID.
<group>.primary_origin_id	string	Yes	Primary origin ID.
<group>.secondary_origin_id	string	Yes	Secondary origin ID used for failover.
<group>.failover_criteria.status_codes	array[number]	No	HTTP status codes that trigger failover. Defaults to [500, 502, 503, 504].

default_cache_behavior

Default cache behavior for all requests that do not match an ordered behavior.

Field	Type	Required	Description
target_origin_id	string	Yes	Origin ID or origin group ID for the default behavior.
viewer_protocol_policy	string	Yes	Viewer protocol policy, such as redirect-to-https, https-only, or allow-all.
allowed_methods	array[string]	Yes	HTTP methods CloudFront accepts.
cached_methods	array[string]	Yes	HTTP methods CloudFront caches.
compress	boolean	Yes	Enables CloudFront compression.
cache_policy_id	string	Conditional	Cache policy ID. Used when set; otherwise cache_policy_name is resolved against custom policies created by this module.
cache_policy_name	string	Conditional	Name of a custom cache policy created by this module. Used when cache_policy_id is empty.
origin_request_policy_id	string	Conditional	Origin request policy ID. Used when set; otherwise origin_request_policy_name is resolved against custom policies created by this module.
origin_request_policy_name	string	Conditional	Name of a custom origin request policy created by this module. Used when origin_request_policy_id is empty.
lambda_function_associations	map[lambda_association]	No	Behavior-specific Lambda@Edge associations.
cloudfront_function_associations	map[function_association]	No	Behavior-specific CloudFront Function associations.

cache_behaviors

Map of ordered cache behaviors. Each entry supports the fields below.

Field	Type	Required	Description
<behavior>.path_pattern	string	Yes	URL path pattern matched by this ordered behavior.
<behavior>.order	number	No	Sort order. Lower numbers are emitted first. Defaults to 999 for sorting when omitted.
<behavior>.enabled	boolean	No	Set to false to exclude this behavior from the distribution. Defaults to true.
<behavior>.target_origin_id	string	Yes	Origin ID used by this behavior.
<behavior>.viewer_protocol_policy	string	Yes	Viewer protocol policy.
<behavior>.allowed_methods	array[string]	Yes	HTTP methods CloudFront accepts for this behavior.
<behavior>.cached_methods	array[string]	Yes	HTTP methods CloudFront caches for this behavior.
<behavior>.compress	boolean	Yes	Enables CloudFront compression for this behavior.
<behavior>.cache_policy_id	string	Conditional	Cache policy ID. Used unless a non-empty cache_policy_name resolves to a custom policy created by this module.
<behavior>.cache_policy_name	string	Yes	Name of a custom cache policy created by this module. Use an empty string when selecting by cache_policy_id.
<behavior>.origin_request_policy_id	string	Conditional	Origin request policy ID. Used unless a non-empty origin_request_policy_name resolves to a custom policy created by this module.
<behavior>.origin_request_policy_name	string	Yes	Name of a custom origin request policy created by this module. Use an empty string when selecting by origin_request_policy_id.
<behavior>.lambda_function_associations	map[lambda_association]	No	Behavior-specific Lambda@Edge associations.
<behavior>.cloudfront_function_associations	map[function_association]	No	Behavior-specific CloudFront Function associations.

lambda_function_associations

Lambda@Edge associations may be defined globally, on default_cache_behavior, or on an ordered cache behavior.

Allowed event keys are origin-request, origin-response, viewer-request, and viewer-response.

Field	Type	Required	Description
<event>.lambda_enabled	boolean	No	Enables or disables this association. Defaults to enabled when a function ARN is present.
<event>.lambda_function_arn	string	Conditional	Published Lambda@Edge function version ARN. Required when the association is enabled.
<event>.include_body	boolean	No	Includes request body for supported event types. Defaults to false.

cloudfront_function_associations

CloudFront Function associations may be defined globally, on default_cache_behavior, or on an ordered cache behavior.

Allowed event keys are viewer-request and viewer-response.

Field	Type	Required	Description
<event>.function_arn	string	Yes	CloudFront Function ARN.

custom_error_responses

Map of custom error responses.

Field	Type	Required	Description
<response>.error_code	number	Yes	HTTP status code handled by this custom error response.
<response>.error_caching_min_ttl	number	Yes	Minimum TTL, in seconds, for caching this error response.

logging_s3

CloudFront access log delivery to S3.

Field	Type	Required	Description
bucket	string	Yes	S3 bucket name used as the log destination.
prefix	string	Yes	S3 prefix used for log delivery destination and generated suffix paths.
output_format	string	Yes	Log output format. Usually w3c.
record_fields	array[string]	No	Optional CloudFront log fields to include.

restrictions

Geographic restriction settings.

Field	Type	Required	Description
geo_restriction.restriction_type	string	Yes	Restriction type, such as none, whitelist, or blacklist.

viewer_certificate

Viewer certificate options. The certificate ARN is read from top-level acm_certificate_arn.

Field	Type	Required	Description
ssl_support_method	string	Yes	SSL support method, such as sni-only.
minimum_protocol_version	string	Yes	Minimum TLS protocol version, such as TLSv1.2_2021.
cloudfront_default_certificate	boolean	Yes	Whether to use the default CloudFront certificate. Usually false when custom aliases are set.

cache_policies

Array of custom CloudFront cache policies created by this module.

Field	Type	Required	Description
name	string	Yes	Cache policy name.
comment	string	Yes	Cache policy comment.
default_ttl	number	Yes	Default TTL in seconds.
max_ttl	number	Yes	Maximum TTL in seconds.
min_ttl	number	Yes	Minimum TTL in seconds.
parameters_in_cache_key_and_forwarded_to_origin.enable_accept_encoding_brotli	boolean	No	Enables Brotli compression in cache key and origin forwarding settings. Defaults to false.
parameters_in_cache_key_and_forwarded_to_origin.enable_accept_encoding_gzip	boolean	No	Enables gzip compression in cache key and origin forwarding settings. Defaults to false.
parameters_in_cache_key_and_forwarded_to_origin.query_strings_config.query_string_behavior	string	No	Query string behavior. Defaults to none. Use whitelist with query_strings.items.
parameters_in_cache_key_and_forwarded_to_origin.query_strings_config.query_strings.items	array[string]	Conditional	Query string names when query string behavior is whitelist.
parameters_in_cache_key_and_forwarded_to_origin.headers_config.header_behavior	string	No	Header behavior. Defaults to none. Use whitelist with headers.items.
parameters_in_cache_key_and_forwarded_to_origin.headers_config.headers.items	array[string]	Conditional	Header names when header behavior is whitelist.
parameters_in_cache_key_and_forwarded_to_origin.cookies_config.cookie_behavior	string	No	Cookie behavior. Defaults to none. Use whitelist with cookies.items.
parameters_in_cache_key_and_forwarded_to_origin.cookies_config.cookies.items	array[string]	Conditional	Cookie names when cookie behavior is whitelist.

origin_request_policies

Array of custom CloudFront origin request policies created by this module.

Field	Type	Required	Description
name	string	Yes	Origin request policy name.
comment	string	Yes	Origin request policy comment.
headers_config.header_behavior	string	No	Header behavior. Defaults to none. Use whitelist with headers.items.
headers_config.headers.items	array[string]	Conditional	Header names when header behavior is whitelist.
query_strings_config.query_string_behavior	string	No	Query string behavior. Defaults to none. Use whitelist with query_strings.items.
query_strings_config.query_strings.items	array[string]	Conditional	Query string names when query string behavior is whitelist.
cookies_config.cookie_behavior	string	No	Cookie behavior. Defaults to none. Use whitelist with cookies.items.
cookies_config.cookies.items	array[string]	Conditional	Cookie names when cookie behavior is whitelist.