Technical Information

Arista CloudVision to NetBox Object Mapping

This page describes how CloudVision data is mapped to NetBox objects by the integration.

Data flows in one direction only, from CloudVision to NetBox. The integration never writes to CloudVision, and it does not push NetBox data into CloudVision.

The integration reads three CloudVision gRPC APIs:

• arista.inventory.v1 (DeviceService.GetAll) - the managed device inventory
• arista.tag.v2 (TagAssignmentService.GetAll) - device system tag assignments from the mainline workspace
• compliancecheck (Compliance.GetConfig, RUNNING_CONFIG) - each device's EOS running configuration, fetched one device at a time

The inventory and tag streams are read to their INITIAL_SYNC_COMPLETE marker, giving a point-in-time snapshot without blocking on the live-update stream that follows.

Device-level objects (devices, device types, platforms, sites, roles, and MAC addresses) come from the inventory and tag APIs. Layer-3 objects (interfaces, VLANs, VRFs, prefixes, and IP addresses) are parsed from each device's EOS running configuration. CloudVision has no structured API for layer-3 data, so the integration reads the same configuration text an operator sees from show running-config and extracts the directives listed in Running configuration parsing.

Object Type Mapping Table

Device Mapping

Device type resolution

CloudVision does not always report a hardware model. Access points and third-party devices managed by CloudVision commonly arrive with no model, and the inventory API has no vendor field to identify them. Instead of labeling every such device as an Arista switch, the integration resolves each device type with the first matching rule below:

Device types created by rules 2 to 4 are placeholders. Each carries the description "CloudVision did not report a hardware model for this device." so that it can be told apart from a device type of the same name reported by a vendor.

Notes on these rules:

• Access points get an Unknown manufacturer, even though Arista sells access points. CloudVision does not report the vendor, so the integration does not claim one.
• The topology_type values in rule 2 are matched exactly and are case-sensitive. CloudVision's own values mix case, so wlanap matches but WLANAP does not.
• Platforms follow the manufacturer. A device is given an EOS {version} platform only when its device type resolved to the Arista manufacturer. Devices under the Unknown manufacturer have no platform.
• The Unknown manufacturer is created on demand, the first time a device resolves to it. Bootstrap mode does not create it.

Device role mapping

The device role is resolved from the topology_type CloudVision system tag. All roles below are created on every run; each device is then assigned the role matching its topology_type tag value. Tag values are matched exactly and are case-sensitive: leaf maps to the Leaf role, but Leaf does not. A device with no topology_type tag, or with a value not listed here, is assigned the fallback role.

Site resolution

Site assignment uses a two-tier fallback per device:

1. The topology_datacenter CloudVision system tag on the device.
2. The SITE_NAME configuration key, defaulting to "CloudVision" when SITE_NAME is not set.

Each site is created on demand as devices are processed. The fallback site is only created when at least one device has no topology_datacenter tag, so a deployment where every device carries a datacenter tag never leaves an unused fallback site in NetBox.

Streaming status

Each device's CloudVision streaming status is mapped from the inventory streaming_status field and stored in the cv_streaming_status custom field on the device:

MAC address handling

The device system_mac_address from the inventory is uppercased and emitted as a MACAddress object assigned to the device's management interface. The same value is also set as the interface primary_mac_address. Devices with no serial number or no system MAC are skipped, as are devices with no management interface in this run.

Running Configuration Parsing

Layer-3 objects are derived by parsing each device's EOS running configuration. The parser recognizes a deliberately small subset of the EOS configuration language and ignores everything else:

A directive the parser does not read is skipped without an error. The data it carries does not appear in NetBox, and the run still reports success. See Known Limitations for constructs that are common in production configurations but not yet parsed.

Interfaces

One Interface is created for each interface stanza in a device's running configuration.

Interface type is derived from the interface name and, for physical ports, the configured speed:

Other interface fields:

