Netbox

---
name: netbox
description: "Expert coverage of NetBox IPAM and DCIM across all versions: data modeling (sites, devices, interfaces, IPs, VLANs, cables), REST and GraphQL APIs, source of truth patterns, Ansible inventory integration, Terraform integration, custom fields, and plugin ecosystem. Use for \"NetBox\", \"IPAM\", \"DCIM\", \"pynetbox\", \"nb_inventory\", \"NetBox API\", \"NetBox custom fields\", \"NetBox plugin\", \"source of truth NetBox\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `network-automation` skill. Do NOT use for general infrastructure-as-code source-of-truth or config-management tool selection across the stack -- that's the `config-mgmt` skill (in the `devops` plugin)."
license: MIT
---

# NetBox

This skill covers NetBox IPAM (IP Address Management) and DCIM (Data Center Infrastructure Management) across all versions. Areas of expertise include:

- NetBox data model: sites, racks, devices, interfaces, IP addresses, prefixes, VLANs, VRFs, cables, circuits
- REST API for CRUD operations and bulk management
- GraphQL API for efficient data queries
- Source of truth patterns: NetBox as authoritative inventory for Ansible and Terraform
- Ansible integration via `netbox.netbox.nb_inventory` dynamic inventory plugin
- Terraform integration via HTTP data source and jsondecode
- pynetbox Python client for automation scripts
- Custom fields, custom validators, and plugin ecosystem
- IPAM design: prefix hierarchy, VRF management, VLAN groups, ASN tracking

When a question is version-specific, consult the matching `references/versions/` file. When the version is unknown, provide general guidance applicable to recent NetBox releases.

## How to Approach Tasks

1. **Classify** the request:
   - **Data modeling** -- Load `references/architecture.md` for data model, relationships, and design patterns
   - **API usage** -- Apply REST or GraphQL patterns with authentication and filtering
   - **Integration** -- Load `references/best-practices.md` for Ansible inventory, Terraform data, and automation patterns
   - **IPAM design** -- Apply prefix hierarchy, VRF, and VLAN group design principles
   - **Administration** -- Custom fields, validators, plugins, user management

2. **Identify the use case** -- Is NetBox being used as inventory source (read), data store (write), or both? This determines API patterns and integration approach.

3. **Load context** -- Read the relevant reference file for deep knowledge.

4. **Analyze** -- Apply NetBox-specific reasoning. NetBox is a data store, not an automation engine -- it describes what should exist, not how to configure it.

5. **Recommend** -- Provide API examples (REST endpoints, pynetbox code), data model design, and integration patterns.

6. **Verify** -- Suggest validation steps (API queries to verify data, inventory plugin testing, data quality checks).

## Core Data Model

### Organizational Hierarchy

```
Region
  └── Site Group
        └── Site
              └── Location (building, floor, room)
                    └── Rack
                          └── Device (position in rack)
                                └── Interface
                                      └── IP Address
                                      └── Cable (to another interface)
```

### DCIM (Physical Infrastructure)

**Devices:**
- Network devices (routers, switches, firewalls, APs, servers)
- Each device has a Device Type (manufacturer + model) that defines its physical characteristics
- Device Type templates pre-define interfaces, power ports, console ports

**Interfaces:**
- Physical interfaces (Ethernet, SFP, console)
- Virtual interfaces (VLAN interfaces, loopbacks, port-channels)
- Link type, speed, MAC address, MTU
- Assigned to cables for physical connectivity tracking

**Cables:**
- Physical connections between interfaces
- Support for patch panels (intermediate termination)
- Cable trace: follow the complete path from source to destination

**Racks:**
- Physical rack layout with U-position tracking
- Front and rear device placement
- Power distribution (power panels, feeds, outlets)

### IPAM (IP Address Management)

**Prefixes:**
- IP blocks organized hierarchically (10.0.0.0/8 > 10.1.0.0/16 > 10.1.1.0/24)
- Assigned to VRFs for routing isolation
- Roles: classify prefix purpose (infrastructure, loopback, management, user)
- Status: active, reserved, deprecated, container

**IP Addresses:**
- Individual IPs with status (active, reserved, deprecated, DHCP, SLAAC)
- Assigned to device interfaces (or VM interfaces)
- Primary IP: the management IP for a device (used for SSH/API access)

**VLANs:**
- VLAN IDs with name, site, group, status
- VLAN groups: scope VLANs within a site or location
- Linked to prefixes (VLAN 10 = 10.1.1.0/24)

**VRFs:**
- Virtual routing instances with route distinguisher
- Import/export targets for VRF leaking
- Prefixes assigned to VRFs for isolation

**ASNs:**
- BGP Autonomous System numbers
- Linked to sites, devices, or providers

**FHRP Groups:**
- VRRP, HSRP, GLBP virtual IP tracking
- Associated with interfaces and IP addresses

### Circuits

- **Providers**: ISPs, telcos, cloud providers
- **Circuit types**: Internet, MPLS, P2P, dark fiber
- **Circuits**: Individual circuits with provider, type, commit rate
- **Terminations**: Where circuits connect to sites/devices

### Tenancy

- **Tenants**: Organizations, business units, customers
- **Tenant Groups**: Hierarchical grouping of tenants
- Most objects can be assigned to a tenant for multi-tenancy tracking

## REST API

### Authentication
All API requests require a token:
```
Authorization: Token <api-token>
```

Create tokens via NetBox UI: Admin > API Tokens

### Common Operations

**List devices (with filtering):**
```
GET /api/dcim/devices/?site=NYC&status=active&role=router
```

**Get specific device:**
```
GET /api/dcim/devices/42/
```

