Tutorial: Transfer a BYOIP IPv4 CIDR to IPAM - Amazon Virtual Private Cloud
Step 1: Create Amazon CLI named profiles and IAM rolesStep 2: Get your IPAM’s public scope IDStep 3: Create an IPAM poolStep 4: Share the IPAM pool using Amazon RAMStep 5: Transfer an existing BYOIP IPV4 CIDR to IPAMStep 6: View the CIDR in IPAMStep 7: 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: Transfer a BYOIP IPv4 CIDR to IPAM

Follow these steps to transfer an existing IPv4 CIDR to IPAM. If you already have an IPv4 BYOIP CIDR with Amazon, you can move the CIDR to IPAM from a public IPv4 pool. You cannot move an IPv6 CIDR to IPAM.

This tutorial assumes you have already successfully brought an IP address range to Amazon using the process described in Bring your own IP addresses (BYOIP) in Amazon EC2 and now you want to transfer that IP address range to IPAM. If you are bringing a new IP address to Amazon for the first time, complete the steps in Tutorial: Bring your IP addresses to IPAM.

If you transfer a public IPv4 pool to IPAM, there is no impact on existing allocations. Once you transfer a public IPv4 pool to IPAM, depending on the resource type, you may be able to monitor the existing allocations. For more information, see Monitor CIDR usage by resource.

Important

  • This tutorial assumes you have already completed the steps in Create an IPAM.

  • Each step of this tutorial must be done by one of two Amazon accounts:

    • The account for the IPAM administrator. In this tutorial, this account will be called the IPAM account.

    • The account in your organization which owns the BYOIP CIDR. In this tutorial, this account will be called the BYOIP CIDR owner account.

Step 1: Create Amazon CLI named profiles and IAM roles

To complete this tutorial as a single Amazon user, you can use Amazon CLI named profiles to switch from one IAM role to another. Named profiles are collections of settings and credentials that you refer to when using the --profile option with the Amazon CLI. For more information about how to create IAM roles and named profiles for Amazon accounts, see Using an IAM role in the Amazon CLI in the Amazon Identity and Access Management User Guide.

Create one role and one named profile for each of the three Amazon accounts you will use in this tutorial:

  • A profile called ipam-account for the Amazon account that is the IPAM administrator.

  • A profile called byoip-owner-account for the Amazon account in your organization which owns the BYOIP CIDR.

After you have created the IAM roles and named profiles, return to this page and go to the next step. You will notice throughout the rest of this tutorial that the sample Amazon CLI commands use the --profile option with one of the named profiles to indicate which account must run the command.

Step 2: Get your IPAM’s public scope ID

Follow the steps in this section to get your IPAM’s public scope ID. This step should be performed by the ipam-account account.

Run the following command to get your public scope ID.

aws ec2 describe-ipams --region us-east-1 --profile ipam-account

In the output, you'll see your public scope ID. Note the values for PublicDefaultScopeId. You will need it in the next step.

{
 "Ipams": [
        {
            "OwnerId": "123456789012",
            "IpamId": "ipam-090e48e75758de279",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-090e48e75758de279",
            "PublicDefaultScopeId": "ipam-scope-0087d83896280b594",
            "PrivateDefaultScopeId": "ipam-scope-08b70b04fbd524f8d",
            "ScopeCount": 2,
            "Description": "my-ipam",
            "OperatingRegions": [
                {
                    "RegionName": "us-east-1"
                },
                {
                    "RegionName": "us-west-2"
                }
            ],
            "Tags": []
        }
    ]
}

Step 3: Create an IPAM pool

Follow the steps in this section to create an IPAM pool. This step should be performed by the ipam-account account. The IPAM pool you create must be a top-level pool with the --locale option matching the BYOIP CIDR Amazon Region. You can only transfer a BYOIP to a top-level IPAM pool.

Important

When you create the pool, you must include --aws-service ec2. The service you select determines the Amazon service where the CIDR will be advertisable. Currently, the only option is ec2, which means that the CIDRs allocated from this pool will be advertisable for the Amazon EC2 service (for Elastic IP addresses) and the Amazon VPC service (for CIDRs associated with VPCs).

To create an IPv4 address pool for the transferred BYOIP CIDR using the Amazon CLI

  1. Run the following command to create an IPAM pool. Use the ID of the public scope of the IPAM that you retrieved in the previous step.

    aws ec2 create-ipam-pool --region us-east-1 --profile ipam-account --ipam-scope-id ipam-scope-0087d83896280b594 --description "top-level-pool" --locale us-west-2 --aws-service ec2 --address-family ipv4

    In the output, you'll see create-in-progress, which indicates that pool creation is in progress.

    {
    "IpamPool": {
        "OwnerId": "123456789012",
        "IpamPoolId": "ipam-pool-0a03d430ca3f5c035",
        "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0a03d430ca3f5c035",
        "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-0087d83896280b594",
        "IpamScopeType": "public",
        "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-090e48e75758de279",
        "Locale": "us-west-2",
        "PoolDepth": 1,
        "State": "create-in-progress",
        "Description": "top-level-pool",
        "AutoImport": false,
        "AddressFamily": "ipv4",
        "Tags": [],
        "AwsService": "ec2"
    }
}

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

    aws ec2 describe-ipam-pools --region us-east-1 --profile ipam-account

    The following example output shows the state of the pool. You will need the OwnerId in the next step.

    {
    "IpamPools": [
        {
            "OwnerId": "123456789012",
            "IpamPoolId": "ipam-pool-0a03d430ca3f5c035",
            "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0a03d430ca3f5c035",
            "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-0087d83896280b594",
            "IpamScopeType": "public",
            "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-090e48e75758de279",
            "Locale": "us-west-2",
            "PoolDepth": 1,
            "State": "create-complete",
            "Description": "top-level-pool",
            "AutoImport": false,
            "AddressFamily": "ipv4",
            "Tags": [],
            "AwsService": "ec2"
        }
    ]
}

Step 4: Share the IPAM pool using Amazon RAM

Follow the steps in this section to share an IPAM pool using Amazon RAM so that another Amazon account can transfer an existing BYOIP IPV4 CIDR to the IPAM pool and use the IPAM pool. This step should be performed by the ipam-account account.

To share an IPv4 address pool using the Amazon CLI

  1. View the Amazon RAM permissions available for IPAM pools. You need both ARNs to complete the steps in this section.

    aws ram list-permissions --region us-east-1 --profile ipam-account --resource-type ec2:IpamPool
    {
    "permissions": [
        {
           "arn": "arn:aws:ram::aws:permission/AWSRAMDefaultPermissionsIpamPool",
           "version": "1",
           "defaultVersion": true,
           "name": "AWSRAMDefaultPermissionsIpamPool",
           "resourceType": "ec2:IpamPool",
           "status": "ATTACHABLE",
           "creationTime": "2022-06-30T13:04:29.335000-07:00",
           "lastUpdatedTime": "2022-06-30T13:04:29.335000-07:00",
           "isResourceTypeDefault": true
        },
        {
            "arn": "arn:aws:ram::aws:permission/AWSRAMPermissionIpamPoolByoipCidrImport",
            "version": "1",
            "defaultVersion": true,
            "name": "AWSRAMPermissionIpamPoolByoipCidrImport",
            "resourceType": "ec2:IpamPool",
            "status": "ATTACHABLE",
            "creationTime": "2022-06-30T13:03:55.032000-07:00",
            "lastUpdatedTime": "2022-06-30T13:03:55.032000-07:00",
            "isResourceTypeDefault": false
        }
    ]
}

  2. Create a resource share to enable the byoip-owner-account account to import BYOIP CIDRs to IPAM. The value for --resource-arns is the ARN of the IPAM pool that you created in the previous section. The value for --principals is the account ID of the BYOIP CIDR owner account. The value for --permission-arns is the ARN of the AWSRAMPermissionIpamPoolByoipCidrImport permission.

    aws ram create-resource-share --region us-east-1 --profile ipam-account --name PoolShare2 --resource-arns arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0a03d430ca3f5c035 --principals 111122223333 --permission-arns arn:aws:ram::aws:permission/AWSRAMPermissionIpamPoolByoipCidrImport
    {                                                                                                                    
    "resourceShare": {                                                                                               
        "resourceShareArn": "arn:aws:ram:us-east-1:123456789012:resource-share/7993758c-a4ea-43ad-be12-b3abaffe361a",
        "name": "PoolShare2",                                                                                      
        "owningAccountId": "123456789012",                                                                                         
        "allowExternalPrincipals": true,                                                                             
        "status": "ACTIVE",                                                                                          
        "creationTime": "2023-04-28T07:32:25.536000-07:00",                                                          
        "lastUpdatedTime": "2023-04-28T07:32:25.536000-07:00"                                                        
        }                                                                                                                
}

  3. (Optional) If you want to allow the byoip-owner-account account to allocate IP address CIDRS from the IPAM pool to public IPv4 pools after the transfer is complete, copy the ARN for AWSRAMDefaultPermissionsIpamPool and create a second resource share. The value for --resource-arns is the ARN of the IPAM pool that you created in the previous section. The value for --principals is the account ID of the BYOIP CIDR owner account. The value for --permission-arns is the ARN of the AWSRAMDefaultPermissionsIpamPool permission.

    aws ram create-resource-share --region us-east-1 --profile ipam-account --name PoolShare1 --resource-arns arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0a03d430ca3f5c035 --principals 111122223333 --permission-arns arn:aws:ram::aws:permission/AWSRAMDefaultPermissionsIpamPool
    {                                                                                                                    
    "resourceShare": {                                                                                               
        "resourceShareArn": "arn:aws:ram:us-east-1:123456789012:resource-share/8d1e229b-2830-4cf4-8b10-19c889235a2f",
        "name": "PoolShare1",                                                                                      
        "owningAccountId": "123456789012",                                                                                         
        "allowExternalPrincipals": true,                                                                             
        "status": "ACTIVE",                                                                                          
        "creationTime": "2023-04-28T07:31:25.536000-07:00",                                                          
        "lastUpdatedTime": "2023-04-28T07:31:25.536000-07:00"                                                        
        }                                                                                                                
}

As a result of creating the resource share in RAM, the byoip-owner-account account can now move CIDRs to IPAM.

Step 5: Transfer an existing BYOIP IPV4 CIDR to IPAM

Follow the steps in this section to transfer an existing BYOIP IPV4 CIDR to IPAM. This step should be performed by the byoip-owner-account account.

Important

Once you bring an IPv4 address range to Amazon, you can use all of the IP addresses in the range, including the first address (the network address) and the last address (the broadcast address).

To transfer the BYOIP CIDR to IPAM, the BYOIP CIDR owner must have these permissions in their IAM policy:

  • ec2:MoveByoipCidrToIpam

  • ec2:ImportByoipCidrToIpam

Note

You can use either the Amazon Web Services Management Console or the Amazon CLI for this step.

Amazon Management Console
To transfer a BYOIP CIDR to the IPAM pool:

  1. Open the IPAM console at https://console.aws.amazon.com/ipam/ as the byoip-owner-account account.

  2. In the navigation pane, choose Pools.

  3. Choose the top-level pool created and shared in this tutorial.

  4. Choose Actions > Transfer BYOIP CIDR.

  5. Choose Transfer BYOIP CIDR.

  6. Choose your BYOIP CIDR.

  7. Choose Provision.

Command line

Use the following Amazon CLI commands transfer a BYOIP CIDR to the IPAM pool using the Amazon CLI:

  1. Run the following command to transfer the CIDR. Ensure that the --region value is the Amazon Region of the BYOIP CIDR.

    aws ec2 move-byoip-cidr-to-ipam --region us-west-2 --profile byoip-owner-account --ipam-pool-id ipam-pool-0a03d430ca3f5c035 --ipam-pool-owner 123456789012 --cidr 130.137.249.0/24

    In the output, you'll see the CIDR pending provision.

    {
    "ByoipCidr": {                                                                 
        "Cidr": "130.137.249.0/24",                                              
        "State": "pending-transfer"                                                      
    }                                                                              
}

  2. Ensure that the CIDR has been transferred. Run the following command until you see a state of complete-transfer in the output.

    aws ec2 move-byoip-cidr-to-ipam --region us-west-2  --profile byoip-owner-account --ipam-pool-id ipam-pool-0a03d430ca3f5c035 --ipam-pool-owner 123456789012 --cidr 130.137.249.0/24

    The following example output shows the state.

    {
    "ByoipCidr": {                                                                 
        "Cidr": "130.137.249.0/24",                                              
        "State": "complete-transfer"                                                      
    }                                                                              
}

Step 6: View the CIDR in IPAM

Follow the steps in this section to view the CIDR in IPAM. This step should be performed by the ipam-account account.

To view the transferred BYOIP CIDR in IPAM pool using the Amazon CLI

  • Run the following command to view the allocation managed in IPAM. Ensure that the --region value is the Amazon Region of the BYOIP CIDR.

    aws ec2 get-ipam-pool-allocations --region us-west-2  --profile ipam-account --ipam-pool-id ipam-pool-0d8f3646b61ca5987

    The output shows the allocation in IPAM.

    {
    "IpamPoolAllocations": [
        {
            "Cidr": "130.137.249.0/24",
            "IpamPoolAllocationId": "ipam-pool-alloc-5dedc8e7937c4261b56dc3e3eb53dc46",
            "ResourceId": "ipv4pool-ec2-0019eed22a684e0b3",
            "ResourceType": "ec2-public-ipv4-pool",
            "ResourceOwner": "111122223333"
        }
    ]
}

Step 7: Cleanup

Follow the steps in this section to remove the resources you created in this tutorial. This step should be performed by the ipam-account account.

