Technical Information

Cisco Nexus Dashboard to NetBox Object Mapping

The integration reads the Nexus Dashboard 4.x unified Manage API (/api/v1/manage/) and emits twelve NetBox object types through Diode: custom fields, manufacturer, device roles, device types, platforms, sites, VRFs, VLANs, prefixes, interfaces, IP addresses, and devices.

Entities are emitted in dependency order, with devices last, because a device's primary_ip4 requires its interface and IP address to be ingested first.

Object Type Mapping Table

The integration creates no Tenant objects, no Regions, Site Groups, or Locations, and no prefix or IP address roles other than the anycast role on overlay gateway addresses.

Field Mapping Details

Device role mapping

Each switch's switchRole is mapped to a NetBox device role name and color:

A switchRole value that is not in this table is passed through verbatim as the NetBox role name, so a role that Nexus Dashboard adds in a later release still reaches NetBox - it just arrives without a color. A switch with no switchRole at all is assigned the Unknown role (9e9e9e, grey).

Roles are created on demand from the switches actually present in the discovered fabrics. NetBox therefore only receives the roles in use, rather than the full list of roles the integration knows about.

Device attributes

A switch must report a serialNumber, a hostname, and a model to become a NetBox device. A switch missing any of the three is skipped and a warning is logged naming the fabric and the missing values.

Device status is mapped from additionalData.discoveryStatus:

An unrecognized discoveryStatus leaves the NetBox status field unset, and logs a warning naming the value. This is deliberate. Diode applies changes with partial=True, so sending a status on every sync would overwrite a status you set in NetBox yourself - staged, failed, or decommissioning - and a transient Nexus Dashboard state must not flip a healthy device.

Platform naming

A platform is created per distinct switch software version, named {family} {version}. The family comes from the switch's additionalData.platformType field, which reports nx-os on Nexus Dashboard 4.2.1 and is displayed as NX-OS. An unrecognized platformType is used as the family verbatim; an absent one falls back to NX-OS.

The family is prefixed onto the version so that a NetBox instance fed by several Cisco integrations does not end up with bare 10.6(3) platform rows that say nothing about which operating system they belong to.

A switch that reports no softwareVersion is emitted without a platform.

Interface mapping

Interfaces come from the per-switch interface endpoint and are only emitted for switches that became NetBox devices.

The interfaceType value maps to a NetBox interface type as follows:

An interfaceType that is not in this table falls back to other.

Other interface attributes:

• enabled - taken from configData.networkOS.policy.adminState (a boolean) when present. When it is absent, operData.adminStatus is used instead, and the interface is enabled if that value is up. When Nexus Dashboard reports neither field, enabled is left unset so NetBox keeps its own default rather than the interface being asserted administratively down.
• mtu - taken from operData.mtu, and only when it is an integer. The configData.networkOS.policy.mtu field is not used, because it reports a symbolic value such as jumbo on ethernet interfaces rather than a number.
• description - taken from configData.networkOS.policy.description. An empty description is omitted rather than written as an empty string.

An interface with no interfaceName is skipped.

Route distinguisher scheme

Each VRF is emitted with a route distinguisher of the form {fabric}:{vrfId}, for example evpn-lab:150001.

The fabric name is part of the RD because Nexus Dashboard allocates vrfId from a per-fabric segment pool, so two fabrics routinely hold different VRFs under the same ID. Diode matches ipam.vrf on rd whenever it is set, so a fabric-independent RD would merge those distinct VRFs into a single NetBox object.

NetBox limits VRF.rd to 21 characters. When the fabric name and VRF ID together exceed that limit, the fabric name is truncated and a ~ plus the first 8 hexadecimal characters of its SHA-256 digest are appended in its place, so the result still fits. A fabric named a-very-long-fabric-name holding VRF ID 150001 yields the RD a-ver~70bcbb17:150001. The digest keeps the result unique and stable across runs, and the surviving prefix keeps the RD readable in the NetBox VRF list.