• Enabled - false when the stanza contains shutdown, otherwise true.
• Description - from description.
• Speed - from a forced speed directive. Not set for speed auto.
• MTU - from mtu. Not set when the MTU is the Ethernet default of 1500.
• Switchport mode - switchport mode trunk maps to tagged and switchport mode access maps to access. A port with switchport but no mode line is treated as access. A routed (no switchport) Ethernet or Port-Channel interface has its mode cleared, so a port converted from a switchport loses its stale mode and VLANs.
• Untagged VLAN - from switchport access vlan.
• Tagged VLANs - from switchport trunk allowed vlan, only when the mode is tagged. Ranges and lists such as 10,20-25 are expanded. switchport trunk allowed vlan all is not expanded and leaves the tagged VLAN list empty.
• VRF - from vrf forwarding <name> (or vrf <name> on SVIs). An interface with no VRF directive has its VRF cleared. Management interfaces never carry a VRF in NetBox, even when the device places them in one (see Management interfaces and VRFs).

Interfaces only reference VLANs that are declared in a vlan stanza on a device in the same site. A VLAN ID used on a port but never declared is not linked.

cv_interface_type custom field - each interface records an EOS classification:

Management interface naming

When a device's running configuration is read, its management interface is taken from the configuration like any other interface, so the name always matches the device.

When no device's running configuration could be read in a run (for example, because the compliance API is unavailable), the integration creates one management interface per device instead, named from the hardware model:

This fallback interface has type other. A model name cannot reveal how many supervisors a chassis has, so the guess can be wrong for some chassis configurations. A configuration that is later read always takes precedence.

If only some devices' configurations were read, the integration does not guess a name for the devices it missed. Their existing management interface in NetBox is left untouched until a run reads their configuration.

VLANs and VLAN groups

Each vlan <id> stanza creates a VLAN with the configured name, or VLAN{id} when no name is set. VLANs are deduplicated per site: the same VLAN ID on several devices in one site produces a single VLAN. When two devices in a site name the same VLAN differently, the name from the first device in serial-number order is used.

Each site whose devices declare at least one VLAN gets a VLANGroup named after the site and scoped to it, and its VLANs are placed in that group. This lets the same VLAN ID exist independently in different sites. Sites with no VLANs get no VLAN group.

VRFs

Each vrf instance <name> stanza creates a VRF with that name. The route distinguisher (rd) is set to the VRF name, which gives NetBox a stable unique key. VRFs are deduplicated by name across all devices: a VRF with the same name on devices in different sites is treated as one routing domain.

Multi-site VRF separation

Fabrics in different sites commonly reuse the same address ranges for loopbacks and management. In NetBox, addresses and prefixes in the global table (no VRF) are unique, so identical loopbacks in two sites would collapse into one object.

To keep them distinct, when the inventory resolves to more than one site, every global-table IP address and prefix is placed in a synthetic per-site VRF named cv-site-{site}:

• Each synthetic VRF has the description "VRF created for the sake of IP address uniqueness across CloudVision sites."
• Its route distinguisher is derived from the VRF name, in the form 0:<number>. This value is generated by the integration and does not exist in your network.
• A synthetic VRF is created only for a site that has global-table addresses.
• Addresses in named EOS VRFs are not affected and stay in their named VRF.
• Interfaces never carry a cv-site VRF. An interface can therefore show no VRF while its IP address sits in cv-site-{site}. This is expected.

Single-site deployments create no cv-site VRFs.

Management interfaces and VRFs

