Hierarchical, Multi-Region AWS VPC IPAM with Terraform

## The Challenge: IP Management Across Accounts and Regions

Plenty of organizations track their AWS IP space in a spreadsheet, and it works right up until two teams in two accounts pick overlapping CIDRs. AWS is blunt about what happens next: a peering request between VPCs with overlapping ranges comes back with a status of failed, full stop. There's no route table entry that fixes it — one side has to be renumbered, and by then both VPCs are usually carrying production traffic.

I've seen enterprises struggle with this repeatedly, and it's worst when scaling into new Regions or partway through a migration. The reason is arithmetic rather than carelessness: every account, Region, environment, and business unit multiplies the number of ranges somebody has to keep straight, and a manual record falls behind the infrastructure it's supposed to describe.

This one started on an engagement, not as a weekend project. The AWS footprint had grown for about a decade without a central plan behind it — six Regions across three geographies, hundreds of network resources, and no single place that authoritatively said which ranges were already spoken for. So I built an Amazon VPC IP Address Manager (IPAM) solution to move all of it into Terraform: the hierarchy, the allocation rules, and the cross-account sharing, defined in code and reviewable before anything gets created.

The part I didn't expect was how little prior art there was. I went looking for an existing pattern to adapt and came up empty — nothing published covered a hierarchical, multi-Region IPAM layout at this shape. Building it from scratch is the reason it ended up as a published AWS Prescriptive Guidance pattern instead of staying in a private repo.

## Solution Architecture: Four-Tier Hierarchical Design

The pool structure is four tiers deep, shaped to match how organizations actually divide their networks. The diagram traces it from the Configurator through to deployment:

Complete AWS VPC IPAM Architecture and Data Flow

Top-Level Pool (Global CIDR: 10.0.0.0/8)
├── Regional Pools (per AWS region: 10.0.0.0/12, 10.16.0.0/12, …)
│   ├── Business Unit Pools (per BU: 10.0.0.0/14, 10.4.0.0/14, …)
│   │   └── Environment Pools (dev/qa/prod: 10.0.0.0/16, 10.1.0.0/16, …)

Why bother with four tiers instead of a flat list of pools:

• ▶Organizational Alignment: Matches business unit and environment structure
• ▶Scalable Governance: Policies applied at appropriate hierarchy levels
• ▶Conflict Prevention: Automatic CIDR containment validation
• ▶Multi-Region Consistency: Centralized control with regional allocation

## The Innovation: IPAM Configurator Tool

The centerpiece is the "IPAM Configurator" — a Streamlit web app for laying out the pool hierarchy before any of it becomes Terraform.

Donny's IPAM Configurator: Demo

Planning a hierarchy like this by hand means subnet math in a spreadsheet, and the mistakes don't surface until Terraform rejects them. The Configurator does the math and shows you the tree while you're still deciding.

The tool is built using modern Python technologies including Streamlit for the web interface, Pandas for data manipulation, Plotly for visualization, and NetworkX for graph operations. The core logic handles complex CIDR validation and hierarchical allocation calculations that would typically require manual verification.

## Technical Implementation Deep Dive

The Terraform is split into modules, with validation logic kept separate so the hierarchy rules are readable on their own:

The hardest part was the validation logic. The solution checks CIDR well-formedness, verifies containment at every level of the hierarchy, and detects conflicts before anything is created.

The simplest, most portable guardrail validates a single variable — it works on every Terraform version because the condition only references the variable it's attached to:

variable "top_level_cidr" {
  type        = string
  description = "Global CIDR for the top-level IPAM pool (e.g. 10.0.0.0/8)."

  validation {
    # Must be a syntactically valid IPv4 CIDR...
    condition     = can(cidrhost(var.top_level_cidr, 0))
    error_message = "top_level_cidr must be a valid IPv4 CIDR, e.g. 10.0.0.0/8."
  }

  validation {
    # ...and broad enough to carve regional/BU/env pools beneath it.
    condition     = tonumber(split("/", var.top_level_cidr)[1]) <= 12
    error_message = "top_level_cidr prefix must be /12 or larger (smaller number) to leave room for the hierarchy."
  }
}

Validating that one pool actually fits inside another means comparing two variables in a single condition. That cross-variable reference requires Terraform 1.9+ (earlier versions reject a validation block that references anything but its own variable). Note the explicit tonumber() — split() returns strings:

# Terraform >= 1.9: a validation rule may reference other variables.
variable "regional_prefix_length" {
  type        = number
  description = "Prefix length for each regional pool (e.g. 12 for a /12)."

  validation {
    condition = (
      var.regional_prefix_length > tonumber(split("/", var.top_level_cidr)[1])
      && var.regional_prefix_length <= 28
    )
    error_message = "Regional prefix must be longer (more specific) than the top-level CIDR and no longer than /28."
  }
}

git clone https://github.com/aws-samples/sample-amazon-vpc-ipam-terraform

## Enterprise Integration Patterns

A few integration points matter if you're dropping this into an existing AWS setup:

AWS Organizations Integration

AWS Resource Access Manager (RAM) shares the IPAM pools across accounts in the organization. This enables centralized governance while allowing distributed teams to provision VPCs using organization-managed IP space.

Account Factory for Terraform (AFT) Compatibility

For organizations using AFT, this IPAM solution can be deployed as a global customization, providing immediate IP management capabilities for newly provisioned accounts.

Downstream VPC Provisioning

VPC modules can directly reference IPAM pools using data sources, eliminating manual CIDR specification and ensuring automatic compliance with organizational IP allocation policies.

# VPC integration example
resource "aws_vpc" "main" {
  ipv4_ipam_pool_id   = data.aws_vpc_ipam_pool.environment.id
  ipv4_netmask_length = 18
  
  tags = {
    Name = "production-vpc"
    Environment = "prod"
  }
}

## Operational Excellence & Governance

Beyond the technical implementation, this solution addresses critical operational requirements for enterprise environments:

## Real-World Impact & Lessons Learned

Building this IPAM solution taught me several important lessons about enterprise infrastructure automation: