📌 Version note: This document covers the current state of the NetBox integration. Expanded coverage (IP addresses, inventory devices, Network Site metadata sync) is planned. Check back for updates.
Overview
The NetBox integration allows network operators to use NetBox as the authoritative source of truth for IP prefix (IP Block) management. Rather than manually entering IP blocks into gaiia, prefixes are defined in NetBox and automatically pushed to the corresponding Network Sites in gaiia.
What the integration does today:
- Syncs IP prefixes ("IP Blocks" in gaiia) from NetBox to gaiia Network Sites.
- Keeps IP Blocks in sync in real-time as prefixes are created, updated, or deleted in NetBox.
- Compatible with NetBox v4.1 and v4.2+.
Not yet supported (coming soon):
- IP Address sync.
- Inventory device sync.
- Network Site metadata sync (names, addresses, coordinates) from NetBox.
- Automatic writes from gaiia back to NetBox.
How it works
The integration operates in two modes: real-time webhook sync and manual full sync.
Real-time sync (webhooks)
When you enable prefix synchronization, gaiia registers a webhook and event rule in your NetBox instance. NetBox fires this webhook whenever:
- A Prefix is created, updated, or deleted.
- A Site is deleted.
When gaiia receives a webhook event, it:
- Identifies the NetBox site associated with the prefix (via
site.nameon NetBox v4.1, orscope.nameon v4.2+). - Finds the matching gaiia Network Site by name.
- Creates, updates, or removes the IP Block on that Network Site accordingly.
⚠️ Critical: gaiia matches NetBox sites to gaiia Network Sites by exact name (case-sensitive). A prefix assigned to a site named Springfield-POP-1 in NetBox will only sync if a Network Site named Springfield-POP-1 exists in gaiia.
Manual full sync
You can trigger a full sync at any time from the integration settings. This fetches all prefixes from NetBox and creates any missing IP Blocks in gaiia. It is additive — it does not remove IP Blocks that were manually created in gaiia or that no longer exist in NetBox.
Full sync is the recommended first step after initial configuration to import your existing prefix data.
Field mapping
The following NetBox prefix fields are mapped to gaiia IP Block fields:
| NetBox Field | gaiia Field | Notes |
|---|---|---|
prefix |
IP Block (CIDR text) | e.g., 192.168.1.0/24
|
description |
IP Block description | Free-text. |
site.name (v4.1) / scope.name (v4.2+)
|
Network Site | Matched by name to determine where to create the block. |
role |
— (filter only) | Used to filter which prefixes are synced; not stored in gaiia. |
Note on NetBox v4.2: NetBox v4.2 replaced the site field on prefixes with a polymorphic scope field. gaiia detects the version automatically and handles both — no configuration change is required if you upgrade NetBox.
Configuration
Prerequisites
Before configuring the integration in gaiia, ensure you have:
- A running NetBox instance (v4.1 or v4.2+) that is network-accessible from gaiia's servers.
- A NetBox API token with the permissions described in the API Token Permissions section below.
- Network Sites already created in gaiia, with names that match your NetBox site names exactly.
Step 1: Install the integration
Navigate to Settings → Integrations in gaiia. Find NetBox in the integrations catalog and click Install.
Step 2: Add a NetBox instance
Click Add Instance and fill in the following:
| Field | Description |
|---|---|
| Instance name | A friendly label for this connection (e.g., Production NetBox). Must be unique across your instances. Defaults to Default for the first instance. |
| NetBox API key | Your NetBox API authentication token. When updating an existing instance, leave blank to keep the current key. |
| Base URL | The full URL to your NetBox API endpoint, e.g., https://netbox.example.com/api. |
You can add multiple instances. Each instance is independently configured with its own credentials, webhook, and sync settings.
Step 3: Configure prefix synchronization
After adding an instance, expand Prefix Synchronization to configure sync behavior:
| Setting | Description |
|---|---|
| Enable Sync | Enables real-time webhook-based sync for this instance. |
| Filter by IPAM Role (optional) | Restricts sync to prefixes assigned to specific NetBox IPAM roles. Leave empty to sync all prefixes. |
Step 4: Webhook registration (automatic)
When you enable Prefix Synchronization and save, gaiia automatically registers a webhook in your NetBox instance. This webhook points to the Import Network Site Prefixes workflow in gaiia, with the instance's ID appended as a query parameter so gaiia knows which NetBox instance is the source of each event.
You can verify the webhook was created by checking Extras → Webhooks and Extras → Event Rules in NetBox.
The webhook fires — and the Import Network Site Prefixes workflow runs — whenever NetBox emits an event for the following object types:
-
Prefix —
created,updated, ordeleted. -
Site —
deletedonly.
What the workflow does for each event:
- Prefix created: Adds an IP Block to the matching gaiia Network Site (matched by site name). If no matching Network Site is found, the event is skipped silently.
- Prefix updated: Handles three sub-cases — if the CIDR or description changed, the existing IP Block is updated in place; if the prefix moved to a different site, the old IP Block is removed and a new one created on the new site; if the prefix moved away from a site entirely, the old IP Block is removed.
- Prefix deleted: Removes the corresponding IP Block from gaiia — but only if that block was originally created by this integration. Manually-created IP Blocks with the same CIDR are left untouched.
- Site deleted: Removes all integration-created IP Blocks from the corresponding gaiia Network Site.
If prefix synchronization is disabled for an instance, incoming webhook events for that instance are rejected.
Disabling prefix synchronization and saving will automatically remove the webhook and event rule from NetBox.
⚠️ Do not manually delete the webhook or event rule in NetBox. Always use the integration settings in gaiia to manage the connection lifecycle.
Step 5: Run initial full sync
Once the webhook is registered, run a full sync to import your existing prefixes:
- Navigate to Workflows in the left sidebar.
- Find Import Network Site Prefixes - Full Sync and run it, providing your instance name (e.g.
Default) as input. - gaiia will paginate through all prefixes from NetBox and create IP Blocks on matching Network Sites.
- The full sync is safe to run multiple times — it skips prefixes that already exist as IP Blocks.
Note: The full sync will fail if prefix synchronization is not currently enabled for the instance.
Workflows
The NetBox integration creates a set of workflows visible in your tenant at Workflows (/workflows/overview). These can be inspected, and some can be run manually.
For most users, the only workflow you’ll interact with directly is Import Network Site Prefixes - Full Sync — and ideally only once, during initial setup. All other workflows either run automatically in the background or are used internally by the integration.
| Workflow Name | Trigger | Description |
|---|---|---|
| Import Network Site Prefixes | Webhook | The core real-time sync handler. Invoked automatically by the NetBox event rule when a prefix or site changes. Creates, updates, or removes the corresponding IP Block in gaiia. Not run manually. |
| Import Network Site Prefixes - Full Sync | Manual | Fetches all prefixes from NetBox and creates any missing IP Blocks in gaiia. Run this once after initial setup to import existing prefixes. Requires instanceName as input (e.g. Default). Safe to re-run. |
| Create NetBox Prefix Update Webhook | Manual | Registers the webhook and event rule in NetBox so gaiia receives real-time prefix change events. Also creates the gaiia_tenant_id and gaiia_instance_id custom fields in NetBox. Runs automatically in the background when prefix synchronization is enabled and saved. |
| Remove NetBox Prefix Update Webhook | Manual | Removes the webhook, event rule, and tracking custom fields from NetBox. Runs automatically in the background when prefix synchronization is disabled and saved. |
| Get IPAM Roles from NetBox | Manual | Fetches available IPAM roles from a NetBox instance. Used internally to populate the IPAM role filter dropdown in the integration settings. |
| Get Config for NetBox | Manual | Returns the current configuration for all registered NetBox instances. Used internally by the integration settings UI. |
| Get NetBox prefix synchronization settings | Manual | Internal node used by the sync workflows to retrieve prefix synchronization settings for a given instance. Not intended for direct use. |
| NetBox HTTP Request | Manual | Internal node used by the sync workflows to make authenticated HTTP requests to the NetBox API. |
Designing your NetBox implementation
If you're setting up NetBox alongside gaiia for the first time, this section covers the key design decisions and constraints you need to plan for.
Site naming conventions
gaiia links NetBox prefixes to Network Sites by exact name match. This is the single most important design constraint.
Best practices:
- Establish a site naming convention before you create sites in either system.
- Names are case-sensitive —
Chicago-HQandchicago-hqare treated as different sites. - Keep names stable — renaming a site in NetBox or gaiia will break the association for all linked prefixes.
- Avoid special characters that may behave differently across systems.
Scoping prefixes to sites
Only prefixes that are assigned to a site in NetBox will sync to gaiia. Global (unscoped) prefixes are not imported.
When creating prefixes in NetBox:
- Always set the Site field (v4.1) or Scope field (v4.2+, using Site as scope type).
- Prefixes scoped to VRFs, Regions, or other non-Site scope types are not currently synced.
Using IPAM roles for selective sync
If you manage different categories of prefixes in NetBox (e.g., infrastructure, customer-facing, OOB management), IPAM roles give you control over which ones flow into gaiia.
Example role structure:
-
Infrastructure— core network blocks, not synced to gaiia. -
Customer Access— access-layer prefixes, synced to gaiia. -
OOB Management— out-of-band management, not synced to gaiia.
In gaiia's prefix sync settings, select only the roles you want synced. Prefixes with no role assigned are always included unless a role filter is active.
Connecting multiple NetBox instances
gaiia supports multiple simultaneous NetBox connections. Each instance:
- Has its own API key and base URL.
- Gets its own webhook and event rule registered in its respective NetBox instance.
- Can have independent IPAM role filters.
- Syncs to the same set of gaiia Network Sites (matched by name).
Common scenarios for multiple instances:
- Production and staging/test NetBox environments.
- Separate NetBox instances per geographic region.
- An acquired network operator with their own existing NetBox.
API token permissions
The API token you provide requires the following minimum permissions in NetBox:
| Object | Permissions Needed | Reason |
|---|---|---|
ipam > prefix |
View | Read prefixes during sync. |
ipam > role |
View | Populate the IPAM role filter dropdown. |
dcim > site |
View | Look up site details during sync. |
extras > webhook |
View, Add, Delete | Create and remove the gaiia webhook. |
extras > event rule |
View, Add, Delete | Create and remove the event rule. |
extras > custom field |
View, Add | Create the gaiia_tenant_id and gaiia_instance_id tracking fields. |
Create a dedicated API token for the gaiia integration rather than reusing a personal token — this makes it easier to rotate credentials without disrupting other integrations.
Network accessibility
gaiia's servers must be able to reach your NetBox API over HTTPS. Conversely, your NetBox instance must be able to make outbound HTTPS calls to gaiia's inbound webhook URL. If NetBox is hosted on a private network behind a firewall, you will need to:
- Allow inbound HTTPS from gaiia's IP ranges (see gaiia Cloud Access and Firewall Rules for the current IP list).
- Allow outbound HTTPS from your NetBox server to gaiia's domain.
Limitations
- Prefixes only: Only IP prefixes (shown as IP Blocks in gaiia) are synced in the current version. Network Site metadata, IP addresses, and inventory devices are not synced yet.
- NetBox is read-only from gaiia: Changes made in gaiia are not written back to NetBox. NetBox is the source of truth.
- Site matching by name only: There is no external ID or UUID-based matching. If a site is renamed in either system, the association breaks.
- Full sync is additive: Full sync creates missing blocks but does not remove stale ones. Real-time webhooks handle deletes; if the webhook was down during a deletion, the corresponding IP Block must be removed manually in gaiia.
- Full sync is manually triggered: There is no scheduled automatic full sync at this time.
- Unscoped prefixes are not synced: Prefixes must be assigned to a Site (or Site-scoped Scope) in NetBox to be imported.
Troubleshooting
Prefixes aren't appearing in gaiia after full sync
- Verify the NetBox site name exactly matches the gaiia Network Site name, including capitalization.
- Confirm each prefix is assigned to a site in NetBox — global prefixes are skipped.
- If using IPAM role filtering, confirm the prefixes have the correct role assigned in NetBox.
New prefixes aren't syncing in real-time
- Verify gaiia's inbound webhook URL is reachable from your NetBox server (outbound firewall rules).
- Confirm prefix synchronization is enabled for the relevant instance in gaiia's integration settings.
Sync stopped working after upgrading NetBox from v4.1 to v4.2
- The
sitefield on prefixes changed toscopein NetBox v4.2 — gaiia handles this automatically. - Run a full sync after upgrading to catch any prefixes where the site association may have changed during migration.