This solution provides code to implement a shared, multi-account, multi-region, hierarchical Amazon VPC IP Address Manager (IPAM) specification using Terraform. Alongside the included companion Streamlit web application (Python), AWS cloud architects, engineers, and/or developers can vastly accelerate VPC/network planning, IP address space visualization, and the eventual Terraform deployment of their Amazon VPC IPAM specification. The specification is shared with AWS Organizations using AWS Resource Access Manager (RAM), and guidance for potential use in other Terraform modules — e.g., with Account Factory for Terraform (AFT) — is provided within this repository's README.
- Executive Summary
- Architecture Overview
- Technical Design
- Implementation Guide
- Module Structure
- Deployed Resources
- Technical Features
- Integration Patterns
- Advanced Usage
- Outputs Reference
- Security
- License
This Terraform implementation provides a robust foundation for enterprise-grade IP address management across your AWS cloud infrastructure. By deploying a hierarchical, multi-region IPAM architecture integrated with AWS Resource Access Manager (RAM), it enables organizations to:
- Automate IP address allocation across regions, business units, and environments
- Enforce organizational network policies through programmatic validation
- Scale network infrastructure efficiently as business requirements evolve
- Reduce operational overhead through centralized management of IP address spaces
- Accelerate cloud-native workload deployments with self-service CIDR allocation
- Prevent address conflicts through policy-based controls and validation
This solution is designed for engineering teams who need to manage complex AWS environments with multiple accounts, regions, and business domains while maintaining consistent network governance.
Diagram: IPAM Deployment Topology & Example Usage
- Developer is deploying a new VPC and requests a
/23CIDR block from IPAM in RegionA, for Business UnitY, in Environment3. - The IPAM specification contains a pool for Region
A, defined with the CIDR block of10.176.0.0/15. - Within the Region
Apool, the specification contains a nested pool for Business UnitY("PoolAY"), defined as10.177.0.0/16. - Within "Pool
AY", the specification contains another nested pool for Environment3("PoolAY3"), defined as10.177.128.0/18. - Within the developer's target pool ("Pool
AY3"), IPAM has two existing CIDR allocations —10.177.128.0/23and10.177.130.0/22. The next-available/23CIDR block is automatically calculated. - The next-available
/23CIDR block is calculated as10.177.134.0/23, is provided for the developer's resource, and is automatically compliant with the IPAM specification (for "PoolAY3").
IP Address Management (IPAM) is how organizations plan, track, and manage IP address spaces. It’s essential for keeping networks organized, avoiding conflicts, and enforcing policies—especially as environments grow more complex.
Common IPAM benefits
- Centralized visibility into address usage
- Automated assignment to prevent conflicts
- Hierarchical organization for governance
- Policy enforcement for compliance
- Integration with DNS and DHCP
Amazon VPC IPAM is a managed feature (of Amazon VPC) that simplifies planning, tracking, allocating, and monitoring IP addresses for your AWS workloads. It replaces spreadsheets with automation and visibility, and is built for scale.
Amazon VPC IPAM benefits checklist
- Centralized management across accounts and regions
- Automated CIDR allocation for VPCs and subnets
- Hierarchical pools for organizational alignment
- Integration with AWS Organizations and RAM
- Near-real-time monitoring and audit trails
This solution uses several AWS constructs to organize and govern IP space:
| Concept | Purpose |
|---|---|
| IPAM Service | Central control, deployed in the primary region |
| IPAM Scopes | Separate public and private address management |
| IPAM Pools | Hierarchical CIDR collections for allocation |
| Pool Sharing | Cross-account access via AWS RAM |
| Resource Discovery | Finds existing resources automatically |
| Compliance Checking | Validates CIDR assignments against policies |
Diagram: IPAM Logical Constructs
By default, this solution is developed to employ a four-tier, nested pool hierarchy:
- Top-Level (Global) Pool: Entire organizational IP space
- Regional Pools: Allocations per AWS region, within the top-level pool
- Business Unit Pools: Allocations per business unit/domain (marketing, finance), within each regional pool
- Environment Pools: Allocations per "SDLC" environment (dev, qa, prod), within each business unit pool
Example: Hierarchical Structure
Top-Level Pool (10.0.0.0/8)
├── Regional Pool - us-east-1 (10.0.0.0/12)
│ ├── Business Unit - Finance (10.0.0.0/14)
│ │ ├── Environment - Dev (10.0.0.0/16)
│ │ ├── Environment - QA (10.0.2.0/16)
│ │ ├── Environment - Core (10.0.4.0/16)
│ │ └── Environment - Prod (10.0.6.0/16)
│ └── Business Unit - Marketing (10.0.8.0/14)
│ ├── Environment - Dev (10.0.8.0/16)
│ └── ... (additional environments)
└── Regional Pool - eu-west-1 (10.16.0.0/12)
└── ... (additional business units and environments)
Why this matters
- Every CIDR sits neatly inside its parent pool.
- No overlaps — each team gets its own space.
- Delegation is simple, but oversight stays centralized.
- Subnetting is straightforward and efficient.
This solution deploys the IPAM service centrally in a primary region, while enabling management of additional AWS regions as operating regions. Each region receives a dedicated IPAM pool and is configured with locale-specific settings, which ensures efficient and centralized IP resource management across your AWS environment.
Table: Deployment Aspects
| Aspect | Description |
|---|---|
| Primary Region Deployment | IPAM service is deployed in a single primary region. |
| Operating Regions | Additional regions registered for IPAM resource management. |
| Regional Pool Assignment | Each operating region receives a dedicated address pool from the top-level. |
| Cross-Region Management | All operating regions are centrally managed. |
| Regional Locale Settings | Each regional pool has a "locale" property tied to its region. |
This solution enables robust IP address compliance mechanisms by means of:
- Auto-Import: When IPAM pools are created, it’s recommended to allow IPAM to automatically import pre-existing resources (into respective pools)
- Compliance Checking: New and imported resources are monitored by IPAM for compliance with pool allocation rules and potential IP address overlap
- Nested Compliance: Resources may be non-compliant with direct pools but compliant with higher-level pools
- Remediation Options: Non-compliant resources can be excluded, reassigned, or have pools adjusted
As shown in the deployment topology diagram, VPC AY3-3 demonstrates a non-compliance scenario where the resource's CIDR doesn't fit within the range of its intended pool.
For more information on CIDR compliance monitoring in Amazon VPC IPAM, please review the documentation.
Before deploying this IPAM solution, ensure your environment meets these requirements:
-
AWS Organizations:
- Your AWS environment must use AWS Organizations
- The IPAM account must be a member of your organization
- Resource sharing must be enabled at the organization level
-
AWS Resource Access Manager (RAM):
- Resource sharing must be enabled in your AWS Organization
- For details: AWS RAM Documentation
-
IAM Permissions:
- The deploying identity requires permissions for:
- IPAM management
- RAM resource sharing
- Organization access
- VPC management
- For details: AWS IPAM IAM Documentation
- The deploying identity requires permissions for:
-
Service Quotas:
- Verify sufficient IPAM pool quota (default: 50)
- This deployment with 6 regions, 2 business units, and 4 environments will create 67 pools
- For details: AWS IPAM Quotas
-
Network Design:
- Prepare a comprehensive IP allocation plan
- Confirm non-overlapping CIDR ranges for all regions, business units, and environments
- For planning guidance: AWS IPAM Planning
Expand details
Key configuration parameters for this solution include:
- Top-Level CIDR: The overall address space for your organization (e.g.,
10.0.0.0/8) - Operating Regions: AWS regions where IPAM will manage resources
- Regional IPAM Configurations: Per-region settings including:
- Regional names and descriptions
- Regional CIDR allocations
- AWS region locale
- Business Unit Configurations: Per-BU settings including:
- Business unit names and descriptions
- BU-level CIDR allocations
- Environment Configurations: Per-environment settings including:
- Environment names and descriptions
- Environment-level CIDR allocations
- Reserved CIDR blocks (see RESERVED-CIDRS.md for details)
Expand details
The deployment process follows this general workflow:
- Module Instantiation: Include the IPAM module in your Terraform code
- Parameter Configuration: Set required variables for your organization
- Validation: Terraform validates CIDR relationships during plan phase
- IPAM Deployment: Creates the IPAM service in the primary region
- Pool Creation: Builds the hierarchical pool structure
- Resource Sharing: Configures RAM sharing for cross-account access
- Outputs: Produces references for downstream consumption
To accelerate and simplify planning and deployment processes, I have developed a companion, Streamlit-based "IPAM Configurator" tool (located in the ipam-figurator directory) that helps generate the necessary terraform.tfvars file based on your organizational requirements.
This companion tool will prove essential once you have your Amazon VPC network hierarchy planned — e.g., Top-Level CIDR, Operating Regions, Business Units, "SDLC" Environments. Here's a high-level overview of what the tool provides:
- Interactive UI: The configurator provides a web-based interface for defining your IPAM hierarchy
- Automated CIDR Planning: The tool calculates appropriate CIDR allocations based on your inputs
- Visual Validation: Preview the IPAM structure before generating the configuration
- Configuration Download: Export (or copy-paste) a ready-to-use
terraform.tfvarsfile
To use the IPAM Configurator, clone the repo, change directories, then execute the run.sh script:
cd ipam-figurator
./run.shThis will launch a local Streamlit application that will guide you through the configuration process. Once complete, you can download the generated terraform.tfvars file (or copy its contents) and use it with this Terraform module.
Once you have your '.tfvars' configuration, simply execute the stop.sh script to "tear-down":
./stop.shFor more detailed information about the IPAM Configurator, see the README.
The repository is organized with the following structure:
- Terraform Directory: Contains all Terraform code for the implementation
- Root Module: Orchestrates the deployment and provides input variables
- IPAM Module: Core implementation of the IPAM architecture
- Tags Module: Standardized tagging for all resources
- IPAM Configurator: Web-based tool for generating terraform.tfvars
Key files include:
terraform/main.tf: Primary module orchestrationterraform/variables.tf: Input variables for configurationterraform/outputs.tf: Output values for downstream consumptionterraform/data.tf: Data sources for AWS resourcesterraform/tags.tf: Tagging configurationterraform/modules/ipam/main.tf: IPAM resource definitionsterraform/modules/ipam/locals.tf: Validation logic and transformationsterraform/modules/tags/main.tf: Tag standardization logicipam-figurator/: IPAM configuration generation tool
This solution deploys the following AWS resources:
-
Core IPAM Resources:
- Amazon VPC IPAM instance in the primary region
- IPAM scope for private IP management
- Four-tier hierarchy of IPAM pools:
- Top-level pool for global address space
- Regional pools for each operating region
- Business unit pools within each region
- Environment pools within each business unit
-
Resource Sharing:
- AWS RAM resource shares for all IPAM pools
- RAM principal associations with your AWS Organization
- RAM resource associations for all pools
Expand details
This solution deploys a single IPAM instance in your primary AWS region that:
- Provides a unified control plane for IP management
- Supports registration of multiple operating regions
- Centralizes logging and audit trails
- Offers consistent policy enforcement
- Maintains a single source of truth for IP allocation
Expand details
The hierarchical pool structure enables:
- Top-down address space planning: Start with the largest scope and segment progressively
- Delegation of control: Business units can manage their allocations independently
- Isolation of concerns: Each pool has a dedicated purpose and owner
- Efficient utilization: CIDR blocks are allocated at appropriate sizes for their use
Expand details
AWS RAM integration provides:
- Cross-account access to IPAM pools
- Organizational-level permission management
- Self-service CIDR allocation for application teams
- Centralized policy enforcement with distributed execution
Expand details
Built-in validation logic ensures:
- Environment CIDRs are contained within their parent business unit CIDRs
- Business unit CIDRs are contained within their parent regional CIDRs
- Regional CIDRs are contained within the top-level CIDR
- No overlapping CIDRs within the same hierarchy level
- Proper mapping of environments to their respective business units
This solution includes an additional, reusable submodule to facilitate standardized tagging for all AWS resources.
This solution integrates with AWS Organizations natively. By design, all IPAM pools are shared across all organization accounts using AWS RAM — from a dedicated Network account, for example, to which this solution's Terraform manifests were applied. Consequently, all accounts in the Organization will have the ability to apply consistent IP addressing standards.
For AWS Account Factory for Terraform (AFT) users, this solution might be used as an Account Customization in your Network account (or similar).
This will help ensure:
- You create and maintain a firm, centralized foundation for consistent network addressing for your accounts and workloads.
- You are providing stable references for network resources provisioned using other AFT customizations/manifests (e.g., a VPC module).
This solution lets you plug IPAM-managed pools directly into your VPC provisioning workflow. Terraform modules for VPC resource provisioning can reference pools programmatically, enabling automatic CIDR allocation with consistent, centralized address management.
Code: Example VPC module integration
# Data source to find the intended IPAM pool
data "aws_vpc_ipam_pool" "dev_pool" {
filter {
name = "tag:Name"
values = ["dev-environment-pool"]
}
}
# Calling the VPC module
module "application_vpc" {
source = "./modules/vpc"
# Reference the intended IPAM pool
ipam_pool_id = data.aws_vpc_ipam_pool.dev_pool.id
ipv4_netmask_length = 24 # Requests a /24 from the pool
# Additional VPC configuration...
name = "dev-test-app-vpc"
#...
}How this helps
- VPCs get non-overlapping CIDRs, automatically assigned from the right pool
- Address assignments are consistent and centrally tracked
- No more manual subnet math or spreadsheet management
For custom or edge-case scenarios, you can define configuration values directly within the module block -- i.e., via direct (inlined, explicit) values. The IPAM Configurator tool can generate the baseline configuration, which you can further tailor as needed.
Code: Example custom, partially-inlined configuration
####### variables.tf #######
variable "additional_reg_ipam_configs" {
description = "Additional regional IPAM configs"
type = map(object({
name = string
description = string
cidr = list(string)
locale = string
}))
default = {}
}
# ...etc.
####### terraform.tfvars #######
additional_reg_ipam_configs = {
"us-west-2" = {
name = "ipam-regional-us-west-2"
description = "Regional IPAM Pool for US West (Oregon)"
cidr = ["10.64.0.0/12"]
locale = "us-west-2"
}
# ...other regions
}
# ...etc.
####### main.tf #######
module "ipam" {
source = "./modules/ipam"
# Inlined (explicit) values for custom requirements
operating_regions = [
"us-east-1",
"us-west-2",
"eu-west-1",
"ap-northeast-1"
]
top_name = "enterprise-ipam-global"
top_description = "Enterprise-wide Global IPAM Pool"
# Partially-inlined: 'us-east-1' is inlined, others via 'merge()' with the new 'var.additional_reg_ipam_configs'
reg_ipam_configs = merge(
{
us-east-1 = {
name = "ipam-regional-us-east-1"
description = "Regional IPAM Pool for US East (N. Virginia)"
cidr = ["10.0.0.0/10"]
locale = "us-east-1"
}
},
var.additional_reg_ipam_configs
)
# Inhereted defaults or shared values from existing variables
top_cidr = var.top_cidr
bu_ipam_configs = var.bu_ipam_configs
env_ipam_configs = var.env_ipam_configs
organization_arn = data.aws_organizations_organization.current.arn
share_name = var.share_name
tags = module.tags.tag_map
}See the example tfvars file for additional insights into fully specified arguments.
Tip
Terraform does not support "spreading" maps — e.g., like JavaScript's { ...var }. So, as illustrated in my "partially-inlined" example (for reg_ipam_configs) above, I needed to declare a new variable (additional_reg_ipam_configs) in the variables.tf file, assign a value to the variable (or values, since additional_reg_ipam_configs is a map) in the terraform.tfvars file, and use merge() to combine the inlined and variable-driven maps.
This solution provides comprehensive outputs by default — e.g., for downstream consumption:
-
IPAM Pool IDs:
- Top-level pool ID
- Regional pool IDs
- Business unit pool IDs
- Environment pool IDs
-
CIDR Allocations:
- Business unit CIDR blocks
- Environment CIDR blocks
-
RAM Resources:
- Resource share ARNs
- Principal associations
- Resource associations
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.