Network Firewall Proxy Resources (Preview)

[alexbacchin]

Note: This PR is submitted as a draft to seek early feedback from maintainers. The Network Firewall Proxy service is currently in public preview. We anticipate maintainers may prefer to hold merging until the service reaches General Availability (GA). In the meantime, this PR aims to gather design feedback on the resource structure, API mapping choices, and Terraform patterns used.

Summary

This PR adds Terraform support for AWS Network Firewall Proxy, a managed HTTP/HTTPS forward proxy that integrates with NAT Gateways. Five new resources are introduced:

Resource	Description
aws_networkfirewall_proxy	The proxy itself, attached to a NAT Gateway
aws_networkfirewall_proxy_configuration	Configuration defining default phase actions
aws_networkfirewall_proxy_rule_group	Container for proxy rules
aws_networkfirewall_proxy_rules_exclusive	Exclusive management of rules within a rule group
aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive	Exclusive management of rule group attachments to a proxy configuration

Resource Hierarchy

aws_networkfirewall_proxy_configuration
  └── aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive
        └── aws_networkfirewall_proxy_rule_group
              └── aws_networkfirewall_proxy_rules_exclusive

aws_networkfirewall_proxy  (references the proxy configuration above)

Design Decisions

Exclusive Resources for Rules and Rule Group Attachments

The Network Firewall Proxy API manages rules and rule group attachments independently from the parent resources (ProxyRuleGroup and ProxyConfiguration). This mirrors existing patterns in the AWS provider (e.g. aws_iam_role_policies_exclusive).

Two exclusive resources are used instead of embedding everything into parent resources:

• aws_networkfirewall_proxy_rules_exclusive — owns all rules in a proxy rule group. Any rule not declared in Terraform will be removed. This provides predictable, authoritative management.
• aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive — owns all rule group attachments for a proxy configuration with the same authoritative behaviour.

This split allows aws_networkfirewall_proxy_rule_group and aws_networkfirewall_proxy_configuration to remain lightweight resources (name, description, tags), while rule content and group membership are managed separately. It also enables independent lifecycle management — e.g. attaching/detaching rule groups without destroying the configuration.

Rule Ordering and InsertPosition

The Network Firewall Proxy API requires an InsertPosition integer when creating rules, and rules are evaluated in the order they were inserted. The API does not expose a single UpdateProxyRules call that replaces the full rule set — instead it uses:

• CreateProxyRules (with InsertPosition)
• UpdateProxyRule (modifies action/conditions of an existing rule by name)
• DeleteProxyRules (removes rules by name)

This creates a challenge for Terraform: the API's positional model does not map cleanly to a declarative set. Using a set would lose ordering guarantees, and using a map would require users to manage positions manually.

Decision: Rules are modelled as ordered list blocks within each request phase (pre_dns, pre_request, post_response). The list index directly corresponds to InsertPosition. This gives users a natural, readable way to control rule order in HCL:

resource "aws_networkfirewall_proxy_rules_exclusive" "example" {
  proxy_rule_group_arn = aws_networkfirewall_proxy_rule_group.example.arn

  pre_dns {                          # position 0 — evaluated first
    proxy_rule_name = "block-malicious-domains"
    action          = "DROP"
    conditions {
      condition_key      = "request:DestinationDomain"
      condition_operator = "StringEquals"
      condition_values   = ["malicious.com", "badactor.net"]
    }
  }

  pre_request {                      # position 0
    proxy_rule_name = "allow-api-requests"
    action          = "ALLOW"
    conditions {
      condition_key      = "request:Http:Uri"
      condition_operator = "StringEquals"
      condition_values   = ["/api/v1", "/api/v2"]
    }
  }

  post_response {                    # position 0
    proxy_rule_name = "block-server-errors"
    action          = "DROP"
    conditions {
      condition_key      = "response:Http:StatusCode"
      condition_operator = "NumericGreaterThanEquals"
      condition_values   = ["500"]
    }
  }
}

Update logic: During updates, the resource compares plan vs. state position-by-position per phase:

• Same name at same position with changed attributes → UpdateProxyRule
• Different name at a position (reorder/replace) → delete old + recreate with new InsertPosition
• Extra rules removed from the plan → DeleteProxyRules
• New rules appended → CreateProxyRules with appropriate position

Deletions are always processed before creations to satisfy the API's uniqueness constraint on proxy_rule_name within a rule group.

Rule Group Attachment Ordering

Similarly, rule group attachments within a proxy configuration have an API-managed priority. The aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive resource uses an ordered rule_group list, where list index maps to InsertPosition/priority. Reordering is handled via UpdateProxyRuleGroupPriorities.

TLS Interception

The aws_networkfirewall_proxy resource supports TLS interception via the tls_intercept_properties block. When tls_intercept_mode = "ENABLED", an AWS Private CA ARN (pca_arn) must be provided. TLS interception is required for HTTP field inspection (URI, headers, method) on HTTPS traffic.

