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

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

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

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

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

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 and tag APIs and sends discovered data to NetBox via Diode. No changes are made to 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. Handle decommissioning 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. A device with no topology_type tag, or an unrecognized value, is assigned the Network Switch fallback role.

Q: Why does a device have a Management1 interface instead of Management0?

A: The management port name is derived from the hardware model. Older fixed-form DCS-7050 and DCS-7060 platforms use Management1; all other EOS platforms use Management0.

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

A: Not in the current preview. This release synchronizes device inventory: devices, device types, platforms, sites, roles, management interfaces, and MAC addresses. Layer-3 interface, VLAN, VRF, prefix, and IP address discovery derived from EOS running configuration is planned for a future release.

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.