Tutorial: Create an IPAM and pools using the Amazon CLI - Amazon Virtual Private Cloud
Step 1: Enable IPAM in your organizationStep 2: Create an IPAMStep 3: Create an IPv4 address poolStep 4: Provision a CIDR to the top-level poolStep 5. Create a Regional pool with CIDR sourced from the top-level poolStep 6: Provision a CIDR to the Regional poolStep 7. Create a RAM share for enabling IP assignments across accountsStep 8. Create a VPCStep 9. Cleanup
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).

Tutorial: Create an IPAM and pools using the Amazon CLI

Follow the steps in this tutorial to use the Amazon CLI to create an IPAM, create IP address pools, and allocate a VPC with a CIDR from an IPAM pool.

The following is an example hierarchy of the pool structure that you will create by following the steps in this section:

  • IPAM operating in Amazon Region 1, Amazon Region 2

    • Private scope

      • Top-level pool

        • Regional pool in Amazon Region 2

          • Development pool

            • Allocation for a VPC

Note

In this section, you'll create an IPAM. By default, you can only create one IPAM. For more information, see Quotas for your IPAM. If you have already delegated an IPAM account and created an IPAM, you can skip steps 1 and 2.

Step 1: Enable IPAM in your organization

This step is optional. Complete this step to enable IPAM in your organization and configure your delegated IPAM using the Amazon CLI. For more information about the role of the IPAM account, see Integrate IPAM with accounts in an Amazon Organization.

This request must be made from an Amazon Organizations management account. When you run the following command, ensure that you’re using a role with an IAM policy that permits the following actions:

  • ec2:EnableIpamOrganizationAdminAccount

  • organizations:EnableAwsServiceAccess

  • organizations:RegisterDelegatedAdministrator

  • iam:CreateServiceLinkedRole

aws ec2 enable-ipam-organization-admin-account --region us-east-1 --delegated-admin-account-id 11111111111

You should see the following output, indicating that enabling was successful. 

{
    "Success": true
}

Step 2: Create an IPAM

Follow the steps in this section to create an IPAM and view additional information about the scopes that are created. You will use this IPAM when you create pools and provision IP address ranges for those pools in later steps.

Note

The operating Regions option determines which Amazon Regions the IPAM pools can be used for. For more information about operating Regions, see Create an IPAM.

To create an IPAM using the Amazon CLI

  1. Run the following command to create the IPAM instance.

    aws ec2 create-ipam --description my-ipam --region us-east-1 --operating-regions RegionName=us-west-2

    When you create an IPAM, Amazon automatically does the following:

    • Returns a globally unique resource ID (IpamId) for the IPAM.

    • Creates a default public scope (PublicDefaultScopeId) and a default private scope (PrivateDefaultScopeId).

    {                                                                                      
    "Ipam": {
        "OwnerId": "123456789012",
        "IpamId": "ipam-0de83dba6694560a9",
        "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
        "PublicDefaultScopeId": "ipam-scope-02a24107598e982c5",
        "PrivateDefaultScopeId": "ipam-scope-065e7dfe880df679c",
        "ScopeCount": 2,
        "Description": "my-ipam",
        "OperatingRegions": [
            {
                "RegionName": "us-west-2"
            },
            {
                "RegionName": "us-east-1"
            }
        ],
        "Tags": []
    }
}

  2. Run the following command to view additional information related to the scopes. The public scope is intended for IP addresses that are going to be accessed via public internet. The private scope is intended for IP addresses that are not going to be accessed via public internet.

    aws ec2 describe-ipam-scopes --region us-east-1

    In the output, you see the available scopes. You'll use the private scope ID in the next step.

    {
    "IpamScopes": [
        {
            "OwnerId": "123456789012",
            "IpamScopeId": "ipam-scope-02a24107598e982c5",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-02a24107598e982c5",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
            "IpamScopeType": "public",
            "IsDefault": true,
            "PoolCount": 0
        },
        {
            "OwnerId": "123456789012",
            "IpamScopeId": "ipam-scope-065e7dfe880df679c",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
            "IpamScopeType": "private",
            "IsDefault": true,
            "PoolCount": 0
        }
    ]
}

Step 3: Create an IPv4 address pool

Follow the steps in this section to create an IPv4 address pool.

Important

You won't use the --locale option on this top-level pool. You will set the locale option later on the Regional pool. The locale is the AWS Region where you want a pool to be available for CIDR allocations. As a result of not setting the locale on the top-level pool, the locale will default to None. If a pool has a locale of None, the pool won't be available to VPC resources in any Amazon Region. You can only manually allocate IP address space in the pool to reserve space.

