FAQ & Troubleshooting

Frequently asked questions

We don't use AWS VPC IPAM. Can the integration discover IP information through other AWS endpoints?

Not currently. To use the integration you must have AWS VPC IPAM enabled. Support for other AWS endpoints may be added in the future.

Is the integration free to use?

The AWS VPC IPAM integration is available with commercial editions of NetBox (NetBox Cloud and NetBox Enterprise).

Do I need NetBox Assurance?

Yes. The integration extracts and transforms the latest state from AWS VPC IPAM and sends it to NetBox Assurance, where you control how it is ingested into NetBox.

Which NetBox versions are supported?

NetBox 4.1 and above.

Which AWS VPC IPAM versions are supported?

The integration is maintained to remain compatible with the latest AWS APIs available in the boto3 library. The Advanced Tier is required for private IP management.

Can the integration push scopes and pools from NetBox back to AWS VPC IPAM?

No. Data flows one way only, from AWS VPC IPAM into NetBox.

Does the integration create NetBox Tenants?

No. Region grouping is expressed through the aws:<region> tag applied to every object, so the integration does not impose a tenant structure on your NetBox data.

Does the integration delete objects from NetBox?

No. Objects are only created. The integration does not remove NetBox objects that no longer exist in AWS.

Why don't my public IPAM scopes appear in NetBox?

The AWS_VPC_IPAM_SCOPE_TYPE config key defaults to private, so only private scopes are ingested. Set it to public or all to include public scopes.

Common issues

1. Missing or incomplete AWS credentials:

   AWS credentials not found or incomplete. Please configure your AWS credentials
   (e.g., via environment variables, ~/.aws/credentials, or an assumed role).

   Solution: Confirm that AWS credentials are available to the agent container through one of the supported methods (environment variables, an AWS profile, an instance/task role, or a cross-account role). Credential errors abort the whole run.

2. Missing region:

   AWS_VPC_IPAM_REGION must be provided in policy config

   or

   AWS_VPC_IPAM_REGION must contain at least one non-empty region

   Solution: Set AWS_VPC_IPAM_REGION in the policy config block to a single region, a comma-separated list, or a YAML list of regions.

3. Invalid scope type:

   AWS_VPC_IPAM_SCOPE_TYPE must be one of ('private', 'public', 'all'), got ...

   Solution: Set AWS_VPC_IPAM_SCOPE_TYPE to private, public, or all, or remove it to use the private default.

4. Cross-account role assumption fails:

   Failed to assume role arn:aws:iam::...:role/... : ...

   Solution: Verify the AWS_ROLE_ARN value, that the source identity is permitted to call sts:AssumeRole on the target role, and that the target role's trust policy allows the source identity. AssumeRole failures abort the whole run.

5. No IPAMs found in a region:

   No IPAMs found in region <region>

   Solution: Confirm that AWS VPC IPAM is enabled in the specified region and that the IAM identity has the required ec2:DescribeIpams permission. This is logged as a warning and that region produces no entities.

6. A configured scope ID matched nothing:

   AWS_VPC_IPAM_SCOPE_IDS lists scope ID(s) not found in any processed region: ...

   Solution: Check the scope IDs in AWS_VPC_IPAM_SCOPE_IDS for typos, whether they belong to a region not listed in AWS_VPC_IPAM_REGION, or whether their region failed to process (see earlier per-region errors in the log).

7. Permission errors accessing the output directory:

   Permission denied when accessing /opt/orb/

   Solution: Ensure the mounted directory has proper read and write permissions.

Support

Email support@netboxlabs.com for support.