A VRF with no vrfName, or no vrfId, is skipped. VRFs are deduplicated by RD.

VLAN mapping

Overlay networks become NetBox VLANs. A network's vlanId must be an integer in the valid VLAN range of 1 to 4094; anything else is skipped and logged.

The VLAN name is resolved in order of preference from displayName, then networkName, then a generated VLAN{vid} fallback. The network's networkId - the VXLAN VNI, or segment ID - is recorded in the nd_segment_id custom field.

VLANs are scoped to the fabric's site, so the same VLAN ID in two fabrics produces two distinct NetBox VLANs.

Prefix derivation

A prefix is derived from each overlay network's l3Data.gatewayIpv4Address. The gateway address is parsed as an IP interface and the containing network becomes the prefix - for example a gateway of 10.10.10.1/24 yields the prefix 10.10.10.0/24.

• A gateway address that does not parse is skipped and logged.
• A gateway with a /32 or /128 mask is skipped, since a host address is not a prefix.
• The prefix is scoped to the fabric's site, so the same CIDR in two fabrics produces two distinct NetBox prefixes rather than one attributed to whichever fabric was read first.
• The prefix is assigned to a VRF when the network's vrfName matches a VRF in the same fabric. When it does not resolve, the prefix is emitted without a VRF.
• Prefix status is set to active.

An overlay network with no gateway address produces no prefix.

IP address handling

The integration emits three categories of IP address.

Infrastructure IP addresses come from operData.ipAddress on interfaces whose interfaceType is loopback, management, or ethernet, and are assigned to their interface in NetBox.

SVI and NVE interfaces are deliberately excluded from this category. On Nexus Dashboard 4.2.1, operData.ipAddress reports the switch's management address on interfaces that have no address of their own, which includes every SVI. Admitting them would make a switch's management address look shared across several interfaces, and strip both its interface assignment and the device's primary IP. Real overlay gateway addresses reach NetBox through the anycast category instead.

IPv6 link-local addresses (fe80::/10) are skipped. An address that does not parse is skipped and logged.

Anycast gateway IP addresses come from each overlay network's l3Data.gatewayIpv4Address and are emitted with the NetBox anycast role. They carry no interface assignment, because the same address is configured on the SVI of every leaf switch in the fabric. They are assigned to the network's VRF when it resolves in the same fabric, and deduplicated on the address and RD together.

The fabric management address is emitted from a switch's fabricManagementIp field only as a primary IP fallback, described below.

Addresses shared across interfaces

When the same address appears on more than one interface, it is emitted without an interface assignment and a warning is logged naming the address and the number of interfaces. Emitting it once per interface would create several NetBox objects for a single host address.

This is a real condition rather than a defensive edge case. On Nexus Dashboard 4.2.1, a switch's unnumbered layer-3 ethernet ports echo its management address in operData.ipAddress - in the validation fabric, one spine reported the same address on mgmt0 and 64 ethernet ports.

Primary IP resolution

A device's primary_ip4 is resolved in this order:

1. The management interface address. The first interface with interfaceType of management that reports an IPv4 operData.ipAddress supplies the primary IP, assigned to that interface. A non-IPv4 address is skipped for this purpose, and an address that is shared across interfaces is not used - a warning is logged instead.
2. fabricManagementIp. When interface data supplied no primary IP - either because the switch has no usable management interface address, or because the cluster runs 4.1.x and has no interface endpoint at all - the switch's fabricManagementIp is emitted as a /32 with no interface assignment and set as the primary IP. The field carries no prefix length, which is why it becomes a /32.

The fallback yields to interface data whenever the same host address already reached NetBox from an interface, compared without its mask so that a maskless 10.10.11.101 is not re-emitted as a /32 alongside an existing 10.10.11.101/21. This means it never resurrects an address that was deliberately left unassigned as shared.

A switch whose ethernet ports echo its management address therefore ends up with no primary_ip4 from either path. One of the four switches in the validation fabric is affected. See Known Limitations.

Custom Fields

