feat: default calculated_subnet_az_capacity to 3 AZ slots

Three AZs is the most common regional layout; the previous default of 6
reserved slots most deployments never use and broke small VPCs (e.g. a /24
inspection VPC with three /28 groups). Regions with more AZs can raise the
value up to 6.

The value is fixed at creation time: changing it on an existing VPC
renumbers calculated subnets. Documented in the variable description,
docs/addressing.md, and the CHANGELOG.

Tests: existing slot-stability runs pin the value they were written
against (6); two new runs exercise the new default (full three-slot
allocation within a /24, and 1->2 AZ scale-up without renumbering).
Suite: 182 passed, 0 failed. Mutation check: reverting the default to 6
fails 4 runs.

Author: Cristobal

CHANGELOG.md

@@ -25,6 +25,7 @@ All notable changes to this module are documented in this file. The format follo
 - Moved NAT configuration to a VPC-wide contract and made subnet groups opt into NAT routing independently.
 - Made isolated subnet roles fail closed for Internet, NAT, TGW, Cloud WAN, and generic routes; injected isolated route tables require an explicit caller-responsibility opt-in.
 - Split outputs into stable Tier 1 handles, deprecated Tier 2 v4 compatibility aliases, and unstable Tier 3 provider-shaped collections.
+- Set `calculated_subnet_az_capacity` to a default of 3 reserved AZ slots per calculated subnet group, matching the most common regional layout; regions with more AZs can raise it up to 6. The value is fixed at creation time: changing it on an existing VPC renumbers calculated subnets.
 
 ### Deprecated
 

README.md

@@ -86,7 +86,7 @@ Each subnet group selects exactly one IPv4 mode:
 | Calculated | `netmask`, optionally `cidr_index` | Deterministic; pin groups that must not move. |
 | IPAM | `ipam_pool_id` and `netmask_length` | CIDR may remain unknown until apply. |
 
-Calculated allocation reserves six AZ slots per group. A pinned `cidr_index` is an absolute group slot and does not move when other groups or AZs are added. Unpinned groups pack largest-first and then alphabetically, so adding or removing an earlier group can move later unpinned ranges.
+Calculated allocation reserves three AZ slots per group by default (`calculated_subnet_az_capacity`, raisable to six). A pinned `cidr_index` is an absolute group slot and does not move when other groups or AZs are added. Unpinned groups pack largest-first and then alphabetically, so adding or removing an earlier group can move later unpinned ranges.
 
 `ipv4.secondary_cidr_key` selects the parent secondary IPv4 association. Omitting it selects the primary VPC CIDR.
 

docs/addressing.md

@@ -85,9 +85,10 @@ locals {
     for k, v in var.subnets : k => v if v.ipv4 != null && v.ipv4.cidrs_by_az != null
   }
   # ─── Deterministic IPv4 CIDR calculation by selected parent ──────────
-  # Calculated groups reserve the caller-selected AZ capacity. Six remains the
-  # module default; constrained wrappers can reserve fewer fixed slots when
-  # their supported maximum is lower.
+  # Calculated groups reserve the caller-selected AZ capacity. Three is the
+  # module default (the most common regional layout); deployments in regions
+  # with more AZs can raise it, and established VPCs must keep their original
+  # value to avoid renumbering.
   cidr_az_stride = var.calculated_subnet_az_capacity
 
   ipv4_parent_key_by_group = {

locals.tf

@@ -24,9 +24,10 @@ run "unpinned_before_group_add" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24 } }
       gamma = { role = "private", ipv4 = { netmask = 24 } }
@@ -58,9 +59,10 @@ run "unpinned_after_group_add" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24 } }
       beta  = { role = "private", ipv4 = { netmask = 24 } }
@@ -89,9 +91,10 @@ run "unpinned_after_group_remove" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24 } }
       gamma = { role = "private", ipv4 = { netmask = 24 } }
@@ -118,9 +121,10 @@ run "pinned_before_group_add" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24, cidr_index = 0 } }
       gamma = { role = "private", ipv4 = { netmask = 24, cidr_index = 5 } }
@@ -147,9 +151,10 @@ run "pinned_after_group_add" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24, cidr_index = 0 } }
       beta  = { role = "private", ipv4 = { netmask = 24 } }
@@ -178,9 +183,10 @@ run "pinned_after_group_remove" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24, cidr_index = 0 } }
       gamma = { role = "private", ipv4 = { netmask = 24, cidr_index = 5 } }
