Technical Information

Arista CloudVision to NetBox Object Mapping

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

The integration reads two CloudVision gRPC Resource APIs:

• arista.inventory.v1 (DeviceService.GetAll) - the managed device inventory
• arista.tag.v2 (TagAssignmentService.GetAll) - device system tag assignments from the mainline workspace

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

Object Type Mapping Table

Field Mapping Details

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. 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.

Management interface naming

Each device receives exactly one management interface. The port name is derived from the hardware model:

The management interface is created with type 1000base-t and enabled: true. The management IP address is not available from the inventory API and is not set in this release.

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.

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:

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).

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

Authentication

The integration supports two authentication methods against the CloudVision gRPC Resource API:

• 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.

Both on-premises CVP and CVaaS use the same gRPC Resource API 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. 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.
• Object deletion: The integration does not delete NetBox objects. Devices removed from CloudVision are not automatically decommissioned in NetBox.
• 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.

Planned Discovery

Layer-3 interface, VLAN, VRF, prefix, and IP address discovery derived from EOS running configuration - including VARP anycast address handling - is planned for a future release and is not emitted by the current preview. The cv_interface_type custom field is created now so that interface classifications can be populated when that discovery lands.