To create an IPv4 address pool for all of your Amazon resources using the Amazon CLI

  1. Run the following command to create an IPv4 address pool. Use the ID of the private scope of the IPAM that you created in the previous step.

    aws ec2 create-ipam-pool --ipam-scope-id ipam-scope-065e7dfe880df679c --description "top-level-pool" --address-family ipv4

    In the output, you'll see a state of create-in-progress for the pool.

    {
    "IpamPool": {
        "OwnerId": "123456789012",
        "IpamPoolId": "ipam-pool-0008f25d7187a08d9",
        "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0008f25d7187a08d9",
        "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
        "IpamScopeType": "private",
        "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
        "Locale": "None",
        "PoolDepth": 1,
        "State": "create-in-progress",
        "Description": "top-level-pool",
        "AutoImport": false,
        "AddressFamily": "ipv4",
        "Tags": []
    }
}

  2. Run the following command until you see a state of create-complete in the output.

    aws ec2 describe-ipam-pools

    The following example output shows the correct state.

    {
    "IpamPools": [
        {
            "OwnerId": "123456789012",
            "IpamPoolId": "ipam-pool-0008f25d7187a08d9",
            "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0008f25d7187a08d9",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
            "IpamScopeType": "private",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
            "Locale": "None",
            "PoolDepth": 1,
            "State": "create-complete",
            "Description": "top-level-pool",
            "AutoImport": false,
            "AddressFamily": "ipv4"
        }
    ]
}

Step 4: Provision a CIDR to the top-level pool

Follow the steps in this section to provision a CIDR to the top-level pool, and then verify that the CIDR is provisioned. For more information, see Provision CIDRs to a pool.

To provision a CIDR block to the pool using the Amazon CLI

  1. Run the following command to provision the CIDR.

    aws ec2 provision-ipam-pool-cidr --region us-east-1 --ipam-pool-id ipam-pool-0008f25d7187a08d9 --cidr 10.0.0.0/8

    In the output, you can verify the state of the provisioning.

    {
    "IpamPoolCidr": {                     
        "Cidr": "10.0.0.0/8",        
        "State": "pending-provision"      
    }                                     
}

  2. Run the following command until you see a state of provisioned in the output.

    aws ec2 get-ipam-pool-cidrs --region us-east-1 --ipam-pool-id ipam-pool-0008f25d7187a08d9

    The following example output shows the correct state.

    {
    "IpamPoolCidrs": [                     
        {                                  
            "Cidr": "10.0.0.0/8",     
            "State": "provisioned"         
        }                                  
    ]                                      
}

Step 5. Create a Regional pool with CIDR sourced from the top-level pool

When you create an IPAM pool, the pool belongs to the Amazon Region of the IPAM by default. When you create a VPC, the pool that the VPC draws from must be in the same Region as the VPC. You can use the --locale option when you create a pool to make the pool available to services in a Region other than the Region of the IPAM. Follow the steps in this section to create a Regional pool in another locale.

To create a pool with a CIDR sourced from the previous pool using the Amazon CLI

  1. Run the following command to create the pool and insert space with a known available CIDR from the previous pool.

    aws ec2 create-ipam-pool --description "regional--pool" --region us-east-1 --ipam-scope-id ipam-scope-065e7dfe880df679c --source-ipam-pool-id 
ipam-pool-0008f25d7187a08d9 --locale us-west-2 --address-family ipv4

    In the output, you'll see the ID of the pool that you created. You'll need this ID in the next step.

    {
    "IpamPool": {
        "OwnerId": "123456789012",
        "IpamPoolId": "ipam-pool-0da89c821626f1e4b",
        "SourceIpamPoolId": "ipam-pool-0008f25d7187a08d9",
        "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0da89c821626f1e4b",
        "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
        "IpamScopeType": "private",
        "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
        "Locale": "us-west-2",
        "PoolDepth": 2,
        "State": "create-in-progress",
        "Description": "regional--pool",
        "AutoImport": false,
        "AddressFamily": "ipv4",
        "Tags": []
    }
}

  2. Run the following command until you see a state of create-complete in the output.

    aws ec2 describe-ipam-pools

    In the output, you see the pools that you have in your IPAM. In this tutorial, we created a top-level and a Regional pool, so you'll see them both.

    {
    "IpamPools": [
        {
            "OwnerId": "123456789012",
            "IpamPoolId": "ipam-pool-0008f25d7187a08d9",
            "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0008f25d7187a08d9",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
            "IpamScopeType": "private",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
            "Locale": "None",
            "PoolDepth": 1,
            "State": "create-complete",
            "Description": "top-level-pool",
            "AutoImport": false,
            "AddressFamily": "ipv4"
        },
        {
            "OwnerId": "123456789012",
            "IpamPoolId": "ipam-pool-0da89c821626f1e4b",
            "SourceIpamPoolId": "ipam-pool-0008f25d7187a08d9",
            "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0da89c821626f1e4b",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-065e7dfe880df679c",
            "IpamScopeType": "private",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-0de83dba6694560a9",
            "Locale": "us-west-2",
            "PoolDepth": 2,
            "State": "create-complete",
            "Description": "regional--pool",
            "AutoImport": false,
            "AddressFamily": "ipv4"
        }
    ]
}

Step 6: Provision a CIDR to the Regional pool

