Getting Started

This guide covers how to set up and run the AWS VPC IPAM Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• AWS Requirements
  • IAM Permissions
  • Choose an authentication method
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Ingestion Filters
  • Multi-Region and Cross-Account
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
• Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the AWS VPC IPAM Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• AWS VPC IPAM enabled in your AWS account (the Advanced Tier is required for private IP management)
• AWS credentials with the IAM permissions listed below
• Host System with Docker support
• Network connectivity between your host and both your NetBox instance and the AWS APIs

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2GB RAM (4GB recommended)
• Storage: 1GB free disk space
• Network: Stable internet connection for pulling Docker images
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound HTTPS access to the AWS EC2 and STS API endpoints (port 443)
• DNS resolution for both your NetBox instance and the AWS API endpoints
• Firewall rules configured to allow the above connections from your agent host

AWS Requirements

IAM Permissions

The identity used by the integration needs read access to the AWS VPC IPAM APIs. Attach a policy with the following permissions:

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

If you use cross-account access (see Multi-Region and Cross-Account), the source identity also needs permission to assume the target role, and the target role carries the IPAM read permissions above:

{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::222222222222:role/netbox-ipam-reader"
}

Choose an authentication method

The integration builds a boto3 EC2 client and uses the standard AWS credential chain. Choose the method that fits your environment. In every case you must set the AWS region (or regions) through the AWS_VPC_IPAM_REGION config key.

• Environment variables - set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN for temporary or SSO credentials). These are read from the agent container environment.
• AWS CLI profile - set the AWS_PROFILE config key to use a named profile from a mounted ~/.aws/credentials file.
• IAM role - when running on AWS infrastructure (EC2, ECS), attach an instance or task role. No credential config is needed beyond the region.
• Cross-account role assumption - set the AWS_ROLE_ARN config key to assume a role in another account via sts:AssumeRole before reading IPAM. The source credentials come from any of the methods above.

NetBox Setup

Generate Diode Client Credentials

1. Log into your NetBox instance
2. Navigate to Diode → Client Credentials
3. Click + Add a Credential
4. Enter a descriptive name (e.g., "AWS VPC IPAM Integration")
5. Click Create
6. Important: Copy and securely store the Client ID and Client Secret - you will need these in the agent configuration
7. Navigate to Diode → Settings
8. Copy the value of the Diode target - you will need this in the agent configuration

Agent Setup and Configuration

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and Token provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

Step 2: Configure the Agent

1. Create the configuration file (you can name the file anything you like):

touch agent.yaml

2. Edit the configuration file with your preferred editor and add the following configuration. Important: Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode > Settings > Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: aws_vpc_ipam_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      aws_vpc_ipam_worker:
        config:
          package: nbl_aws_vpc_ipam
          schedule: "0 2 * * *" # Daily at 2:00 AM. Set your desired schedule (see examples below)
          timeout: 5
          AWS_VPC_IPAM_REGION: us-east-1        # Required: single region, comma-separated list, or YAML list
          # AWS_PROFILE: my-profile             # Optional: named AWS CLI profile to use
          # AWS_VPC_IPAM_SCOPE_TYPE: private    # Optional: private (default), public, or all
          # AWS_VPC_IPAM_SCOPE_IDS:             # Optional: only ingest these scope IDs
          #   - ipam-scope-0abc123
          # AWS_VPC_IPAM_RESOURCE_TYPES:        # Optional: only ingest these resource-CIDR types
          #   - vpc
          #   - subnet
          # AWS_ROLE_ARN: arn:aws:iam::222222222222:role/netbox-ipam-reader  # Optional: cross-account role
          # AWS_ROLE_SESSION_NAME: netbox-prod-ipam                          # Optional: assumed-role session name
        scope:            # Required - leave empty (AWS VPC IPAM filtering is done via the config keys above)

Ingestion Filters

Three optional config keys narrow what gets synced into NetBox. All are unset by default, which means everything is ingested (subject to the scope type default of private).

• AWS_VPC_IPAM_SCOPE_TYPE - one of private (default), public, or all. Filters IPAM scopes by type. Most customers only want private scopes in NetBox.
• AWS_VPC_IPAM_SCOPE_IDS - a comma-separated string or YAML list of IPAM scope IDs. When set, only those scopes are ingested. Applied on top of AWS_VPC_IPAM_SCOPE_TYPE. Useful for keeping legacy or test scopes out of NetBox.
• AWS_VPC_IPAM_RESOURCE_TYPES - a comma-separated string or YAML list matched case-insensitively against each resource CIDR's ResourceType (vpc, subnet, eip, eni, public-ipv4-pool, ipv6-pool, anycast-ip-list). Large fleets can drop per-address noise (eip, eni) while keeping vpc and subnet prefixes.

