Home

Welcome to netbox_sd

Netbox_sd is an open source software project that helps manage targets for Prometheus based on data in Netbox. Targets are added/removed based on their status value (it must be Active) while adding additional labels to the target. What devices should be included can be controlled by using tags or services in Netbox and additional filtering.

Getting Started

Netbox_sd consists of a single binary plus a config file. It's meant to be run on the same instance Prometheus is on as to have access to the file_sd path that must be configured on Prometheus' side.

Building Netbox_sd

Currently there are no binary releases but installing netbox_sd is very easy. Install Golang on your system and run go install github.com/4xoc/netbox_sd@v1.0.0. This will automatically download and install netbox_sd in your $GOPATH/bin. go env | grep GOPATH shows you what $GOPATH is used.

Configuring Netbox_sd

A simple example of a config file is this where we select all devices that have the tag junos_exporter associated with. Some basic things must be defined to talk to Netbox (base_url and api_token). Note that base_url doesn't point to an API endpoint, always reference just the actual base URL of the Netbox installation. Netbox_sd will use the appropriate full URL. scan_interval simply means we want to check Netbox every 10 seconds for changes.

base_url: "https://netbox.mydomain.tld/"
api_token: aaabbbccc
scan_interval: 10s

groups:
  - file: /tmp/junos_exporter.yml
    type: device_tag
    match: junos_exporter
    port: 9100
    flags:
      include_vms: false
      inet_family: any
      all_addresses: false

We have one group defined (you can have as many groups as you like as long as the file path is always different). Because we want to filter for devices with a specific tag, we selected device_tag for the type. To only get devices that have the junos_exporter tag, we set is as match and lastly tell it what port should be used.

Then comes flags, which are optional, but provide some more control. First we exclude VMs from our result, allow for any IP family to be used (targets are always addressed via IP, not DNS) and lastly we select that only the first matching IP is used. Netbox_sd can allow you to have all IPs added as targets for some use-cases that go beyond this guide.

Save the file as config.yml.

Seeing it in action

Now that netbox_sd is installed and configured, execute $GOPATH/bin/netbox_sd (remember to look above where that path actually is) in the directory that contains the config.yml created earlier. The output looks something like this:

2024/09/09 19:44:12.905535 netbox_sd.go:64: Version:  (compiled on  with commit )
2024/09/09 19:44:12.905860 netbox_sd.go:88: loading config
2024/09/09 19:44:12.906281 metrics.go:203: starting metrics http endpont on [::]:9099
2024/09/09 19:44:13.027181 logging.go:67: [netbox-go] http call took 120ms
2024/09/09 19:44:13.027575 netbox_sd.go:111: connection to Netbox successful
2024/09/09 19:44:13.027607 netbox_sd.go:122: starting worker for group /tmp/junos_exporter.yml
2024/09/09 19:44:13.050093 logging.go:67: [netbox-go] http call took 22ms

Depending on your Netbox installation it can take some time for the first run to complete. Note that the logs don't show when a run is complete but have a look at /tmp/junos_exporter.yml where you should see something like this:

- targets:
    - '[2001:db8::1]:9100'
  labels:
    netbox_asset_tag: ""
    netbox_name: myRouter
    netbox_platform: ""
    netbox_rack: rack1
    netbox_role: router
    netbox_serial_number: abcd
    netbox_site: dc1
    netbox_tenant: network

Obviously the content will vary greatly but you should see one or more -targets: blocks of YAML.

Getting it into Prometheus

Within Prometheus all that's needed is a new scrape config, utilizing the file_sd_configs option to point to the file we told netbox_sd to create for us. Prometheus will automatically read and refresh the file to add the changes. Reload Prometheus and your target list should include those from /tmp/junos_exporter.yml.

[..]
scrape_configs:
  - job_name: junos_exporter
    file_sd_configs:
      - files:
        - /tmp/junos_exporter.yml