Follow the steps in this section to assign a CIDR block to the pool, and validate that it’s been successfully provisioned.

To assign a CIDR block to the Regional pool using the Amazon CLI

  1. Run the following command to provision the CIDR.

    aws ec2 provision-ipam-pool-cidr --region us-east-1 --ipam-pool-id ipam-pool-0da89c821626f1e4b --cidr 10.0.0.0/16

    In the output, you see the state of the pool.

    {
    "IpamPoolCidr": {                     
        "Cidr": "10.0.0.0/16",       
        "State": "pending-provision"      
    }                                     
}

  2. Run the following command until you see the state of provisioned in the output.

    aws ec2 get-ipam-pool-cidrs --region us-east-1 --ipam-pool-id ipam-pool-0da89c821626f1e4b

    The following example output shows the correct state.

    {
    "IpamPoolCidrs": [                     
        {                                  
            "Cidr": "10.0.0.0/16",     
            "State": "provisioned"         
        }                                  
    ]                                      
}

  3. Run the following command to query the top-level pool to view the allocations. The Regional pool is considered an allocation within the top-level pool.

    aws ec2 get-ipam-pool-allocations --region us-east-1 --ipam-pool-id ipam-pool-0008f25d7187a08d9

    In the output, you see the Regional pool as an allocation in the top-level pool.

    {
    "IpamPoolAllocations": [
        {
            "Cidr": "10.0.0.0/16",
            "IpamPoolAllocationId": "ipam-pool-alloc-fbd525f6c2bf4e77a75690fc2d93479a",
            "ResourceId": "ipam-pool-0da89c821626f1e4b",
            "ResourceType": "ipam-pool",
            "ResourceOwner": "123456789012"
        }
    ]
}

Step 7. Create a RAM share for enabling IP assignments across accounts

This step is optional. You can complete this step only if you completed Integrate IPAM with accounts in an Amazon Organization.

When you create an IPAM pool Amazon RAM share, it enables IP assignments across accounts. RAM sharing is only available in your home Amazon Region. Note that you create this share in the same Region as the IPAM, not in the local Region for the pool. All administrative operations on IPAM resources are made through the home Region of your IPAM. The example in this tutorial creates a single share for a single pool, but you can add multiple pools to a single share. For more information, including an explanation of the options that you must enter, see Share an IPAM pool using Amazon RAM.

Run the following command to create a resource share.

aws ram create-resource-share --region us-east-1 --name pool_share --resource-arns arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0dec9695bca83e606 --principals 123456

The output shows that the pool was created.

{
    "resourceShare": {
        "resourceShareArn": "arn:aws:ram:us-west-2:123456789012:resource-share/3ab63985-99d9-1cd2-7d24-75e93EXAMPLE",
        "name": "pool_share",
        "owningAccountId": "123456789012",
        "allowExternalPrincipals": false,
        "status": "ACTIVE",
        "creationTime": 1565295733.282,
        "lastUpdatedTime": 1565295733.282
    }
}

Step 8. Create a VPC

Run the following command to create a VPC and assign a CIDR block to the VPC from the pool in your newly created IPAM.

aws ec2 create-vpc --region us-east-1 --ipv4-ipam-pool-id ipam-pool-04111dca0d960186e --cidr-block 10.0.0.0/24

The output shows that the VPC was created.

{
    "Vpc": {
        "CidrBlock": "10.0.0.0/24",
        "DhcpOptionsId": "dopt-19edf471",
        "State": "pending",
        "VpcId": "vpc-0983f3c454f3d8be5",
        "OwnerId": "123456789012",   
        "InstanceTenancy": "default",
        "Ipv6CidrBlockAssociationSet": [],
        "CidrBlockAssociationSet": [
            {
                "AssociationId": "vpc-cidr-assoc-00b24cc1c2EXAMPLE",
                "CidrBlock": "10.0.0.0/24",
                "CidrBlockState": {
                    "State": "associated"
                }
            }
        ],
        "IsDefault": false
    }
}

Step 9. Cleanup

Follow the steps in this section to delete the IPAM resources you've created in this tutorial.

  1. Delete the VPC.

    aws ec2 delete-vpc --vpc-id vpc-0983f3c454f3d8be5

  2. Delete the IPAM pool RAM share.

    aws ram delete-resource-share --resource-share-arn arn:aws:ram:us-west-2:123456789012:resource-share/3ab63985-99d9-1cd2-7d24-75e93EXAMPLE

  3. Deprovision pool CIDR from the Regional pool.

     aws ec2 deprovision-ipam-pool-cidr --ipam-pool-id ipam-pool-0da89c821626f1e4b --region us-east-1

  4. Deprovision pool CIDR from the top-level pool.

     aws ec2 deprovision-ipam-pool-cidr --ipam-pool-id ipam-pool-0008f25d7187a08d9 --region us-east-1

  5. Delete the IPAM

    aws ec2 delete-ipam --region us-east-1