Listener Properties

The proxy supports up to 2 listener configurations (HTTP on port 8080, HTTPS on port 443 are typical). Listeners can be updated in-place using ListenerPropertiesToAdd / ListenerPropertiesToRemove API fields without replacement of the proxy.

Serial Acceptance Tests

The Proxy API enforces strict concurrency limits during preview. All acceptance tests for these resources are serialised via a single TestAccNetworkFirewallProxy_serial test function using acctest.RunSerialTests2Levels.

End-to-End Example

# 1. Proxy Configuration with default-allow behaviour
resource "aws_networkfirewall_proxy_configuration" "example" {
  name = "example"

  default_rule_phase_actions {
    pre_dns       = "ALLOW"
    pre_request   = "ALLOW"
    post_response = "ALLOW"
  }
}

# 2. Rule Group container
resource "aws_networkfirewall_proxy_rule_group" "example" {
  name        = "example"
  description = "Corporate traffic policy"
}

# 3. Rules within the group (exclusive ownership)
resource "aws_networkfirewall_proxy_rules_exclusive" "example" {
  proxy_rule_group_arn = aws_networkfirewall_proxy_rule_group.example.arn

  pre_dns {
    proxy_rule_name = "block-malicious-domains"
    action          = "DROP"
    conditions {
      condition_key      = "request:DestinationDomain"
      condition_operator = "StringEquals"
      condition_values   = ["malicious.com"]
    }
  }

  pre_request {
    proxy_rule_name = "allow-corporate-traffic"
    action          = "ALLOW"
    conditions {
      condition_key      = "request:SourceVpc"
      condition_operator = "StringEquals"
      condition_values   = [aws_vpc.corporate.id]
    }
  }
}

# 4. Attach rule group to configuration (exclusive ownership)
resource "aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive" "example" {
  proxy_configuration_arn = aws_networkfirewall_proxy_configuration.example.arn

  rule_group {
    proxy_rule_group_name = aws_networkfirewall_proxy_rule_group.example.name
  }
}

# 5. The Proxy (attached to a NAT Gateway)
resource "aws_networkfirewall_proxy" "example" {
  name                    = "example"
  nat_gateway_id          = aws_nat_gateway.example.id
  proxy_configuration_arn = aws_networkfirewall_proxy_configuration.example.arn

  tls_intercept_properties {
    tls_intercept_mode = "DISABLED"
  }

  listener_properties {
    port = 8080
    type = "HTTP"
  }

  listener_properties {
    port = 443
    type = "HTTPS"
  }
}

Test Coverage

Resource	Test Cases
aws_networkfirewall_proxy	basic, disappears, tls_intercept_enabled, logging
aws_networkfirewall_proxy_configuration	basic, disappears, tags
aws_networkfirewall_proxy_rule_group	basic, disappears, tags
aws_networkfirewall_proxy_rules_exclusive	basic, disappears, update_add, update_modify, update_remove, multiple_rules_per_phase
aws_networkfirewall_proxy_configuration_rule_group_attachments_exclusive	basic, disappears, update_add, update_remove, update_reorder

Open Questions / Known Limitations

• Service in preview: Some API behaviours (e.g. UpdateProxyRule for conditions) were found to behave unexpectedly during testing. These may be resolved before GA.
• proxy_rule_name uniqueness: Rule names must be unique across all phases within a rule group. The resource enforces this via delete-before-create ordering during updates.
• No ListProxies pagination: The current implementation uses ARN-based describe calls; no list data sources are included in this PR.

References

Closes #45265

• AWS Network Firewall Proxy documentation

AI Disclosure

All code in this PR was generated by Claude Code (Anthropic's AI coding assistant). The resource design decisions — including the exclusive resource pattern, ordered list modelling for rules/attachments, update strategy (delete-before-create), and the overall resource hierarchy — were made by the PR author. Claude Code was used to implement those decisions, write tests, and fix CI lint/formatting issues.

🤖 Generated with Claude Code

[github-actions]

Community Guidelines

This comment is added to every new Pull Request to provide quick reference to how the Terraform AWS Provider is maintained. Please review the information below, and thank you for contributing to the community that keeps the provider thriving! 🚀

Voting for Prioritization

• Please vote on this Pull Request by adding a 👍 reaction to the original post to help the community and maintainers prioritize it.
• Please see our prioritization guide for additional information on how the maintainers handle prioritization.
• Please do not leave +1 or other comments that do not add relevant new information or questions; they generate extra noise for others following the Pull Request and do not help prioritize the request.

Pull Request Authors

• Review the contribution guide relating to the type of change you are making to ensure all of the necessary steps have been taken.
• Whether or not the branch has been rebased will not impact prioritization, but doing so is always a welcome surprise.