FAQ & Troubleshooting

Common Issues

1. Authentication errors:

   Either CVP_API_TOKEN or both CVP_USERNAME and CVP_PASSWORD must be provided

   Solution: Provide either CVP_API_TOKEN, or both CVP_USERNAME and CVP_PASSWORD, in your configuration or .env file. A service account token is the recommended method.

2. Session token exchange fails:

   Authentication failed at cvp.example.com

   Solution: When using username/password authentication, verify the credentials are correct and that the account can reach the CloudVision REST login endpoint. Confirm CVP_HOST is correct and reachable from the agent host.

3. Invalid host errors:

   Invalid host 'https://cvp.example.com': do not include a URL scheme

   Solution: Set CVP_HOST to a bare hostname or hostname:port (for example, cvp.example.com or cvp.example.com:443). Do not include a scheme such as https://, a path, or credentials.

4. CVaaS connection fails with an unclear gRPC error:

   Solution: For CVaaS, set CVP_HOST to www.<cluster>.arista.io (for example, www.cv-prod-us-4.arista.io). The cluster hostname shown in your browser, without the www. prefix, is not the gRPC endpoint. Connecting to it fails in a way that can look like an authentication or network problem.

5. TLS certificate errors:

   Solution: For a certificate signed by an internal or private CA, add the CA chain to the host trust store and leave CVP_SSL_VERIFY=True. Setting CVP_SSL_VERIFY=False accepts a self-signed certificate but requires CVP_API_TOKEN, and the certificate must be issued for CVP_HOST. CVP_SSL_VERIFY=False cannot be used with username/password authentication.

6. Diode connection errors:

   failed to connect to diode

   Solution: Verify that DIODE_CLIENT_ID, DIODE_CLIENT_SECRET, and the target value in your agent.yaml are correct. Confirm outbound gRPCS access (port 443) from your agent host to your NetBox instance.

7. A scoped run ingests no devices or fails on the tag API:

   Solution: When scope.sites or scope.tags is set, the integration must be able to read CloudVision device tags. If the tag API is unavailable or the token lacks tag-read permission, a scoped run fails deliberately rather than silently ingesting nothing. Confirm the token can read tags, or remove the scope filter to run an inventory-only sync.

8. Custom fields not present in NetBox after the first run:

   Solution: The custom fields are created during bootstrap mode. Ensure you ran the agent with BOOTSTRAP: true and applied the resulting deviations in NetBox Assurance before running the full sync.

9. Objects not appearing in NetBox after the agent reports successful ingestion:

   Solution: Discovered data is staged as deviations in NetBox Assurance and must be applied before it appears in NetBox. Navigate to Assurance → Active Deviations and apply the deviations.

10. Devices sync, but no interfaces, VLANs, VRFs, prefixes, or IP addresses appear:

    the compliance API is not usable with these credentials; skipping the remaining N devices (config-derived entities degraded this run)

    Solution: Layer-3 objects are parsed from each device's running configuration, which is read through the CloudVision compliance API. This warning means the API rejected the request because the CloudVision version does not provide it or the credentials cannot access it. Confirm the service account or user can read device running configurations. Device-level data continues to sync in the meantime.

11. Some devices have no interfaces or addresses:

    Retrieved running configs for 10/12 devices

    Solution: Running configurations are fetched per device, and a device whose configuration cannot be read is skipped with a warning naming its serial number, for example Skipping config for <serial>: ... or Config fetch failed for <serial> .... Check that the device is streaming to CloudVision. The device's other data still syncs, and its layer-3 objects are added on the next run that reads its configuration.

12. Observations incomplete warning in the log:

    Solution: Not every in-scope device produced a usable running configuration this run. To avoid writing conclusions that a missing device could contradict, the integration withholds some IP address interface assignments and prefix site scopes until a run reads every device. See Configuration Retrieval and Partial Runs.

Frequently Asked Questions

Q: Does the integration write any data back to Arista CloudVision?

A: No. The integration is read-only. It reads the CloudVision inventory, tag, and compliance APIs and sends discovered data to NetBox via Diode. No changes are made to CloudVision.

