NetBox Discovery

NetBox discovery

ktranslate can use NetBox as the source of truth for SNMP discovery instead of scanning CIDRs. When discovery.netbox.url is set, discovery lists devices from the NetBox DCIM API, then SNMP-probes those addresses with the same communities / v3 configs as a CIDR scan.

This landed in PR #799, with OAuth and filter lists in #813 / #819, and multi-interface fallback in #829.

host was renamed to url in #813. Use url.

When to use this

CIDR discovery	NetBox discovery
discovery.cidrs lists subnets to scan	discovery.netbox.url lists devices from NetBox
Good for a lab or a small fabric	Good when NetBox already has the inventory

You still need working SNMP credentials (default_communities or default_v3 / other_v3s). NetBox only supplies which IPs to try.

Example

discovery:
  cidrs: []
  ignore_list:
    - 10.0.10.0/24          # CIDRs are allowed; see ignore_list note below
  ports:
    - 161
  default_communities:
    - public
  add_devices: true
  add_mibs: true
  threads: 4
  replace_devices: true
  no_dedup_engine_id: true
  netbox:
    url: https://netbox.example.com/api/dcim/devices
    token: ${NETBOX_TOKEN}    # or leave empty and use OAuth env vars
    ip_to_pick: primary,oob   # try primary first, then OOB
    tag:
      - production
    site:
      - sydney
    location: []
    tenant: []
    status: active
    role:
      - access-switch
    custom_fields:
      monitoring_tier: gold

Token can be:

• Inline in YAML
• An environment variable (token: ${NETBOX_TOKEN})
• A cloud-secret reference (aws.sm.…, azure.kv.…, gcp.sm.…) — same prefixes as SNMPv3 secrets

discovery.netbox keys

Key	Required	Description
url	Yes	Full DCIM devices API URL, e.g. https://netbox.example.com/api/dcim/devices. Not a hostname-only field.
token	Yes, unless using OAuth	NetBox API token. Leave empty when KTRANS_OAUTH_TOKEN_URL is set.
ip_to_pick		Comma-separated list of NetBox IP fields to try, in order. First address that SNMP-responds wins; the rest are dropped. Values: primary (default), oob, primary_ip4, primary_ip6. Example: primary,oob,primary_ip4.
tag		List of NetBox tags (server-side filter).
site		List of site slugs.
location		List of location slugs.
tenant		List of tenant slugs.
role		List of device-role slugs.
status		Device status. Default if omitted: active.
custom_fields		key: value pairs. Unlike the filters above, these are evaluated client-side after the API returns. A device is kept only if every listed custom field matches.

tag, site, location, tenant, and role are arrays. A single string is a breaking change from the first NetBox PR — use a one-item list.

ktranslate always adds interface_count__gt=0 to the API query (devices with no interfaces are skipped).

OAuth (no API token in YAML)

Leave token empty and set:

Variable	Purpose
KTRANS_OAUTH_TOKEN_URL	Token endpoint (client-credentials).
KTRANS_OAUTH_CLIENT_ID	OAuth client id.
KTRANS_OAUTH_CLIENT_SECRET	OAuth client secret.
KTRANS_OAUTH_SCOPE	Scope string required by the IdP.

ktranslate POSTs grant_type=client_credentials and sends Authorization: Bearer … to NetBox.

ignore_list with NetBox

discovery.ignore_list applies to NetBox results too. Entries may be a single IP or a CIDR (PR #820):

ignore_list:
  - 10.0.0.98
  - 10.150.10.0/23

Use this to skip management ranges you do not want polled even if they are in NetBox.

Discovery still writes devices:

NetBox discovery is not a live poller. It fills snmp-base.yaml devices: the same way CIDR discovery does. Recreate or signal the poller after a discovery run so it reloads the file.