@@ -207,9 +213,10 @@ run "add_availability_zone" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b", "us-east-1c"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b", "us-east-1c"] }
     subnets = {
       alpha = { role = "private", ipv4 = { netmask = 24 } }
       gamma = { role = "private", ipv4 = { netmask = 24 } }
@@ -334,9 +341,10 @@ run "mixed_netmasks_pack_without_overlap" {
   command = plan
 
   variables {
-    vpc                = { name = "cidr-test" }
-    addressing         = { primary = { cidr_block = "10.0.0.0/16" } }
-    availability_zones = { names = ["us-east-1a", "us-east-1b"] }
+    calculated_subnet_az_capacity = 6
+    vpc                           = { name = "cidr-test" }
+    addressing                    = { primary = { cidr_block = "10.0.0.0/16" } }
+    availability_zones            = { names = ["us-east-1a", "us-east-1b"] }
     subnets = {
       application = { role = "private", ipv4 = { netmask = 22 } }
       public      = { role = "public", ipv4 = { netmask = 24 } }
@@ -404,10 +412,9 @@ run "constrained_three_az_capacity_fits_three_pinned_28_groups_in_a_24" {
   command = plan
 
   variables {
-    vpc                           = { name = "inspection-24" }
-    addressing                    = { primary = { cidr_block = "10.0.0.0/24" } }
-    availability_zones            = { names = ["eu-south-2a"] }
-    calculated_subnet_az_capacity = 3
+    vpc                = { name = "inspection-24" }
+    addressing         = { primary = { cidr_block = "10.0.0.0/24" } }
+    availability_zones = { names = ["eu-south-2a"] }
     subnets = {
       core_network = { role = "private", ipv4 = { netmask = 28, cidr_index = 0 } }
       firewall     = { role = "private", ipv4 = { netmask = 28, cidr_index = 1 } }
@@ -424,3 +431,72 @@ run "constrained_three_az_capacity_fits_three_pinned_28_groups_in_a_24" {
     error_message = "A /24 must fit the three inspection /28 groups while reserving three stable AZ slots per group."
   }
 }
+
+run "constrained_three_az_capacity_allocates_every_availability_zone" {
+  command = plan
+
+  variables {
+    vpc                = { name = "inspection-24" }
+    addressing         = { primary = { cidr_block = "10.0.0.0/24" } }
+    availability_zones = { names = ["eu-south-2a", "eu-south-2b", "eu-south-2c"] }
+    subnets = {
+      core_network = { role = "private", ipv4 = { netmask = 28, cidr_index = 0 } }
+      firewall     = { role = "private", ipv4 = { netmask = 28, cidr_index = 1 } }
+      public       = { role = "public", ipv4 = { netmask = 28, cidr_index = 2 } }
+    }
+  }
+
+  assert {
+    condition = output.subnet_cidrs_by_group_by_az == {
+      core_network = {
+        eu-south-2a = "10.0.0.0/28"
+        eu-south-2b = "10.0.0.16/28"
+        eu-south-2c = "10.0.0.32/28"
+      }
+      firewall = {
+        eu-south-2a = "10.0.0.48/28"
+        eu-south-2b = "10.0.0.64/28"
+        eu-south-2c = "10.0.0.80/28"
+      }
+      public = {
+        eu-south-2a = "10.0.0.96/28"
+        eu-south-2b = "10.0.0.112/28"
+        eu-south-2c = "10.0.0.128/28"
+      }
+    }
+    error_message = "Filling the three reserved AZ slots must allocate consecutive /28 blocks per group without exceeding the /24."
+  }
+}
+
+run "constrained_capacity_scale_up_preserves_existing_az_cidrs" {
+  command = plan
+
+  variables {
+    vpc                = { name = "inspection-24" }
+    addressing         = { primary = { cidr_block = "10.0.0.0/24" } }
+    availability_zones = { names = ["eu-south-2a", "eu-south-2b"] }
+    subnets = {
+      core_network = { role = "private", ipv4 = { netmask = 28, cidr_index = 0 } }
+      firewall     = { role = "private", ipv4 = { netmask = 28, cidr_index = 1 } }
+      public       = { role = "public", ipv4 = { netmask = 28, cidr_index = 2 } }
+    }
+  }
+
+  assert {
+    condition = (
+      output.subnet_cidrs_by_group_by_az.core_network["eu-south-2a"] == "10.0.0.0/28" &&
+      output.subnet_cidrs_by_group_by_az.firewall["eu-south-2a"] == "10.0.0.48/28" &&
+      output.subnet_cidrs_by_group_by_az.public["eu-south-2a"] == "10.0.0.96/28"
+    )
+    error_message = "Growing from one AZ to two must keep the first AZ on the same /28 blocks (scale-up without renumbering)."
+  }
+
+  assert {
+    condition = (
+      output.subnet_cidrs_by_group_by_az.core_network["eu-south-2b"] == "10.0.0.16/28" &&
+      output.subnet_cidrs_by_group_by_az.firewall["eu-south-2b"] == "10.0.0.64/28" &&
+      output.subnet_cidrs_by_group_by_az.public["eu-south-2b"] == "10.0.0.112/28"
+    )
+    error_message = "The second AZ must take the next reserved slot of each group without touching neighbouring groups."
+  }
+}

tests/cidr_engine.tftest.hcl

@@ -74,8 +74,8 @@ run "generated_dual_stack_dns64_eigw" {
     condition = (
       aws_subnet.main["public/us-east-1a"].ipv6_cidr_block == "2001:db8:4200::/64" &&
       aws_subnet.main["public/us-east-1b"].ipv6_cidr_block == "2001:db8:4200:1::/64" &&
-      aws_subnet.main["app/us-east-1a"].ipv6_cidr_block == "2001:db8:4200:c::/64" &&
-      aws_subnet.main["app/us-east-1b"].ipv6_cidr_block == "2001:db8:4200:d::/64" &&
+      aws_subnet.main["app/us-east-1a"].ipv6_cidr_block == "2001:db8:4200:6::/64" &&
+      aws_subnet.main["app/us-east-1b"].ipv6_cidr_block == "2001:db8:4200:7::/64" &&
       alltrue([for subnet in values(aws_subnet.main) : subnet.assign_ipv6_address_on_creation])
     )
     error_message = "auto_assign must plan deterministic, pinned /64s and enable address assignment."

tests/ipv6.tftest.hcl

@@ -489,7 +489,7 @@ run "reject_calculated_cidr_pin_beyond_parent_capacity" {
     addressing         = { primary = { cidr_block = "10.120.0.0/24" } }
     availability_zones = { names = ["us-east-1a"] }
     subnets = {
-      app = { role = "private", ipv4 = { netmask = 28, cidr_index = 3 } }
+      app = { role = "private", ipv4 = { netmask = 28, cidr_index = 6 } }
     }
   }
 

tests/validations.tftest.hcl

@@ -328,13 +328,15 @@ variable "availability_zones" {
 
 variable "calculated_subnet_az_capacity" {
   description = <<-EOT
-    Number of AZ slots reserved per calculated subnet group. The default six
-    preserves the v5 stability contract. A constrained wrapper may choose a
-    lower fixed capacity when it explicitly supports fewer AZs; the value must
-    still cover every configured AZ.
+    Number of AZ slots reserved per calculated subnet group. The default of
+    three matches the most common regional layout (three AZs). Deployments in
+    regions with more AZs may raise it up to six; the value must always cover
+    every configured AZ. Changing it on an existing VPC renumbers calculated
+    subnets, so established deployments must keep the value they were created
+    with.
   EOT
   type        = number
-  default     = 6
+  default     = 3
 
   validation {
     condition = (
@@ -417,7 +419,8 @@ variable "transit_gateway_attachments" {
 #
 # NETMASK STABILITY:
 #   When using `ipv4.netmask`, CIDRs are calculated deterministically:
-#   - Every group reserves six AZ slots, so appending AZs does not move CIDRs
+#   - Every group reserves `calculated_subnet_az_capacity` AZ slots (default 3,
+#     raisable to 6), so appending AZs within that capacity does not move CIDRs
 #   - Pinned groups use absolute `cidr_index` slots and never move
 #   - Unpinned groups pack largest-first, then alphabetically; adding/removing a
 #     group affects unpinned groups that sort after it
@@ -489,8 +492,9 @@ variable "subnets" {
       cidrs_by_az    = optional(map(string))
       ipam_pool_id   = optional(string)
       netmask_length = optional(number)
-      # Absolute CIDR group slot for pinning. Each slot reserves six
-      # AZ-sized CIDRs at this netmask. Pinned ranges never move when groups or AZs
+      # Absolute CIDR group slot for pinning. Each slot reserves
+      # `calculated_subnet_az_capacity` AZ-sized CIDRs (default 3) at this netmask.
+      # Pinned ranges never move when groups or AZs
       # are added/removed; overlapping pins across netmasks are rejected.
       cidr_index         = optional(number)
       secondary_cidr_key = optional(string)