Lightyear Integration FAQ and Troubleshooting

This document provides answers to commonly asked questions about the NetBox Lightyear integration.

General Questions

Q: What does the Lightyear integration synchronize into NetBox? A: The integration discovers and imports circuit, provider, provider account, and circuit type data from your Lightyear.ai service inventory into NetBox.

Q: Can NetBox push configurations back to Lightyear? A: No. The integration is currently data-in only, synchronizing from Lightyear.ai into NetBox.

Q: Is the integration free to use? A: The Lightyear integration is available with commercial editions of NetBox.

Q: Do I have to have NetBox Assurance to use the Lightyear integration? A: Yes. The Lightyear integration extracts and transforms the latest state from Lightyear.ai which is sent to NetBox Assurance where users can control how it is ingested into NetBox.

Q: Which versions of NetBox are supported? A: NetBox 4.1 and above.

Q: Which versions of the Lightyear API are supported? A: This integration is built on the Lightyear Developer API (v1).

Technical Questions

Q: What authentication method does the integration use to connect to Lightyear? A: The integration uses HMAC-SHA256 signed requests. You need to provide both a Lightyear API key (LIGHTYEAR_API_KEY) and API secret (LIGHTYEAR_API_SECRET). These credentials are used to generate a per-request signature.

Q: How does the integration handle Lightyear API rate limits? A: The integration automatically retries on rate limit responses (HTTP 429) with exponential backoff: 5 seconds, then 10 seconds, then 20 seconds (up to a maximum of 60 seconds). If a Retry-After header is present, it is respected. After 3 failed retries, the run is aborted with an error.

Q: How are circuits matched to their circuit type and provider? A: The integration extracts unique service types and provider names from all services in a single pass, creates the corresponding CircuitType and Provider entities first, and then references these when creating Circuit entities. This ensures all referenced objects exist before circuits are ingested.

Q: What happens if a circuit is missing a provider_service_id? A: If the detailed service response does not include a provider_service_id, the circuit's cid field is set to "Undefined" as a fallback.

Q: How does the integration handle duplicate providers or circuit types? A: Providers are deduplicated by slug before ingestion. Circuit types are deduplicated by slug. Only one entity per unique slug value is sent to NetBox, regardless of how many Lightyear services reference the same provider or service type.

Q: Does the integration support provider accounts? A: Yes. Provider accounts are created when a service includes a provider_account_number field. They are deduplicated using a composite key of provider_slug::account_number.

Q: How frequently should I run the integration? A: For most production use cases, every 6 hours (0 */6 * * *) is recommended. You can also run daily or weekly depending on how often your Lightyear service inventory changes.

Q: What tags are applied to objects discovered by the integration? A: All objects (CircuitTypes, Providers, ProviderAccounts, and Circuits) are tagged with lightyear and discovered.

Troubleshooting

Connection Issues

Problem: Connection to the Lightyear API fails with an authentication error Solution:

• Verify that LIGHTYEAR_API_KEY and LIGHTYEAR_API_SECRET are both set and correct
• Check that the API credentials have not been revoked in the Lightyear dashboard
• Ensure outbound HTTPS access to api.lightyear.ai is permitted from your agent host

Problem: The agent cannot reach the Lightyear API Solution:

• Confirm that your host has outbound HTTPS connectivity to api.lightyear.ai on port 443
• Check for proxy or firewall rules blocking outbound requests
• If using a non-default API host, verify the lightyear_host value in your agent.yaml is correct

Problem: The agent starts but fails with 401 Authentication Failed: invalid api key Solution:

• Verify that LIGHTYEAR_API_KEY and LIGHTYEAR_API_SECRET in your .env file are correct and match your Lightyear.ai account credentials
• Confirm the credentials have not been rotated or revoked in the Lightyear dashboard
• Check that the env vars are being passed to the container (use --env-file .env or -e flags in your docker run command)
• Note: the agent logs client_id: ${DIODE_CLIENT_ID} as a literal string — this is normal logging behaviour; the orb-agent resolves env vars at runtime

Problem: The agent cannot connect to Diode Solution:

• Verify the target value in your agent.yaml matches the Diode target shown in Diode > Settings in your NetBox UI
• Confirm that DIODE_CLIENT_ID and DIODE_CLIENT_SECRET are correctly set
• Check that outbound gRPC/gRPCS traffic to your NetBox instance is not blocked by firewall rules

Common Error Messages

"LIGHTYEAR_API_KEY must be provided in policy config"

• Add lightyear_api_key: ${LIGHTYEAR_API_KEY} to the config section of your policy in agent.yaml
• Ensure the LIGHTYEAR_API_KEY environment variable is exported before running the agent

"LIGHTYEAR_API_SECRET must be provided in policy config"

• Add lightyear_api_secret: ${LIGHTYEAR_API_SECRET} to the config section of your policy in agent.yaml
• Ensure the LIGHTYEAR_API_SECRET environment variable is exported before running the agent

Rate limit error after retries

• The integration has exceeded the Lightyear API rate limit after 3 retries
• Consider reducing the run frequency or contact Lightyear support about rate limit thresholds for your account