IPAM
Amazon VPC IP Address Manager (IPAM) is the AWS service that records which address ranges belong to which part of an organization, so that no two networks overlap. The platform runs exactly one IPAM and uses it to publish the entire address plan from a single file.
What it does
IPAM organizes address space as a tree of pools. A top-level pool holds the organization's supernet; child pools carve it by region, then by business unit, then by account. Each pool has a locale, the region its addresses may be used in. Pools can be shared with other accounts through Resource Access Manager. IPAM tracks allocations (which CIDR is in use where), detects overlaps, and can hand out the next free range on request. It is one organization-wide resource: all its pools are created through its home region.
How BuiltForProd uses it
The ipam unit (module modules/ipam, listed by the core/network/global stack file) is the only place in the AWS Baseline where addresses enter the configuration. It reads one YAML file at the repository root, eks_vpc_map.yaml, builds the pool hierarchy from it, and republishes every value as outputs that the VPC, Transit Gateway routing, Network Firewall and Client VPN units consume through dependency blocks.
The map is the single source of truth. It holds, per region, the region slug, the OU pools, and for every account VPC its primary CIDR and its private, public and firewall subnet CIDRs, plus a client_vpn_cidr per region (172.16.0.0/21, deliberately outside the supernet). The OU pools are shared organization-wide through RAM. VPC CIDRs are assigned statically from the map rather than allocated dynamically from the pools, so the plan is reviewable in one diff.
Regions are discovered, not listed. The unit reads every region.hcl in the environments tree, skipping global/ folders, and builds pools only for regions that have folders; operating_regions covers every region in the map so adding a folder never changes the IPAM resource itself. A validation fails the plan on a region folder the map does not describe, a slug mismatch, or a VPN CIDR for a region with no folders.
Two guardrails keep addresses out of code: a pre-commit and CI check rejects any private CIDR literal in .hcl or .tf files outside comments and mocks, and a second check validates both maps for nesting, overlap and that every unit's ipam_key resolves to an entry. A compact alternative map, non_eks_vpc_map.yaml (10.0.0.0/11), is structurally interchangeable; switching between them is only safe before the first apply, because every CIDR differs.
Capacity is reserved up front: 16 regions in the /8, 8 stages per region, and a free /14 per region for a future OU.
Terms you will see
| Term | Meaning |
|---|---|
| Pool | A range of addresses in the IPAM tree, with a locale. |
| Supernet | The top-level range everything else is carved from; 10.0.0.0/8 here. |
| Locale | The region a pool's addresses may be used in. |
| VPC map | The YAML file at the repository root that defines every CIDR. |
ipam_key | The <ou>-<account> key a VPC unit uses to find its entry, such as plat-prod. |
| Region slug | The short name of a region used in resource names, such as usw2. |
| Allocation | A CIDR recorded as in use within a pool. |
Where to read more
- AWS Baseline overview for the CIDR table derived from the map.
- VPC for the networks built from these ranges.
- Client VPN for how the same outputs generate VPN routes.