**Create device:**
```
POST /api/dcim/devices/
Content-Type: application/json

{
  "name": "core-rtr-01",
  "device_type": 5,
  "role": 1,
  "site": 1,
  "status": "active"
}
```

**Update device:**
```
PATCH /api/dcim/devices/42/
Content-Type: application/json

{
  "description": "Core router - NYC datacenter"
}
```

**Get available IPs from prefix:**
```
GET /api/ipam/prefixes/15/available-ips/?prefix_length=30
```

**Bulk create:**
```
POST /api/dcim/devices/
Content-Type: application/json

[
  {"name": "sw-01", "device_type": 3, "role": 2, "site": 1, "status": "active"},
  {"name": "sw-02", "device_type": 3, "role": 2, "site": 1, "status": "active"}
]
```

### Pagination
```
GET /api/dcim/devices/?limit=50&offset=100
```
Response includes `count`, `next`, `previous` for navigation.

### Filtering Reference
Most list endpoints support:
- Exact match: `?name=core-rtr-01`
- Contains: `?name__ic=core` (case-insensitive contains)
- Multiple values: `?site=NYC&site=LAX`
- Nested lookups: `?site__region__name=US-East`
- Boolean: `?has_primary_ip=true`

## GraphQL API

Endpoint: `/graphql/`

### Query Examples

**Devices with interfaces and IPs:**
```graphql
{
  device_list(site_id: [1], status: "active") {
    name
    device_role { name }
    primary_ip4 { address }
    interfaces {
      name
      type
      ip_addresses {
        address
      }
    }
  }
}
```

**Filter components by location (v4.5+):**
```graphql
{
  interface_list(device__rack_id: [5]) {
    name
    type
    speed
    device { name }
  }
}
```

GraphQL is read-only. Use REST API for write operations.

### Cursor-Based Pagination (v4.5.2+)
For large datasets, cursor-based pagination is more efficient than offset:
```graphql
{
  device_list(first: 50, after: "cursor_value") {
    edges {
      node { name }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## pynetbox Python Client

```python
import pynetbox

nb = pynetbox.api("https://netbox.example.com", token="your-token")

# Query devices
devices = nb.dcim.devices.filter(site="nyc", status="active")
for device in devices:
    print(f"{device.name}: {device.primary_ip4}")

# Create device
new_device = nb.dcim.devices.create(
    name="core-rtr-03",
    device_type=5,
    role=1,
    site=1,
    status="active"
)

# Update device
device = nb.dcim.devices.get(name="core-rtr-03")
device.description = "Updated description"
device.save()

# Get available IPs
prefix = nb.ipam.prefixes.get(prefix="10.1.1.0/24")
available = prefix.available_ips.list()

# Create IP and assign to interface
ip = nb.ipam.ip_addresses.create(
    address="10.1.1.10/24",
    status="active",
    assigned_object_type="dcim.interface",
    assigned_object_id=42
)
```

## Ansible Integration

### Dynamic Inventory Plugin
```yaml
# inventory/netbox.yml
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.example.com
token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
config_context: true
group_by:
  - device_roles
  - sites
  - platforms
  - regions
query_filters:
  - status: active
  - has_primary_ip: true
compose:
  ansible_host: primary_ip4.address | ansible.utils.ipaddr('address')
  ansible_network_os: platform.napalm_driver
```

### Using NetBox Data in Playbooks
```yaml
- name: Query NetBox for device interfaces
  uri:
    url: "https://netbox.example.com/api/dcim/interfaces/?device={{ inventory_hostname }}"
    headers:
      Authorization: "Token {{ netbox_token }}"
  register: nb_interfaces

- name: Configure interfaces from NetBox data
  cisco.ios.ios_interfaces:
    config: "{{ nb_interfaces.json.results | map(attribute='name') | ... }}"
    state: merged
```

## Common Pitfalls

1. **Treating NetBox as an automation engine** -- NetBox is a data store. It describes the desired state of the network but does not push configuration. Use Ansible, Terraform, or scripts to act on NetBox data.

2. **Stale data** -- NetBox is only useful if data is accurate. Build automation to keep NetBox updated (auto-populate from device discovery, reconciliation scripts, pre/post change updates).

3. **Over-using custom fields** -- Custom fields are powerful but can sprawl. Plan custom fields carefully; document their purpose; review unused fields quarterly.

4. **Ignoring device type templates** -- Device types define interfaces and ports. Creating devices without proper device types means interfaces must be manually added. Invest time in accurate device type templates.

5. **Flat prefix hierarchy** -- Organize prefixes hierarchically (container > aggregate > assignment). Flat prefix lists become unmanageable at scale.

6. **No primary IP set** -- The `primary_ip4` field determines the management IP used by Ansible inventory. Devices without a primary IP will not appear in dynamic inventory.

7. **Manual-only population** -- Manually entering hundreds of devices, interfaces, and IPs does not scale. Use scripts (pynetbox) and bulk import (CSV/API) for initial population.

8. **No data ownership** -- Every NetBox data domain (IPAM, DCIM, circuits) should have an owner responsible for accuracy. Unowned data decays.

## Version-Specific Guidance

| Version | Reference | What's version-specific |
|---|---|---|
| 4.5 | `references/versions/4.5.md` | NetBox v4.5 specific features, API changes, migration guidance |

## Reference Files

Load these when you need deep knowledge:
- `references/architecture.md` -- Data model (sites, racks, devices, interfaces, IPs, VLANs, cables), REST/GraphQL API, plugins. Read for "how does X work" architecture questions.
- `references/best-practices.md` -- IPAM design, naming conventions, custom fields, integrations (Ansible inventory, Terraform). Read for design and operations questions.