Example: only private scopes, only VPC and subnet CIDRs

config:
  AWS_VPC_IPAM_SCOPE_TYPE: private
  AWS_VPC_IPAM_RESOURCE_TYPES:
    - vpc
    - subnet

Multi-Region and Cross-Account

To sync more than one region in a single policy, pass a comma-separated list or a YAML list to AWS_VPC_IPAM_REGION. Each region is processed independently. A per-region AWS failure (throttling, IAM denial, or IPAM not enabled) is logged and skipped, and the run continues with the remaining regions. Missing or incomplete credentials abort the whole run, since they apply globally.

config:
  AWS_VPC_IPAM_REGION:
    - us-east-1
    - eu-west-1
    - ap-south-1

To read IPAM data from a different AWS account (for example a hub-and-spoke setup where IPAM is centralized), set AWS_ROLE_ARN. Before querying IPAM the integration assumes that role via sts:AssumeRole using your source credentials. Optionally set AWS_ROLE_SESSION_NAME; it defaults to netbox-orb-agent-aws-vpc-ipam and surfaces in the target account's CloudTrail.

config:
  AWS_VPC_IPAM_REGION: us-east-1
  AWS_ROLE_ARN: arn:aws:iam::222222222222:role/netbox-ipam-reader
  AWS_ROLE_SESSION_NAME: netbox-prod-ipam

Optional - Dry Run Mode

The agent can be run in Dry Run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for troubleshooting or reviewing what the integration will ingest before committing to your NetBox instance.

Enable dry run in the diode section of your agent configuration file:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/ # saves the output file to this directory

Step 3: Run the Agent

Run the agent to synchronize data from AWS VPC IPAM into NetBox.

Method 1: Set Environment Variables Manually

1. Export Diode credentials as environment variables:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export AWS credentials as environment variables (skip this step if you use an AWS profile or an IAM role):

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
# export AWS_SESSION_TOKEN="your-session-token"   # Only for temporary/SSO credentials

3. Run the agent with the following command:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file in your current directory:

touch .env

2. Edit the .env file with your preferred editor and add the following content:

## NetBox Diode credentials (from NetBox Setup)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

## AWS credentials
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
# AWS_SESSION_TOKEN=your-session-token   # Only for temporary/SSO credentials

3. Run the agent with the following command:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

echo ".env" >> .gitignore

Expected Output

After starting the agent, depending on the schedule you defined, you should see output similar to the following:

{"time":"2026-07-20T02:00:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_aws_vpc_ipam.aws_vpc_ipam_diode:Found 1 IPAM(s) in region us-east-1"}
{"time":"2026-07-20T02:00:02.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_aws_vpc_ipam.aws_vpc_ipam_diode:Region us-east-1 summary: 4 VRFs, 27 Prefixes, 2 IPs to ingest."}
{"time":"2026-07-20T02:00:02.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_aws_vpc_ipam.aws_vpc_ipam_diode:AWS VPC IPAM sync complete: 1/1 regions succeeded, 33 entities emitted."}
{"time":"2026-07-20T02:00:03.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy aws_vpc_ipam_worker: Successful ingestion"}
{"time":"2026-07-20T02:00:03.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: cron[month='*', day='*', day_of_week='*', hour='2', minute='0'], next run at: 2026-07-21 02:00:00 UTC)\" executed successfully"}

View and Apply Discovered Data in NetBox Assurance

Once the agent has run, AWS VPC IPAM data is staged as deviations in the NetBox Assurance UI.

NetBox Assurance gives you control over operational drift by identifying deviations between your operational state and NetBox, and analytics to understand drift, plan for remediation, and ultimately take action.

Accessing NetBox Assurance

1. Navigate to your NetBox instance
2. Click on Assurance in the main navigation menu

Explore Deviation Types

1. Click on Deviation Types to view the types of deviations discovered
2. Click on the Name of a deviation type to view its deviations

3. Click on the Name of an individual deviation to view the details

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been Applied or Ignored
2. Click on the Name of a deviation to view the details

Apply Deviations

1. Select all the deviations you want to apply. If you are working with a large number of deviations, first set the Per Page view to 500:
2. Select the first deviation, hold SHIFT and select the last one, then click Apply Selected:
3. Click Apply X Deviations to write the deviations to the NetBox database:

View the AWS VPC IPAM Data in NetBox

After running the integration and applying the discovered data, you can view it in the NetBox UI.

1. Navigate to IPAM → VRFs to view the VRFs created for each IPAM scope and VPC

2. Navigate to IPAM → Prefixes to view the synchronized pool and resource CIDRs

3. Navigate to IPAM → IP Addresses to view single-host addresses such as Elastic IPs

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation

Support

Email support@netboxlabs.com for support.