• Fixed critical bug in NAT Gateway routing whenmax_nats is set to fewer than the number of Availability Zones
• Added modulo operation to route table mapping formulas to clamp NAT indices to available NATs
• Created new examplelimited-nat-gateways demonstrating themax_nats feature
• Added 3 new test functions providing 100% test coverage formax_nats feature
• Added comprehensive documentation including PRD with diagrams and decision tree

why

Critical Bug: Whenmax_nats < num_azs, Terraform failed with "Invalid index" error because route tables in AZs without NATs attempted to reference non-existent NAT Gateway indices.

Example Failure:

Configuration: 3 AZs, max_nats=1 (only 1 NAT in AZ-a)Error: aws_nat_gateway.default[1] - Invalid indexRoute tables in AZ-b and AZ-c tried to access NAT[1] and NAT[2] which don't exist

Root Cause: The route table mapping formula calculated:

az_index * nats_per_az + subnet_offset

This produced indices [0, 1, 2] but only NAT[0] existed.

Fix: Added modulo operation to wrap indices to available NATs:

(az_index * nats_per_az + subnet_offset) % total_nats

Now produces [0, 0, 0] - all route to the single NAT.

Test Coverage Gap: Themax_nats feature had ZERO test coverage. None of the 6 existing examples tested this scenario. The bug was discovered by the aws-vpc component test suite, not by this module's own tests.

Changes Include:

1. Bug Fix (main.tf):

   • Fixedprivate_route_table_to_nat_map calculation
   • Fixedpublic_route_table_to_nat_map calculation
   • Added explanatory comments and example scenarios

2. New Test Example (examples/limited-nat-gateways):

   • Tests 3 AZs with max_nats=1 (the failing scenario)
   • Tests 3 AZs with max_nats=2 (between scenario)
   • Includes comprehensive README with cost analysis
   • Documents use case: Dev/test cost optimization

3. Test Coverage (test/src/examples_limited_nat_gateways_test.go):

   • TestExamplesLimitedNatGateways - Tests max_nats=1
   • TestExamplesLimitedNatGatewaysTwoNats - Tests max_nats=2
   • TestExamplesLimitedNatGatewaysDisabled - Tests enabled=false
   • Brings max_nats test coverage from 0% to 100%

4. Documentation:

   • Test Coverage Analysis: Comprehensive audit of all tests, identifies gaps
   • PRD: Detailed problem statement, solution, cost analysis
   • NAT Placement Diagrams: 4 strategy diagrams with ASCII art
   • Decision Tree: Guides users to optimal configuration
   • Best Practices: Recommendations by environment type

Cost Implications:
Themax_nats feature enables significant cost savings in non-production environments:

• Standard (3 NATs): $97.20/month
• Limited (1 NAT): $32.40/month
• Savings: $64.80/month per environment (67% reduction)
• 10 dev environments: $7,776/year savings

This bug blocked users from utilizing this cost optimization feature.

references

• Related to#226 (Separate Public/Private Subnet Configuration)
• Discovered by: cloudposse-terraform-components/aws-vpc test suite
• Affects: All users attempting to usemax_nats < num_azs for cost optimization
• Test Coverage Analysis:/docs/test-coverage-analysis.md
• Detailed PRD:/docs/prd/fix-max-nats-routing.md