Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Getting started with IPAM using the Amazon CLI

This tutorial guides you through the process of setting up and using Amazon VPC IP Address Manager (IPAM) with the Amazon CLI using a single Amazon account. By the end of this tutorial, you will have created an IPAM, created a hierarchy of IP address pools, and allocated a CIDR to a VPC.

Prerequisites

Before you begin this tutorial, make sure you have:

Create an IPAM

The first step is to create an IPAM with operating regions. An IPAM helps you plan, track, and monitor IP addresses for your Amazon workloads.

Create an IPAM with operating regions in us-east-1 and us-west-2:

aws ec2 create-ipam \
  --description "My IPAM" \
  --operating-regions RegionName=us-east-1 RegionName=us-west-2

This command creates an IPAM and enables it to manage IP addresses in the specified regions. The operating regions are the Amazon Regions where the IPAM is allowed to manage IP address CIDRs.

Verify that your IPAM was created:

aws ec2 describe-ipams

Take note of the IPAM ID from the output, as you'll need it for subsequent steps.

Wait for the IPAM to be fully created and available (approximately 20 seconds):

sleep 20

Get the IPAM scope ID

When you create an IPAM, Amazon automatically creates a private and a public scope. For this tutorial, we'll use the private scope.

Retrieve the IPAM details and extract the private scope ID:

aws ec2 describe-ipams --ipam-id ipam-0abcd1234

Replace ipam-0abcd1234 with your actual IPAM ID.

From the output, identify and note the private scope ID from the PrivateDefaultScopeId field. It will look something like ipam-scope-0abcd1234.

Create a top-level IPv4 pool

Now, let's create a top-level pool in the private scope. This pool will serve as the parent for all other pools in our hierarchy.

Create a top-level IPv4 pool:

aws ec2 create-ipam-pool \
  --ipam-scope-id ipam-scope-0abcd1234 \
  --address-family ipv4 \
  --description "Top-level pool"

Replace ipam-scope-0abcd1234 with your actual private scope ID.

Wait for the pool to be fully created and available:

aws ec2 describe-ipam-pools --ipam-pool-ids ipam-pool-0abcd1234 --query 'IpamPools[0].State' --output text

Replace ipam-pool-0abcd1234 with your actual top-level pool ID. The state should be create-complete before proceeding.

After the pool is available, provision a CIDR block to it:

aws ec2 provision-ipam-pool-cidr \
  --ipam-pool-id ipam-pool-0abcd1234 \
  --cidr 10.0.0.0/8

Wait for the CIDR to be fully provisioned:

aws ec2 get-ipam-pool-cidrs --ipam-pool-id ipam-pool-0abcd1234 --query "IpamPoolCidrs[?Cidr=='10.0.0.0/8'].State" --output text

The state should be provisioned before proceeding.

Create a regional IPv4 pool

Next, create a regional pool within the top-level pool. This pool will be specific to a particular Amazon Region.

Create a regional IPv4 pool:

aws ec2 create-ipam-pool \
  --ipam-scope-id ipam-scope-0abcd1234 \
  --source-ipam-pool-id ipam-pool-0abcd1234 \
  --locale us-east-1 \
  --address-family ipv4 \
  --description "Regional pool in us-east-1"

Replace ipam-scope-0abcd1234 with your actual private scope ID and ipam-pool-0abcd1234 with your top-level pool ID.

Wait for the regional pool to be fully created and available:

aws ec2 describe-ipam-pools --ipam-pool-ids ipam-pool-1abcd1234 --query 'IpamPools[0].State' --output text

Replace ipam-pool-1abcd1234 with your actual regional pool ID. The state should be create-complete before proceeding.

After the pool is available, provision a CIDR block to it:

aws ec2 provision-ipam-pool-cidr \
  --ipam-pool-id ipam-pool-1abcd1234 \
  --cidr 10.0.0.0/16

Wait for the CIDR to be fully provisioned:

aws ec2 get-ipam-pool-cidrs --ipam-pool-id ipam-pool-1abcd1234 --query "IpamPoolCidrs[?Cidr=='10.0.0.0/16'].State" --output text

The state should be provisioned before proceeding.

Create a development IPv4 pool

Now, create a development pool within the regional pool. This pool will be used for development environments.

Create a development IPv4 pool:

aws ec2 create-ipam-pool \
  --ipam-scope-id ipam-scope-0abcd1234 \
  --source-ipam-pool-id ipam-pool-1abcd1234 \
  --locale us-east-1 \
  --address-family ipv4 \
  --description "Development pool"

Replace ipam-scope-0abcd1234 with your actual private scope ID and ipam-pool-1abcd1234 with your regional pool ID.

Note: It's important to include the --locale parameter to match the parent pool's locale.

Wait for the development pool to be fully created and available:

aws ec2 describe-ipam-pools --ipam-pool-ids ipam-pool-2abcd1234 --query 'IpamPools[0].State' --output text

Replace ipam-pool-2abcd1234 with your actual development pool ID. The state should be create-complete before proceeding.

After the pool is available, provision a CIDR block to it:

aws ec2 provision-ipam-pool-cidr \
  --ipam-pool-id ipam-pool-2abcd1234 \
  --cidr 10.0.0.0/24

Wait for the CIDR to be fully provisioned:

aws ec2 get-ipam-pool-cidrs --ipam-pool-id ipam-pool-2abcd1234 --query "IpamPoolCidrs[?Cidr=='10.0.0.0/24'].State" --output text

The state should be provisioned before proceeding.

Create a VPC using an IPAM pool CIDR

Finally, create a VPC that uses a CIDR from your IPAM pool. This demonstrates how IPAM can be used to allocate IP address space to Amazon resources.

Create a VPC using an IPAM pool CIDR:

aws ec2 create-vpc \
  --ipv4-ipam-pool-id ipam-pool-2abcd1234 \
  --ipv4-netmask-length 26 \
  --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=IPAM-VPC}]'

Replace ipam-pool-2abcd1234 with your actual development pool ID.

The --ipv4-netmask-length 26 parameter specifies that you want a /26 CIDR block (64 IP addresses) allocated from the pool. This netmask length is chosen to ensure it's smaller than the pool's CIDR block (/24).

Verify that your VPC was created:

aws ec2 describe-vpcs --filters "Name=tag:Name,Values=IPAM-VPC"

Verify the IPAM pool allocation

Check that the CIDR was allocated from your IPAM pool:

aws ec2 get-ipam-pool-allocations \
  --ipam-pool-id ipam-pool-2abcd1234

Replace ipam-pool-2abcd1234 with your actual development pool ID.

This command shows all allocations from the specified IPAM pool, including the VPC you just created.

Troubleshooting

Here are some common issues you might encounter when working with IPAM:

Clean up resources

When you're done with this tutorial, you should clean up the resources you created to avoid incurring unnecessary charges.

Replace all IDs with your actual resource IDs.

Next steps

Now that you've learned how to create and use IPAM with the Amazon CLI, you might want to explore more advanced features: