Technical Information

AWS VPC IPAM to NetBox object mapping

The integration queries the AWS EC2 IPAM APIs and emits three NetBox object types through Diode: VRF, Prefix, and IPAddress. No Tenant, Manufacturer, or custom field objects are created.

Object type mapping table

VRF name enrichment

The scope VRF name is derived from the IPAM scope's tags. If the scope has a Name tag with a non-empty value, that value is used as the VRF name after trimming surrounding whitespace. If the Name tag is unset, empty, or whitespace-only, the VRF name falls back to the scope ID (for example ipam-scope-08c06b7b3f4853315).

NetBox limits VRF.name to 100 characters. A Name tag longer than 100 characters is truncated to fit, and a warning is logged.

VPC VRFs are always named after the VpcId, not an AWS Name tag, because two VPCs can share a Name while the VpcId is globally unique.

VRF assignment and overlapping CIDRs

• Scope VRFs hold pool inventory (provisioned CIDRs and allocations) and any resource CIDRs that do not carry a VpcId (for example unattached Elastic IPs).
• VPC VRFs are created for resource CIDRs that carry a VpcId, keyed on the VpcId. This gives each VPC its own routing-isolation boundary in NetBox so that overlapping CIDRs across VPCs (for example dev, staging, and prod all on 10.0.0.0/16) coexist without colliding on the NetBox (prefix, vrf) uniqueness constraint.

Route distinguisher (RD) scheme

Both VRF kinds set an RD to guarantee uniqueness and traceability while staying within the NetBox 21-character RD limit:

• Scope VRF: ScopeID: + the last 13 hexadecimal characters of the scope ID (for example ScopeID:6b7b3f4853315).
• VPC VRF: VPC: + the last 13 hexadecimal characters of the VPC ID (for example VPC:b19444de235e8).

Host address handling

Resource CIDRs with a /32 (IPv4) or /128 (IPv6) mask are modeled as NetBox IPAddress objects rather than prefixes. AWS IPAM represents single-host Elastic IPs this way. All other resource CIDRs become prefixes.

Configuration keys

All keys are read from the policy config block.

AWS access keys (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) are not policy config keys. They are read from the agent process environment through the standard boto3 credential chain.

There is no BOOTSTRAP key for this integration. It creates no custom fields or other static content, so no bootstrap run is required.

Authentication

The integration builds a boto3 EC2 client per region. Source credentials are resolved as follows:

• If AWS_ROLE_ARN is not set: AWS_PROFILE is used when present, otherwise the default boto3 credential chain (environment variables, ~/.aws/credentials, or an attached instance/task role).
• If AWS_ROLE_ARN is set: the source credentials above call sts:AssumeRole against the target role, and the returned short-lived credentials build the EC2 client. The role is assumed per region so credentials stay fresh on long multi-region runs.

Required IAM permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeIpams",
        "ec2:DescribeIpamScopes",
        "ec2:DescribeIpamPools",
        "ec2:GetIpamPoolCidrs",
        "ec2:GetIpamPoolAllocations",
        "ec2:GetIpamResourceCidrs"
      ],
      "Resource": "*"
    }
  ]
}

For cross-account access, the source identity additionally needs sts:AssumeRole on the target role ARN, and the target role's trust policy must allow the source identity to assume it. The target role carries the IPAM read permissions above.

AWS APIs used

• describe_ipams - IPAM instances in the region
• describe_ipam_scopes (filtered by ipam-id) - scopes per IPAM
• describe_ipam_pools (filtered by ipam-scope-id) - pools per scope
• get_ipam_pool_cidrs - provisioned CIDRs per pool (paginated, 100 per page)
• get_ipam_pool_allocations - allocations per pool (paginated, 1000 per page)
• get_ipam_resource_cidrs (filtered by ipam-scope-id) - resource CIDRs per scope (paginated, 1000 per page)
• sts:AssumeRole - only when AWS_ROLE_ARN is set

Tags and metadata

Every object created by the integration is tagged with:

• aws-vpc-ipam - the integration identity tag applied to all objects
• aws:<region> - a per-region tag (for example aws:us-east-1) that conveys region grouping

Region grouping is expressed only through the aws:<region> tag. No Tenant is created or assigned, so customers can filter and group by region without the integration imposing a tenant structure on their NetBox data.

Multi-region behavior

Each region in AWS_VPC_IPAM_REGION is processed independently. An AWS-side failure on one region (throttling, IAM denial, or IPAM not enabled) is logged and skipped, and the run continues with the remaining regions. Missing or incomplete AWS credentials, or a failure to assume the cross-account role, abort the entire run because those errors are global rather than per-region.

If AWS_VPC_IPAM_SCOPE_IDS lists a scope ID that is not found in any processed region, a warning is logged so you can check for typos or a scope that belongs to a region not in AWS_VPC_IPAM_REGION.

Known limitations

• Objects are only created in NetBox; the integration does not delete objects that no longer exist in AWS.
• After a run that predates per-VPC VRFs, resource-CIDR prefixes created under scope VRFs by earlier runs are not migrated to VPC VRFs.
• Data flows one way only. The integration does not push scopes or pools from NetBox back to AWS VPC IPAM.
• The integration only reads from AWS VPC IPAM. It does not discover IP information through other AWS endpoints.