Terraform配置CloudFront关联WAF时Scope参数异常问题排查

核心原因 #

CloudFront只能关联Scope为CLOUDFRONT的WAFv2 Web ACL，你大概率遇到了以下两类矛盾场景：

1. 创建WAF ACL时误用了REGIONAL Scope，关联CloudFront时系统检测到Scope不匹配报错；但如果改成非CLOUDFRONT的Scope，AWS关联逻辑又强制要求必须用CLOUDFRONT，形成冲突。
2. Terraform资源引用错误——你把REGIONAL作用域的WAF ACL的ARN传给了CloudFront的web_acl_id参数，导致Scope校验失败。

要明确：AWS的WAFv2中，CLOUDFRONT作用域的ACL是全局资源，和REGIONAL作用域的ACL是完全独立的两套体系，绝对不能跨作用域关联。

解决步骤 #

1. 创建CLOUDFRONT作用域的WAFv2 Web ACL #

所有和CloudFront关联的WAF资源（包括Web ACL、IP集合、规则组等）必须统一设置scope = "CLOUDFRONT"，示例代码：

# 创建CLOUDFRONT作用域的Web ACL
resource "aws_wafv2_web_acl" "cloudfront_acl" {
  name        = "cloudfront-waf-acl"
  scope       = "CLOUDFRONT" # 必须指定该值
  description = "防护CloudFront分发的WAF规则集"
  default_action {
    allow {}
  }
  visibility_config {
    cloudwatch_metrics_enabled = true
    metric_name                = "cloudfront-waf-acl-metric"
    sampled_requests_enabled   = true
  }

  # 示例：添加IP白名单规则
  rule {
    name     = "IP-Whitelist"
    priority = 1
    action {
      allow {}
    }
    statement {
      ip_set_reference_statement {
        arn = aws_wafv2_ip_set.whitelist.arn
      }
    }
    visibility_config {
      cloudwatch_metrics_enabled = true
      metric_name                = "ip-whitelist-rule"
      sampled_requests_enabled   = true
    }
  }
}

# 配套的CLOUDFRONT作用域IP集合
resource "aws_wafv2_ip_set" "whitelist" {
  name               = "ip-whitelist"
  scope              = "CLOUDFRONT" # 必须和ACL的Scope一致
  ip_address_version = "IPV4"
  addresses          = ["192.168.1.0/24"]
}

2. 在CloudFront资源中正确关联该ACL #

在CloudFront分发配置里，将web_acl_id设置为上述CLOUDFRONT作用域ACL的ARN：

resource "aws_cloudfront_distribution" "example" {
  # 省略其他CloudFront基础配置（如源站、缓存行为等）...

  # 关键：关联正确的WAF ACL
  web_acl_id = aws_wafv2_web_acl.cloudfront_acl.arn

  # 省略剩余配置...
}

额外注意事项 #

• 不要尝试将REGIONAL作用域的WAF ACL关联给CloudFront，这是AWS的硬性限制，没有变通方法。
• 若之前创建了REGIONAL的WAF资源，无需删除，但要确保CloudFront引用的是CLOUDFRONT作用域的那一套资源。
• 部署前用terraform plan检查资源依赖，确认WAF的Scope和CloudFront的引用是否匹配。

内容的提问来源于stack exchange，提问作者Carabes