Vpc Ipam Diagnostics

VPC IPAM Diagnostics

When to use

Any VPC IPAM investigation — IPAM creation, scope configuration, pool management, CIDR provisioning, allocation failures, overlap detection, organization integration, cross-region configuration, BYOIP, public IP insights, or compliance monitoring.

Investigation workflow

Step 1 — Collect and triage

aws ec2 describe-ipams --query 'Ipams[*].{IpamId:IpamId,State:State,ScopeCount:ScopeCount,OperatingRegions:OperatingRegions}'
aws ec2 describe-ipam-scopes --query 'IpamScopes[*].{ScopeId:IpamScopeId,Type:IpamScopeType,PoolCount:PoolCount}'
aws ec2 describe-ipam-pools --query 'IpamPools[*].{PoolId:IpamPoolId,State:State,AddressFamily:AddressFamily,Locale:Locale}'

Step 2 — Domain deep dive

aws ec2 get-ipam-pool-cidrs --ipam-pool-id <pool-id> --query 'IpamPoolCidrs[*].{Cidr:Cidr,State:State}'
aws ec2 get-ipam-pool-allocations --ipam-pool-id <pool-id> --query 'IpamPoolAllocations[*].{Cidr:Cidr,ResourceId:ResourceId,ResourceType:ResourceType}'
aws ec2 get-ipam-resource-cidrs --ipam-scope-id <scope-id> --query 'IpamResourceCidrs[*].{ResourceId:ResourceId,ResourceCidr:ResourceCidr,ComplianceStatus:ComplianceStatus}'

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ec2.amazonaws.com --max-results 20
aws ec2 get-ipam-discovered-resource-cidrs --ipam-resource-discovery-id <discovery-id> --resource-region <region>
aws ec2 describe-ipam-resource-discoveries --query 'IpamResourceDiscoveries[*].{DiscoveryId:IpamResourceDiscoveryId,State:State,IsDefault:IsDefault}'

Read references/guardrails.md before concluding on any VPC IPAM issue.

Tool quick reference

Gotchas: VPC IPAM

• IPAM operates at the organization level. A single IPAM can manage IP addresses across all accounts and regions in an AWS Organization.
• IPAM has two default scopes: public and private. Custom scopes can be created for additional isolation. Pools belong to scopes.
• Pool locale determines which region can allocate from the pool. A pool with locale us-east-1 cannot allocate CIDRs for VPCs in eu-west-1.
• CIDR provisioning to pools is asynchronous. After provisioning, the CIDR state transitions from pending-provision to provisioned. Do not allocate until provisioned.
• Allocation failures often indicate the pool has insufficient free space. Check pool utilization before diagnosing complex issues.
• IPAM resource discovery is required for cross-account visibility. Without it, IPAM cannot see resources in member accounts.
• BYOIP (Bring Your Own IP) requires address range verification with Regional Internet Registries before provisioning to IPAM.

Anti-hallucination rules

1. Always cite specific IPAM IDs, pool IDs, CIDR ranges, or API responses as evidence.
2. Pool locale restricts allocation to a specific region. Never suggest allocating from a pool with the wrong locale.
3. CIDR provisioning is asynchronous. Never assume a CIDR is available immediately after provisioning.
4. IPAM resource discovery is required for cross-account visibility. Never assume IPAM sees all accounts automatically.
5. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

12 runbooks