Overview

Purpose

This walkthrough documents how to deploy and operate the tfstack/terraform-aws-ipam example — a TerraformTerraform
HashiCorp Terraform — four account stacks in examples/multi-account/ plus shared modules/ipam-vpc/. demo for four-account IPAMIPAM
Amazon VPC IP Address Manager — hosts the pool hierarchy in the network account; workloads allocate VPC CIDRs from RAM-shared leaf pools. with ANZ regional pools, RAM sharingRAM sharing
AWS Resource Access Manager permission for a workload account to use an IPAM pool — does not create a formal allocation by itself., and pool-backed workload VPCs.

A dedicated network accountnetwork account
Delegated IPAM admin account — owns IPAM home region, pool tree, and RAM resource shares. hosts org-wide IPAM in ap-southeast-6. Dev and sandbox workload accounts allocate /20 VPC CIDRs from RAM-shared leaf pools in matching regions.

The pattern uses ipv4_ipam_pool_id via modules/ipam-vpc/. It does not use Transit Gateway, VPC peering, NAT gateway, or management-account IPAM hosting.

Architecture at a glance

Four AWS accounts: managementmanagement
AWS Organizations management account — runs org-bootstrap for delegation and RAM org sharing only; cannot host IPAM. delegates admin and enables RAM org sharing; networknetwork
Delegated IPAM admin account — owns IPAM home region, pool tree, and RAM resource shares. owns the pool tree; dev and sandbox create pool-backed VPCs after RAM shareRAM share
AWS Resource Access Manager permission for a workload account to use an IPAM pool — does not create a formal allocation by itself. and the stack contractstack contract
Manual copy of nz_dev_pool_id and au_sandbox_pool_id into workload terraform.tfvars as pool_id — no terraform_remote_state..

Accounts, regions, and stacks

Stack	Account	Profile	Region
org-bootstrap/	Management	ipam-org	Global
ipam/	Network	ipam-network	ap-southeast-6
workload-a/	Dev	ipam-workload-a	ap-southeast-6
workload-b/	Sandbox	ipam-workload-b	ap-southeast-2

Leaf pools and expected VPC CIDRs:

Pool path	Locale	Workload VPC
org/nz/dev	ap-southeast-6	10.64.0.0/20
org/au/sandbox	ap-southeast-2	10.128.0.0/20

Phased dependency model

Step	Depends on	Why
ipam/	org-bootstrap/	Needs delegated admin and RAM org sharing
workload-a/ / workload-b/	ipam/	Needs pool_id from nz_dev_pool_id / au_sandbox_pool_id outputs

Workloads may run in parallel after ipam/ completes.

Walkthrough path

1. Planning vs Monitoring — two-plane IPAM console model
2. Tools and Accounts — four accounts, profiles, upstream clone
3. Pre-flight — SSO and identity checks before every apply
4. Org Bootstrap — delegation + RAM org sharing
5. IPAM Deploy — pools and RAM shares
6. Workload Deploy — pool-backed VPCs
7. Post-Deploy Checks — Allocations and Managed VPCs
8. Common Issues — operator mistakes (wrong profile, stack contract)
9. Teardown — dependency-safe cleanup

For conceptual depth before apply, read Account Topology and Pool Hierarchy.

Success criteria

Deployment succeeds when all of the following are true:

• Leaf pools org/nz/dev and org/au/sandbox exist with expected CIDRs and locales
• RAM shares org-nz-dev and org-au-sandbox are Active
• Workload VPCs are Managed via ipv4_ipam_pool_id
• Planning → Pools → Allocations shows /20 blocks owned by workload accounts
• Monitoring → Resources lists the pool-backed VPCs as Managed (filter by account and CIDR)

Intentionally excluded

The upstream example deliberately omits:

• Transit Gateway, VPC peering, VPN, or Direct Connect
• NAT gateway (disabled for cost)
• Public IPAM scope usage