Q: Can I use the integration to push data from NetBox into CloudVision?

A: No. Data flows from CloudVision into NetBox only. The integration does not provision or configure anything in CloudVision.

Q: Will objects be deleted from NetBox if they are removed from CloudVision?

A: No. The integration does not delete NetBox objects. If a device is removed from CloudVision, it is not automatically decommissioned in NetBox. The same applies to interfaces, VLANs, VRFs, prefixes, and IP addresses removed from a device's configuration. Handle these removals manually.

Q: Does the integration work with both CloudVision Portal (CVP) and CloudVision as a Service (CVaaS)?

A: Yes. Both are reached over the CloudVision gRPC Resource API on port 443. For CVaaS, use a service account token.

Q: Can I run the integration against multiple CloudVision systems?

A: Yes, by running a separate agent instance for each system. Give each instance its own CVP_HOST, credentials, a distinct agent_name, and a distinct CVP_NAME so its objects are identifiable by the cv-{name} tag in NetBox.

Q: How is a device's NetBox site determined?

A: The site is resolved from the device's topology_datacenter CloudVision system tag. When that tag is absent, the device is assigned to the SITE_NAME value (default "CloudVision").

Q: How is a device's NetBox role determined?

A: The role is resolved from the device's topology_type CloudVision system tag - for example spine, leaf, l2leaf, superspine, campus-leaf, or borderleaf. Values are matched exactly and are case-sensitive. A device with no topology_type tag, or an unrecognized value, is assigned the Network Switch fallback role.

Q: Why do some devices have the device type Unknown Device, Wireless Access Point, or Arista EOS Switch?

A: These are placeholders for devices where CloudVision reports no hardware model, which is common for access points and third-party devices. Access points are identified by their topology_type tag and get Wireless Access Point. Other devices that report an EOS software version get Arista EOS Switch, and the rest get Unknown Device. Placeholders that cannot be attributed to Arista use an Unknown manufacturer. See Device type resolution.

Q: Where does the management interface name come from?

A: From the device's running configuration, so it matches the device. Only when no device's configuration could be read in a run does the integration name the management interface from the hardware model instead: Management0 for chassis families, Management1/1 for a few specific models, and Management1 for everything else. See Management interface naming.

Q: Are interfaces, VLANs, VRFs, prefixes, and IP addresses synchronized?

A: Yes. They are parsed from each device's EOS running configuration, retrieved through the CloudVision compliance API. See Running Configuration Parsing for what is read.

Q: Why are some VLANs missing?

A: Only single-VLAN stanzas such as vlan 10 are parsed. VLANs declared as a range or list, such as vlan 10-20 or vlan 10,20,30, are not created in this release. A VLAN used on a port but not declared in a vlan stanza is also not linked to the port.

Q: Is VXLAN supported?

A: Not in this release. Vxlan* interfaces are created, but VNI-to-VLAN mappings and VTEP source interfaces are not parsed.

Q: What are the cv-site-* VRFs?

A: When your devices span more than one site, the integration places each site's global routing table addresses and prefixes in a synthetic cv-site-{site} VRF. This keeps address ranges reused across sites, such as loopbacks, as separate NetBox records. Their route distinguishers are generated by the integration and do not exist in your network. Single-site deployments create none. See Multi-site VRF separation.

Q: Why does an IP address have no interface assignment?

A: Either the address is configured on more than one interface in the same routing domain, or it is an ip address virtual shared gateway, which is created with the anycast role. In both cases no single interface owns it. An address can also be left unassigned for one run when not every device's configuration was read.

Q: Why does a device have no primary IP?

A: A device's primary IP is set from its management interface address. When the same management address is configured on more than one device, NetBox cannot assign it to any one of them, so none of those devices gets a primary IP.

Q: Why was a value I set by hand removed?

A: The integration clears some fields 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 manual value on one of these fields of a CloudVision-managed object is removed on the next sync.

Q: How do I change the fallback NetBox site name?

A: Set the SITE_NAME parameter in your configuration. The default is "CloudVision". This value is only used for devices that have no topology_datacenter tag.