Management interfaces are held out of their EOS VRF. A Management* interface with a vrf forwarding directive is treated as part of the global routing table, so its address is placed in the global table (or the site's cv-site VRF in multi-site deployments) rather than in a management VRF. Out-of-band management VRFs are a common device convention, not an IP addressing decision.

Prefixes

A Prefix is created for the network containing each interface address (for example, 10.0.0.1/31 produces 10.0.0.0/31). Prefixes are deduplicated by prefix and VRF.

• Host routes (/32, /128) and default routes (/0) are skipped.
• Link-local IPv6 addresses (fe80::/10) are skipped.
• A prefix seen in exactly one site is scoped to that site.
• A prefix seen in more than one site (only possible in a named VRF that spans sites) has no site scope, and any scope previously set on it is cleared.

IP addresses

An IPAddress is created for each interface address, with its prefix length. Addresses are canonicalized, so two devices that write the same IPv6 address differently produce one record.

• Secondary IPv4 addresses (ip address ... secondary) are skipped.
• Link-local IPv6 addresses are skipped.
• Single owner - an address found on exactly one interface is assigned to that interface.
• Shared addresses - an address found on more than one interface in the same routing domain is created once, with no interface assignment. This prevents the assignment from switching between devices on each run. Any assignment previously stored in NetBox is cleared, except on management addresses.
• Shared gateways - addresses from ip address virtual and ipv6 address virtual are created once with the role anycast and no interface assignment, however many devices declare them.
• Primary IP - a device's management interface address becomes the device's primary IPv4 or IPv6 address. When the management address is shared by more than one interface, the device has no primary IP, because NetBox requires a primary IP to be assigned to the device itself. Any stale primary IP pointer on those devices is cleared.

Configuration Retrieval and Partial Runs

Running configurations are fetched one device at a time, and a failure for one device does not stop the sync:

• A single device fails (unreachable, inactive, an empty configuration, or a configuration that cannot be parsed) - the device is skipped with a warning naming its serial number. It still gets its device-level objects (device, device type, platform, site, role, and MAC address), but no layer-3 objects this run.
• The compliance API is unusable (a CloudVision version that does not provide it, or a token that cannot access it) - the first such failure stops all remaining configuration fetches. The run completes with device-level objects only.
• The compliance API appears unavailable - five consecutive service-level failures stop the remaining configuration fetches for that run.

Each fetch is bounded by GRPC_STREAM_TIMEOUT_SECONDS. Fetches run in sequence, so the time a run takes grows with the number of devices.

When some configurations were not read, the integration logs one Observations incomplete warning naming how many devices produced a usable configuration and the affected sites. Conclusions that a missing device could contradict are withheld until a later run reads every device:

• An IP address seen on only one interface is not assigned to that interface if another device in the same site (or, for a named VRF, anywhere in the fleet) was not read. The assignment is added on the next complete run.
• A prefix in a named VRF is not given a site scope in a multi-site deployment until every device has been read.

Conclusions that more data cannot change, such as clearing the interface assignment of an address already seen on two interfaces, are applied on every run.

Custom Fields

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

Configuration Parameters

config Parameters

Configure these under the config key in the policy definition.

* Provide either CVP_API_TOKEN, or both CVP_USERNAME and CVP_PASSWORD. Token authentication takes precedence when both are supplied.

The gRPC Resource API uses port 443 for both on-premises CVP and CVaaS. To use a different port, include it directly in CVP_HOST (for example, cvp.example.com:8443).

CVaaS hostnames

For CloudVision as a Service (CVaaS), set CVP_HOST to www.<cluster>.arista.io, where <cluster> is your CVaaS cluster name (for example, www.cv-prod-us-4.arista.io).

The www. prefix is required. The cluster hostname shown in your browser (for example, cv-prod-us-4.arista.io) resolves and serves TLS on port 443, but it is not the gRPC endpoint. If CVP_HOST is set to it, the connection fails with an error that can look like an authentication or network problem.

scope Parameters

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

Example scope block:

scope:
  sites:
    - London
    - Amsterdam
  tags:
    - label: topology_type
      value: spine
    - label: topology_type
      value: leaf

Running configurations are fetched only for devices in scope, so out-of-scope devices contribute no layer-3 objects.

Authentication

The integration supports two authentication methods against the CloudVision gRPC APIs:

• Service account token (preferred) - set CVP_API_TOKEN. The token is sent as gRPC call credentials on the encrypted channel. This is the recommended method for both CVP and CVaaS.
• Username and password - set CVP_USERNAME and CVP_PASSWORD. The integration exchanges these for a session token via a REST POST to /cvpservice/login/authenticate.do, then opens the gRPC channel with that token. The username is also sent as per-call metadata alongside the token.

The account must be able to read the device inventory, device tags, and device running configurations through the compliance API. Without access to running configurations, the integration still syncs device-level objects, but creates no layer-3 objects.

Both on-premises CVP and CVaaS use the same gRPC APIs on port 443. For CVaaS, use a service account token.

TLS verification

By default (CVP_SSL_VERIFY=True), the server certificate is validated against the system trust store. For a certificate signed by an internal or private CA, provide the CA chain to the host trust store and leave CVP_SSL_VERIFY=True.

Setting CVP_SSL_VERIFY=False accepts a self-signed certificate. In this mode:

• The server certificate is fetched on each run without CA validation and trusted only for that run's channel. It is not persisted.
• gRPC still verifies the certificate's SAN/CN against the target name, which is pinned to CVP_HOST. The self-signed certificate must therefore be issued for CVP_HOST. For a certificate presenting a different name, use a CA bundle with CVP_SSL_VERIFY=True instead.
• CVP_SSL_VERIFY=False requires CVP_API_TOKEN. It cannot be used with username/password authentication, because those credentials would travel over an unverified TLS connection during the REST session-token exchange.
• This mode is vulnerable to a machine-in-the-middle attack on each run. Use it only on trusted networks. For production, provide a proper CA chain and leave CVP_SSL_VERIFY=True.

Tags

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

The per-instance cv-{name} tag is created only on a real sync, not in bootstrap mode. When running multiple integration instances against different CloudVision systems, set a distinct CVP_NAME per instance so each set of objects can be identified by its tag.

Bootstrap Mode

When BOOTSTRAP is set to True, the integration creates the following without connecting to CloudVision:

• Tags: arista, cloudvision, discovered
• Custom fields: cv_streaming_status, cv_interface_type
• The Arista manufacturer
• All device roles: Spine, Leaf, L2 Leaf, Superspine, Campus Leaf, Border Leaf, and the Network Switch fallback

No site is created in bootstrap mode - the fallback site is created on demand during a real sync only when a device lacks a topology_datacenter tag, so bootstrap does not leave an unused site in NetBox. The Unknown manufacturer is likewise created only when a device needs it. Use bootstrap mode on the initial setup only, then set it to False for all subsequent runs.

Sync Behavior

• Direction: One-way, CloudVision to NetBox. The integration does not write to CloudVision, and it cannot be used to push NetBox data into CloudVision.
• Object deletion: The integration does not delete NetBox objects. Devices removed from CloudVision are not automatically decommissioned in NetBox, and interfaces, VLANs, VRFs, prefixes, and addresses removed from a device's configuration remain in NetBox.
• Cleared fields: Some fields are actively cleared when the running configuration shows they no longer apply: an interface's VRF and switchport mode, an IP address's interface assignment, a prefix's site scope, and a device's primary IP. A value set by hand on one of these fields of a CloudVision-managed object is removed on the next sync.
• Idempotency: Subsequent runs update existing NetBox objects rather than creating duplicates. The Diode SDK handles conflict resolution.
• Scope: All managed devices are synced by default. Optional site and tag scope filtering is available (see scope Parameters).
• Multi-instance: Each agent instance is configured for a single CloudVision system. Run a separate agent instance per system, each with a distinct CVP_NAME.

Known Limitations

The following are not synced in this release. Data that depends on them is missing from NetBox, and the run still reports success.

• VLAN range and list stanzas - only single-VLAN stanzas (vlan 10) are parsed. VLANs declared as a range or list (vlan 10-20, vlan 10,20,30) are not created, and interfaces cannot reference them. These forms are common in production configurations.
• VXLAN - VNI-to-VLAN mappings and VTEP source interfaces are not parsed. Vxlan* interfaces are created, classified as vxlan in cv_interface_type, but carry no VXLAN mapping data.
• Trunk native VLAN - switchport trunk native vlan is not read, so trunk ports have no untagged VLAN.
• Subinterfaces - subinterfaces such as Ethernet1.100 are created, but are not linked to their parent interface and carry no 802.1Q encapsulation.
• Port-channel membership - channel-group is not read, so physical ports are not linked to their port-channel.
• ip virtual-router address - this form of VARP shared gateway is not read. Shared gateways configured with ip address virtual are synced.
• switchport trunk allowed vlan all - not expanded. A trunk allowing all VLANs shows no tagged VLANs in NetBox.
• Secondary IPv4 addresses - skipped.
• Hardware models for access points and third-party devices - CloudVision does not report a model or vendor for these devices, so they receive a placeholder device type (see Device type resolution).