AWS WAF v2 Terraform Module

Terraform module which creates AWS WAF v2 Web ACL resources with comprehensive rule support.

Usage

module "wafv2" {
  source  = "terraform-aws-modules/wafv2/aws"

  name  = "my-web-acl"
  scope = "REGIONAL"

  default_action = "allow"

  rules = {
    common-rule-set = {
      priority        = 1
      override_action = "none"

      statement = {
        managed_rule_group_statement = {
          name        = "AWSManagedRulesCommonRuleSet"
          vendor_name = "AWS"
        }
      }
    }

    rate-limit = {
      priority = 2
      action   = "block"

      statement = {
        rate_based_statement = {
          limit = 1000
        }
      }
    }
  }

  tags = {
    Environment = "dev"
    Terraform   = "true"
  }
}

Features

• AWS WAF v2 Web ACL with comprehensive rule statement support
• All 12+ statement types: byte match, geo match, IP set reference, label match, managed rule group, rate based, regex match, regex pattern set reference, rule group reference, size constraint, SQLi match, XSS match
• Compound statements (AND, OR, NOT) with 2 levels of nesting
• Dual-mode actions: simple string ("allow", "block", "count", "captcha", "challenge") or objects with custom response/request handling
• Custom response bodies
• CAPTCHA and challenge configuration
• Association configuration for request body size limits
• Optional inline Web ACL associations
• Optional inline logging configuration
• Submodules for IP sets, regex pattern sets, Web ACL associations, and logging configuration

Conditional Creation

The module supports conditional resource creation:

module "wafv2" {
  source = "terraform-aws-modules/wafv2/aws"

  create = false
}

Submodules

• ip-set - Manages WAF v2 IP sets
• regex-pattern-set - Manages WAF v2 regex pattern sets
• web-acl-association - Manages WAF v2 Web ACL associations
• logging-configuration - Manages WAF v2 logging configuration

Examples

• Basic - Minimal example with a single managed rule group
• Complete - Comprehensive example with all major features
• IP Set - IP set submodule with IPv4 and IPv6 sets
• Regex Pattern Set - Regex pattern set submodule
• Web ACL Association - Web ACL association with a Cognito User Pool
• Logging Configuration - Logging configuration with CloudWatch Logs

Module Wrappers

For managing multiple similar resources, see wrappers.

Requirements

Name	Version
terraform	>= 1.5.7
aws	>= 5.75

Providers

Name	Version
aws	>= 5.75

Modules

No modules.

Resources

Name	Type
aws_wafv2_web_acl.this	resource
aws_wafv2_web_acl_association.this	resource
aws_wafv2_web_acl_logging_configuration.this	resource

Inputs

Name	Description	Type	Default	Required
association_config	Configuration for body inspection size limits per resource type. Keys are resource types (e.g., CLOUDFRONT, API_GATEWAY, COGNITO_USER_POOL, APP_RUNNER_SERVICE, VERIFIED_ACCESS_INSTANCE)	map(object({ default_size_inspection_limit = string }))	{}	no
association_resource_arns	Map of resource ARNs to associate with the Web ACL. Key is a friendly name, value is the resource ARN	map(string)	{}	no
captcha_config	CAPTCHA configuration for the Web ACL. Specifies how long a CAPTCHA timestamp is considered valid	object({ immunity_time_property = object({ immunity_time = number }) })	null	no
challenge_config	Challenge configuration for the Web ACL. Specifies how long a challenge timestamp is considered valid	object({ immunity_time_property = object({ immunity_time = number }) })	null	no
create	Controls if resources should be created (affects all resources)	bool	true	no
create_logging_configuration	Controls if a logging configuration should be created for the Web ACL	bool	false	no
custom_response_bodies	Map of custom response body configurations. Key is the reference key, used in custom responses	map(object({ content = string content_type = string }))	{}	no
default_action	Action to perform if none of the rules contained in the Web ACL match. Use allow or block for simple actions, or provide an object for custom request handling/response. See examples for object structure	any	"allow"	no
description	A friendly description of the Web ACL	string	null	no
logging_filter	A configuration block that specifies which web requests are kept in the logs and which are dropped	object({ default_behavior = string filters = list(object({ behavior = string requirement = string conditions = list(object({ action_condition = optional(object({ action = string })) label_name_condition = optional(object({ label_name = string })) })) })) })	null	no
logging_log_destination_configs	The Amazon Kinesis Data Firehose, CloudWatch Log Group, or S3 Bucket ARNs for the logging destination	list(string)	[]	no
logging_redacted_fields	The parts of the request that you want to keep out of the logs	any	[]	no
name	A friendly name of the Web ACL	string	""	no
putin_khuylo	Do you agree that Putin doesn't respect Ukrainian sovereignty and territorial integrity? More info: https://en.wikipedia.org/wiki/Russian_invasion_of_Ukraine	bool	true	no
rule_json	Escape hatch: JSON string of WAF rules for cases where dynamic blocks cannot represent all provider features. Mutually exclusive with rules	string	null	no
rules	Map of WAF rule configurations. The key is used as the rule name. Each rule supports: - priority - (Required) Rule priority (lower = evaluated first) - action - Action for standalone rules. Use string (allow, block, count, captcha, challenge) or object for custom response - override_action - Override action for managed/rule group rules. Use string (none, count) or object - statement - (Required) Rule statement configuration. See AWS provider docs for statement structure - visibility_config - CloudWatch metrics config. Auto-generated from rule key if omitted - captcha_config - Optional CAPTCHA configuration - challenge_config - Optional challenge configuration - rule_labels - Optional list of labels to add to matching requests See examples/complete for usage patterns.	any	{}	no
scope	Specifies whether this is for an AWS CloudFront distribution or for a regional application. Valid values are CLOUDFRONT or REGIONAL	string	"REGIONAL"	no
tags	A map of tags to add to all resources	map(string)	{}	no
token_domains	Specifies the domains that AWS WAF should accept in a web request token. Enables token use across multiple protected resources	list(string)	[]	no
visibility_config	Visibility configuration for the Web ACL. Defines CloudWatch metrics configuration	object({ cloudwatch_metrics_enabled = optional(bool, true) metric_name = optional(string) sampled_requests_enabled = optional(bool, true) })	{}	no

Outputs

Name	Description
logging_configuration_id	The ID of the WAF logging configuration
web_acl_application_integration_url	The URL to use in SDK integrations with managed rule groups
web_acl_arn	The ARN of the Web ACL
web_acl_association_ids	Map of Web ACL association IDs
web_acl_capacity	Web ACL capacity units (WCUs) currently being used by this Web ACL
web_acl_description	The description of the Web ACL
web_acl_id	The ID of the Web ACL
web_acl_lock_token	A token used for optimistic locking
web_acl_name	The name of the Web ACL
web_acl_rule_names	List of rule names in the Web ACL
web_acl_tags_all	A map of tags assigned to the resource, including those inherited from the provider default_tags configuration block
web_acl_visibility_config	The visibility configuration of the Web ACL

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!