The integration creates the following custom fields. Both are created during bootstrap and set to read-only in the NetBox UI.

A value that is absent, or that is not convertible to an integer, is omitted rather than written as a zero.

Configuration Parameters

config Parameters

Configure these under the config key in the policy definition.

* Provide either ND_USERNAME and ND_PASSWORD, or ND_API_KEY and ND_API_USERNAME. Each pair must be complete. API key authentication takes precedence when both pairs are supplied.

Boolean values accept the usual YAML forms - true, false, and equivalent string and integer representations.

A config value that is present but blank is treated the same as absent, so a ${...} reference that resolves to an empty string does not pass the credential check as a supplied value.

Do not write secrets into the policy file in plain text. When the policy loads, a config value that is exactly a ${...} reference is replaced with the matching environment variable from the agent process. Orb Agent can additionally resolve secrets from an external store such as HashiCorp Vault, configured separately under orb.secrets_manager and referenced with its own ${vault://...} form.

scope Parameters

Scope parameters limit which fabrics are ingested. Configure them under a scope key in the policy definition, separate from config.

Example scope block:

scope:
  fabrics:
    - evpn-lab
    - dc1-fabric

Filtering behavior:

• Names are matched exactly against each fabric's name field, so matching is case-sensitive. Surrounding whitespace in a configured name is trimmed.
• An empty list, a list containing *, and an omitted key all mean "ingest every fabric".
• A value that is not a list disables filtering rather than failing the run, and logs a warning naming the type received.
• A configured fabric name that matches nothing simply contributes no data. The log line reporting how many fabrics were fetched and how many survived filtering is where a typo shows up.
• scope.fabrics is ignored in bootstrap mode, since no API calls are made.

Authentication

The integration supports two authentication methods against the Manage API:

• JWT (username and password) - the integration calls POST /api/v1/infra/login with the username, password, and login domain, and uses the returned jwttoken value as an Authorization: Bearer credential. The token has a 20-minute lifetime. If a subsequent call returns 401, the integration re-authenticates once with the stored credentials and retries that call, so a long run spanning the token lifetime does not fail partway through. A login that succeeds but returns no token is treated as an error.
• API key - the X-Nd-Apikey and X-Nd-Username headers are set on the session. Both are required together. No login call is made and there is no token to refresh.

API key authentication takes precedence when both credential pairs are supplied.

Credentials are validated before any request is made. A missing ND_HOST, or an incomplete credential pair, ends the run with a configuration error rather than a network failure.

Login domains

ND_LOGIN_DOMAIN carries the login domain name as listed by GET /logindomains on your cluster, and the value is case-sensitive. It is how you authenticate against a remote domain - LDAP, RADIUS, or TACACS - rather than the local one.

When the key is omitted, the integration sends the server-side DefaultAuth alias rather than omitting the field, so Nexus Dashboard authenticates against its configured default login domain. The field is always sent because Nexus Dashboard 4.2 returns a 500 when it is absent entirely, despite the API documentation stating that omission falls back to the default.

TLS verification

By default the Nexus Dashboard server certificate is validated against the agent host's trust store. For a certificate signed by an internal or private CA, add the CA chain to that trust store and leave SKIP_SSL unset.

SKIP_SSL: true disables verification for every request on the session, including the login request that carries your password. The run is then vulnerable to a machine-in-the-middle attack. Use it only on trusted networks and for initial testing.

Tags

The integration applies the following tags to the objects it ingests:

The per-cluster nd-{host} tag is not applied in bootstrap mode, and is never applied to the Cisco manufacturer, which is static content shared with every other Cisco integration.

When running multiple agents against different Nexus Dashboard clusters, each cluster's ND_HOST produces a distinct tag, so its objects remain identifiable in NetBox.

API and Behavior Notes

• Pagination. List endpoints wrap their payload as {<key>: [...], "meta": {...}}. The integration follows meta.links.next until it is absent, so a large fabric is read to completion rather than ingesting only its first page. A server that echoes the same next link is guarded against with a visited-URL set. When the number of records fetched does not match the total the API reports, a warning is logged naming both counts.
• Retries. GET and POST requests are retried up to 3 times with a 0.5-second backoff factor on HTTP 429, 500, 502, 503, and 504. Every request has a 30-second timeout.
• URL encoding. Fabric names and switch serial numbers are URL-encoded before being placed in a request path, so a fabric name containing a slash or a space is read correctly.
• Per-fabric resilience. A failure fetching switches, interfaces, VRFs, or overlay networks for one fabric is logged as a warning and that collection is treated as empty; the run continues with the remaining fabrics and data types. A failure fetching the fabric list aborts the run, because it cannot be distinguished from a cluster with no fabrics.
• Interface fetch failures. A failure fetching one switch's interfaces is logged and that switch contributes no interfaces. Its device, device type, platform, and role are unaffected.

Bootstrap Mode

When BOOTSTRAP is set to true, the integration creates the following without connecting to Nexus Dashboard:

• Tags: cisco, nexus-dashboard, discovered
• Custom fields: nd_switch_db_id, nd_segment_id
• The Cisco manufacturer

Credentials are not required in bootstrap mode, and scope.fabrics is ignored.

Device roles are not created in bootstrap mode. They are created on a real sync, and only for the roles the discovered switches actually use, so bootstrap does not leave unused roles in NetBox. No site is created either, since sites are derived from the fabrics themselves.

Use bootstrap mode on the initial setup only, then set it to false for all subsequent runs.

Sync Behavior

• Direction: One-way, Nexus Dashboard to NetBox. Nothing is written back to Nexus Dashboard or to the fabric.
• Object deletion: The integration does not delete NetBox objects. A switch removed from a fabric is not automatically decommissioned in NetBox.
• Idempotency: Subsequent runs update existing NetBox objects rather than creating duplicates. The Diode SDK handles conflict resolution.
• Partial updates: Diode applies changes with partial=True, so fields the integration does not set are left as they are in NetBox.
• Scope: All fabrics on the cluster are synced by default. Optional fabric scope filtering is available (see scope Parameters).
• Multi-cluster: Each agent instance is configured for a single Nexus Dashboard cluster. Run a separate agent instance per cluster; each is distinguished in NetBox by its nd-{host} tag.

Known Limitations

• Device scope is switches only. Only fabric switches are modeled as NetBox devices. The Nexus Dashboard controller and cluster nodes themselves are not emitted.
• Interfaces require Nexus Dashboard 4.2.x. The per-switch interface endpoint (.../switches/{serial}/interfaces) is absent on 4.1.x, so interfaces and interface-assigned IP addresses are skipped on that version. Everything else - fabrics, sites, switches, devices, device types, platforms, roles, VRFs, VLANs, and prefixes - still syncs, and device primary_ip4 still works via the fabricManagementIp fallback, emitted as a /32 because the field carries no prefix length. Verified live on Nexus Dashboard 4.2.1.
• A switch can end up without a primary IP. Nexus Dashboard reports a switch's management address in operData.ipAddress for interfaces that have none of their own, which includes SVIs and unnumbered layer-3 ethernet ports. When a switch's ethernet ports echo its management address, that address is genuinely shared across many interfaces, so it is synced without an interface assignment and the device receives no primary_ip4. Emitting one anyway would mean two NetBox objects for the same host address. One of the four switches in the validation fabric is affected.
• Infrastructure IP addresses are not VRF-scoped. Loopback, management, and routed ethernet addresses are emitted without a VRF, so two fabrics reusing the same underlay addressing produce colliding NetBox IP address objects. Overlay data is unaffected: VRFs, prefixes, and anycast gateway addresses are all fabric-scoped through their route distinguisher.
• Legacy APIs are not supported. The integration targets the Nexus Dashboard 4.x unified Manage API only. The per-service NDFC and Nexus Dashboard Orchestrator APIs that 4.x replaced are not read.