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
  • Credential Model
  • Least-Privilege IAM Policy
  • Choose an Authentication Method
  • Credential Rotation
• 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 read-only 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

Credential Model

You run the agent, on your own infrastructure, with credentials you control. NetBox Labs never holds your AWS credentials and never assumes a role in your AWS account, so there is no External ID to configure.

AWS_ROLE_ARN exists for reaching your own accounts: the agent assumes a role you own, in another AWS account you own. That is what makes a hub-and-spoke IPAM layout readable from a single policy.

Least-Privilege IAM Policy

The integration only reads. The six actions below are the complete set it calls, so the identity you give it needs no write, modify, or delete permission anywhere in your account:

{
  "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

Credentials are read from the policy config block. Pick the option that fits where the agent runs. In every case you must also set the AWS region (or regions) through the AWS_VPC_IPAM_REGION config key.

Prefer an instance role or role assumption where you can. Neither leaves a long-lived secret in your agent host's configuration.

When both credential keys are unset, no credentials are passed to boto3 and its standard credential chain applies. Inside AWS that resolves the attached instance or task role; elsewhere it resolves whatever that chain finds in the agent's own environment or AWS config files.

Keep secrets out of the policy file

Write ${AWS_SECRET_ACCESS_KEY} in the policy rather than the secret itself. When the agent loads the policy, a config value that is exactly a ${...} reference is replaced with the matching environment variable from the agent process. The .env file in Step 3 is what supplies those variables.

Two details matter in practice:

• The reference must be the whole value. ${AWS_SECRET_ACCESS_KEY} is substituted; prefix-${AWS_SECRET_ACCESS_KEY} is not.
• An unset variable is not caught as a missing credential. If the environment variable does not exist, the literal text ${AWS_SECRET_ACCESS_KEY} is passed through as the credential and the run fails when AWS rejects it. See FAQ & Troubleshooting for that message.

Orb Agent can also resolve secrets from an external secret store, including HashiCorp Vault, configured under a separate orb.secrets_manager section of the agent config. Those references use a different form (${vault://...}) - see the Orb Agent documentation for setup.

Credential Rotation

• An instance or task role rotates automatically. There is nothing for you to do.
• AWS_ROLE_ARN issues short-lived credentials on every run, and the role is re-assumed once per region. Revoking or editing the role takes effect on the next run.
• A long-term IAM user key is the only option you rotate yourself. Create the replacement key, update the environment variable that the ${...} reference reads from, restart the agent, then deactivate and delete the old key in AWS. Because the policy references the secret rather than embedding it, rotation never means editing the policy file.

Nothing about the credential is stored in NetBox, so rotation needs no NetBox-side change.

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_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}          # Omit both key lines to use an attached instance/task role
          AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}  # Resolved from the agent environment, never written in plain text
          # 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 another AWS account you own (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. The role is re-assumed once per region, so credentials stay fresh on a long multi-region run. Optionally set AWS_ROLE_SESSION_NAME; it defaults to netbox-orb-agent-aws-vpc-ipam and surfaces in the target account's CloudTrail.

Both accounts are yours, and both sides of the trust relationship are yours to configure, so no External ID is involved. A failure to assume the role aborts the whole run rather than skipping a region, because the role and its trust policy apply to every region equally.

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. These are the values that the ${...} references in your policy config resolve to. Skip this step if the agent uses an attached instance or task role:

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"

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

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: Successfully ingested 33 entities in 1 chunks"}
{"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.