what

• Fixed critical bug in NAT Gateway routing when max_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 example limited-nat-gateways demonstrating the max_nats feature
• Added 3 new test functions providing 100% test coverage for max_nats feature
• Added comprehensive documentation including PRD with diagrams and decision tree

why

Critical Bug: When max_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 index
Route 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: The max_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):

   • Fixed private_route_table_to_nat_map calculation
   • Fixed public_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:
The max_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 use max_nats < num_azs for cost optimization
• Test Coverage Analysis: /docs/test-coverage-analysis.md
• Detailed PRD: /docs/prd/fix-max-nats-routing.md

what

• Add ability to configure different numbers of public and private subnets per Availability Zone independently
• Add controlled NAT Gateway placement by subnet index to reduce costs
• Add intuitive NAT Gateway placement by subnet name for better usability
• Fix critical NAT Gateway placement bug causing wrong AZ distribution
• Fix cross-AZ routing issue where private subnets routed to NATs in different AZs
• Add comprehensive examples demonstrating cost-optimized and high-availability configurations
• Add full test coverage with Terratest for all new features
• Maintain 100% backward compatibility with existing configurations

why

User Pain Points:

• Users were forced to create equal numbers of public and private subnets, even when workloads didn't require it
• NAT Gateways were created in every public subnet, resulting in unnecessarily high AWS costs (~$32/month per NAT)
• No control over which public subnets received NAT Gateways
• Index-based configuration was not intuitive for users who assigned names to subnets
• Critical bugs caused NAT Gateways to be placed in wrong AZs and private subnets to route across AZ boundaries

Business Impact:

• Cost Optimization: Reducing from 6 NATs to 3 NATs saves $96/month (50% reduction)
• Flexibility: Users can now match subnet configuration to their actual workload requirements
• Reliability: Fixes ensure NAT Gateways are correctly distributed across AZs and routing stays within same AZ
• Usability: Name-based placement is more intuitive and maintainable than index-based placement

Key Features:

1. Separate Public/Private Subnet Counts: New variables public_subnets_per_az_count, public_subnets_per_az_names, private_subnets_per_az_count, private_subnets_per_az_names allow independent control while falling back to original variables for backward compatibility

2. Controlled NAT Placement by Index: Variable nat_gateway_public_subnet_indices (default [0]) specifies which subnet position(s) in each AZ receive NAT Gateways, enabling cost optimization

3. Named NAT Placement: Variable nat_gateway_public_subnet_names allows intuitive placement like ["loadbalancer"] instead of remembering indices

4. Bug Fixes: Corrected NAT Gateway global index calculation and route table mapping to ensure proper AZ distribution and same-AZ routing

Examples Included:

• examples/separate-public-private-subnets/: Cost-optimized with 1 NAT per AZ (~$110/month)
• examples/redundant-nat-gateways/: High-availability with 2 NATs per AZ (~$140/month)

Test Coverage:

• Full Terratest coverage for both examples
• Tests for name-based and index-based NAT placement
• Tests for disabled state (no resources created)
• Verification of all outputs, subnet counts, NAT counts, and route table mappings

references

• Comprehensive PRD: docs/prd/separate-public-private-subnets-and-nat-placement.md

what

• Update go 1.24

why

• Error loading shared library libresolv.so.2 in Go 1.20

References

• https://sweetops.slack.com/archives/G014YEKDH4K/p1746672149263629
• https://github.com/golang/go/issues/59305#issuecomment-1488478737
• https://github.com/cloudposse/terraform-aws-cloudfront-s3-cdn/pull/294/#issuecomment-2859195553

what

• Remove Makefile
• Add atmos.yaml

why

• Replace build-harness with atmos for readme genration

References

• DEV-3229 Migrate from build-harness to atmos

what

• Update .github/settings.yml
• Update .github/chatops.yml files

why

• Re-apply .github/settings.yml from org level to get terratest environment
• Migrate to new test account

References

• DEV-388 Automate clean up of test account in new organization
• DEV-387 Update terratest to work on a shared workflow instead of a dispatch action
• DEV-386 Update terratest to use new testing account with GitHub OIDC

what

• Update .github/settings.yml
• Drop .github/auto-release.yml files

why

• Re-apply .github/settings.yml from org level
• Use organization level auto-release settings

references

• DEV-1242 Add protected tags with Repository Rulesets on GitHub

what

• Update workflow (.github/workflows/release.yaml) to have permission to comment on PR

why

• So we can support commenting on PRs with a link to the release

what

• Update workflows (.github/workflows) to use shared workflows from .github repo

why

• Reduce nested levels of reusable workflows

what

• Update workflows (.github/workflows) to add issue: write permission needed by ReviewDog tflint action

why

• The ReviewDog action will comment with line-level suggestions based on linting failures

what

• Update workflows (.github/workflows/settings.yaml)

why

• Support new readme generation workflow.
• Generate banners

what

• Install latest GitHub Action Workflows

why

• Use shared workflows from cldouposse/.github repository
• Simplify management of workflows from centralized hub of configuration

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

what

• Install a repository config (.github/settings.yaml)

why

• Programmatically manage GitHub repo settings

what

This is an auto-generated PR that updates the README.md and docs

why

To have most recent changes of README.md and doc from origin templates

what

• Reran make readme to rebuild README.md from README.yaml
• Migrate to square badges
• Add scaffolding for repo settings and Mergify

why

• Upstream template changed in the .github repo
• Work better with repository rulesets
• Modernize look & feel