Getting Started

This guide walks you through setting up the Arista CloudVision Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Scope Configuration
  • Bootstrap Mode (First-Time Setup)
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
• Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the Arista CloudVision Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• Arista CloudVision access - a CloudVision Portal (CVP) on-premises instance or a CloudVision as a Service (CVaaS) tenant, with a service account token or a username and password that can read device inventory and tags
• Host system with Docker support
• Network connectivity between your host and both your NetBox instance and CloudVision

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2 GB RAM (4 GB recommended)
• Storage: 1 GB free disk space
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound gRPC access to your CloudVision system (port 443 for both CVP and CVaaS)
• DNS resolution for both NetBox and CloudVision hostnames
• Firewall rules configured to allow the above connections from your agent host

NetBox Setup

Generate Diode Client Credentials

1. Log in to your NetBox instance.
2. Navigate to Diode → Client Credentials.
3. Click + Add a Credential.
4. Enter a descriptive name (for example, "Arista CloudVision Integration").
5. Click Create.

6. Important: Copy and securely store the Client ID and Client Secret - you will need them in the agent configuration.

7. Navigate to Diode → Settings.
8. Copy the Diode target value - you will use this in the agent configuration file.

Agent Setup and Configuration

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and token provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session:

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

Step 2: Configure the Agent

1. Create the configuration file (you can name the file anything you like):

touch agent.yaml

2. Edit the configuration file and add the following. Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode → Settings → Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode  # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: arista_cloudvision_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      arista_cloudvision_worker:
        config:
          package: nbl_arista_cloudvision
          schedule: "0 */6 * * *"  # Every 6 hours. Set your desired schedule (see examples below)
          timeout: 5
          CVP_HOST: ${CVP_HOST}              # CloudVision host, e.g. cvp.example.com or cvp.example.com:443
          CVP_API_TOKEN: ${CVP_API_TOKEN}    # Service account token (preferred)
          # CVP_USERNAME: ${CVP_USERNAME}    # Alternative to CVP_API_TOKEN
          # CVP_PASSWORD: ${CVP_PASSWORD}    # Alternative to CVP_API_TOKEN
          SITE_NAME: "CloudVision"           # Fallback site name for devices without a topology_datacenter tag
          CVP_NAME: "cvp-primary"            # Optional instance identifier; used for the cv-{name} tag
          BOOTSTRAP: false                   # Set to true for initial setup only
          # CVP_SSL_VERIFY: true             # Set false to accept a self-signed cert (requires CVP_API_TOKEN)
        scope:                               # Optional: leave empty to ingest all devices
        # scope:                             # Or restrict ingestion by site or tag:
        #   sites:
        #     - London
        #   tags:
        #     - label: topology_type
        #       value: spine

Scope Configuration

The scope section limits which devices are synchronized. Configure it under a scope key in the policy, separate from config.

• sites - a list of site names. Only devices whose resolved site name (from the topology_datacenter CloudVision tag, or the SITE_NAME fallback) matches one of the listed names are ingested. Use ["*"] or omit to ingest all sites.
• tags - a list of {label, value} pairs. Only devices carrying at least one matching CloudVision tag are ingested. Omit for no tag filter.

Example:

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

Both filters resolve through CloudVision device tags. When a scope filter is active and the CloudVision tag API cannot be read, the run fails rather than silently ingesting no devices. See Scope Parameters for details.

Bootstrap Mode (First-Time Setup)

Bootstrap mode creates the static content in NetBox that the integration requires before the first full sync. Run it once on initial setup, then disable it for all subsequent runs. In bootstrap mode the integration makes no CloudVision API calls, so credentials are not required.

What bootstrap mode creates:

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

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-time run process:

1. Set BOOTSTRAP: true in your configuration.
2. Run the agent and monitor the output for executed successfully.
3. Stop the agent by pressing Ctrl+C once you see executed successfully.
4. Apply the deviations in NetBox Assurance (see Apply Deviations below).
5. Set BOOTSTRAP: false for all future runs.

Optional - Dry Run Mode

The agent can run in dry run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for troubleshooting or for sharing data with the NetBox Labs support team.

Add the following to the diode section of your configuration:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/  # Output file is written to this directory

Step 3: Run the Agent

Run the agent to synchronize CloudVision device inventory into NetBox.

Method 1: Set Environment Variables Manually

1. Export Diode credentials:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export CloudVision connection details:

export CVP_HOST="cvp.example.com"
export CVP_API_TOKEN="your-cloudvision-service-account-token"

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e CVP_HOST \
  -e CVP_API_TOKEN \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file:

touch .env

2. Edit the .env file and add the following:

## NetBox Diode credentials (from Step 1)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

## Arista CloudVision connection
CVP_HOST=cvp.example.com
CVP_API_TOKEN=your-cloudvision-service-account-token

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

echo ".env" >> .gitignore

Expected Output

After starting the agent, you will see log output as the integration reads CloudVision and sends data to NetBox:

{"time":"2025-07-20T15:15:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_arista_cloudvision.cloudvision_diode:Starting Arista CloudVision integration for cvp.example.com"}
{"time":"2025-07-20T15:15:02.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_arista_cloudvision.cloudvision_client:Retrieved 12 devices from CloudVision inventory"}
{"time":"2025-07-20T15:15:03.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_arista_cloudvision.builders.sites:Built 2 site(s): ['dc1', 'dc2']"}
{"time":"2025-07-20T15:15:04.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_arista_cloudvision.builders.devices:Built 12 devices from 12 inventory entries"}
{"time":"2025-07-20T15:15:05.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy arista_cloudvision_worker: Successful ingestion"}
{"time":"2025-07-20T15:15:05.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run\" executed successfully"}

View and Apply Discovered Data in NetBox Assurance

After the agent runs, work with the discovered CloudVision data in NetBox Assurance.

NetBox Assurance identifies deviations between data already in NetBox and the actual operational state discovered by the integration.

Accessing NetBox Assurance

1. Navigate to your NetBox instance UI.
2. Click on Assurance in the main navigation menu.

Explore Deviation Types

1. Click on Deviation Types to view the categories of deviations discovered.

2. Click the Name of a deviation type to view deviations of that type.

3. Click the Name of an individual deviation to view its details.

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been applied or ignored.

2. Click the Name of a deviation to view its details.

Apply Deviations

1. Select the deviations you want to apply. For large result sets, set Per Page to 500 first.

2. Select the first deviation, hold SHIFT, select the last one, then click Apply Selected.

3. Click Apply X Deviations to write the data to NetBox.

View the Arista CloudVision Data in NetBox

After running the integration and applying discovered data, you can navigate the CloudVision inventory in NetBox:

1. Click on Devices in the main navigation menu to view discovered EOS switches.

2. Click on a device to see its device type, platform, role, site, management interface, MAC address, and the cv_streaming_status custom field value.

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation
• Arista CloudVision Integration - Technical Information

Support

Email support@netboxlabs.com for support.