To cleanup the resources created in this tutorial using the Amazon CLI

  1. To delete the IPAM pool shared resource, run the following command to get the first resource share ARN:

    aws ram get-resource-shares --region us-east-1 --profile ipam-account --name PoolShare1 --resource-owner SELF
    {
    "resourceShares": [
        {
            "resourceShareArn": "arn:aws:ram:us-east-1:123456789012:resource-share/8d1e229b-2830-4cf4-8b10-19c889235a2f",
            "name": "PoolShare1",
            "owningAccountId": "123456789012",
            "allowExternalPrincipals": true,
            "status": "ACTIVE",
            "creationTime": "2023-04-28T07:31:25.536000-07:00",
            "lastUpdatedTime": "2023-04-28T07:31:25.536000-07:00",
            "featureSet": "STANDARD"
        }
    ]
}

  2. Copy the resource share ARN and use it to delete the IPAM pool resource share. 

    aws ram delete-resource-share --region us-east-1 --profile ipam-account --resource-share-arn arn:aws:ram:us-east-1:123456789012:resource-share/8d1e229b-2830-4cf4-8b10-19c889235a2f
    {                      
    "returnValue": true
}

  3. If you created an additional resource share in Step 4: Share the IPAM pool using Amazon RAM, repeat the previous two steps to get the second resource share ARN for PoolShare2 and delete the second resource share.

  4. Run the following command to get the allocation ID for the BYOIP CIDR. Ensure that the --region value matches the Amazon Region of the BYOIP CIDR.

    aws ec2 get-ipam-pool-allocations --region us-west-2  --profile ipam-account --ipam-pool-id ipam-pool-0d8f3646b61ca5987

    The output shows the allocation in IPAM.

    {
    "IpamPoolAllocations": [
        {
            "Cidr": "130.137.249.0/24",
            "IpamPoolAllocationId": "ipam-pool-alloc-5dedc8e7937c4261b56dc3e3eb53dc46",
            "ResourceId": "ipv4pool-ec2-0019eed22a684e0b3",
            "ResourceType": "ec2-public-ipv4-pool",
            "ResourceOwner": "111122223333"
        }
    ]
}

  5. Release the last IP address in the CIDR from the public IPv4 pool. Enter the IP address with a netmask of /32. You must rerun this command for each IP address in the CIDR range. If your CIDR is a /24, you will have to run this command to deprovision each of the 256 IP addresses in the /24 CIDR. When you run the command in this section, the value for --region must match the Region of your IPAM.

    This step must be done by the byoip-owner-account account.

    aws ec2 deprovision-public-ipv4-pool-cidr --region us-east-1  --profile byoip-owner-account --pool-id ipv4pool-ec2-0019eed22a684e0b3 --cidr 130.137.249.255/32

    In the output, you'll see the deprovisioned CIDR.

    {
    "PoolId": "ipv4pool-ec2-0019eed22a684e0b3",                                                                                       
    "DeprovisionedAddresses": [                                                                                                       
        "130.137.249.255"                                                                                                             
    ]                                                                                                                                 
}

  6. View your BYOIP CIDRs again and ensure there are no more provisioned addresses. When you run the command in this section, the value for --region must match the Region of your IPAM.

    This step must be done by the byoip-owner-account account.

    aws ec2 describe-public-ipv4-pools --region us-east-1 --profile byoip-owner-account

    In the output, you'll see the IP addresses count in your public IPv4 pool.

    {
    "PublicIpv4Pools": [
        {
            "PoolId": "ipv4pool-ec2-0019eed22a684e0b3",
            "Description": "",
            "PoolAddressRanges": [],
            "TotalAddressCount": 0,
            "TotalAvailableAddressCount": 0,
            "NetworkBorderGroup": "us-east-1",
            "Tags": []
        }
    ]
}

  7. Run the following command to delete the top-level pool.

    aws ec2 delete-ipam-pool --region us-east-1  --profile ipam-account --ipam-pool-id ipam-pool-0a03d430ca3f5c035

    In the output, you can see the delete state.

    {
    "IpamPool": {
        "OwnerId": "123456789012",
        "IpamPoolId": "ipam-pool-0a03d430ca3f5c035",
        "IpamPoolArn": "arn:aws:ec2::123456789012:ipam-pool/ipam-pool-0a03d430ca3f5c035",
        "IpamScopeArn": "arn:aws:ec2::123456789012:ipam-scope/ipam-scope-0087d83896280b594",
        "IpamScopeType": "public",
        "IpamArn": "arn:aws:ec2::123456789012:ipam/ipam-090e48e75758de279",
        "Locale": "us-east-1",
        "PoolDepth": 2,
        "State": "delete-in-progress",
        "Description": "top-level-pool",
        "AutoImport": false,
        "Advertisable": true,
        "AddressFamily": "ipv4",
        "AwsService": "ec2"
    }
}