Introducing Netbox in the Automation Context

One of the things that attracted me most to Netbox was how honest they are. On the very first page of the Netbox documentation, they clearly break down exactly what Netbox is, as well as what it is not. I think this is important because, real talk, how often are we oversold on a product’s capabilities?

So fast forward a little bit to the present. More and more people are getting into network automation, but the larger your infrastructure, the bigger the pain in the ass it is to write scripts for your entire inventory. If you’re familiar at all with Ansible or Nornir. you’re familiar with the concept of separating your inventory from your core code or configuration management.

If you’re not familiar with Ansible or Nornir, here is the gist. You write your configurations in one place, and then you identify your inventory that it applies to in a different place. The idea being that you can identify your inventory one time, usually in a YAML file

Here’s a basic example, ironically in the project where I am attempting to perform automation tasks against the Netbox API. Check out the Inventory.yaml file and the Groups.yaml file to see how inventory and connectivity are defined, and then check out Collector.py to see how one function is applied to each item in the inventory (not so obvious hint: the run() function runs a given function against every device in the inventory).

So where does Netbox come into play, again? Netbox is inventory management

Get to the Point…

No more defining YAML files.

I think that bears more emphasis than it was originally given. No more YAML files. When we set up our inventory in Netbox, we can now integrate Netbox with other applications. In fact, there is a Netbox inventory driver specifically for Nornir. And the cool part is that Netbox exposes and outstanding REST API that adheres to OpenAPI (read: Swagger) specs.

So get started by deploying Netbox:

You can run Netbox as a Docker container natively on your desktop/laptop as long as it runs Linux/WSL2. The steps to get that Docker container are here but note that the Docker run commands won’t work. You will need to run:

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<EOF
version: '3.4'
services:
  nginx:
    ports:
      - 8000:8080
EOF
docker-compose pull
docker-compose up

However, if you would like to run Netbox within EVE-NG, I’d encourage you to watch my video on how to get that going here. I forked the code and tweaked it to work within EVE-NG.

The Container is up and running. How do I automate it?

Netbox comes with a slick API, and like most well maintained REST APIs, leverages Swagger for quick documentation. For newcomers to API development, Swagger is basically a plugin that can scan your API for all of it’s capabilities (methods, required fields, response payloads) and scaffolds an interactive website for developers to use basically as documentation on how your API works. This is similar to other Cisco platform API documentation, like Meraki and DNA Center.

With your container running, head on over to http://localhost:8000/api/docs/

You’ll be brought to a page that has every endpoint and every method. Pay attention to the endpoints as well as their methods, and keep this very important factor in mind – under the hood, Netbox runs a PostgreSQL database – a relational database. Therefore, pretty much everything you do will require an ID rather than by name.

Take Device Roles here for a second. You can’t create a device without a role. So before you try to create a device programmatically, you’ll need to retrieve a list of device roles and select the specific ID that you want to associate with your device. Same with Sites. Same with Device Types. And Tenant IDs.

Beyond that, one of the worst documented parts of Netbox’s API is authentication. The container uses the same API key for all users, so in our case, we can use the same header:

headers = {
    'accept': 'application/json',
    'Authorization': 'Token 0123456789abcdef0123456789abcdef01234567',
}

And if you would like to explore more programmatic ways to retrieve data from Netbox, you may want to check out my KNetbOX project. In this case, the knetbox-getter.py file will retrieve all of the data from Netbox, while the knetbox.py file uses that data in conjunction with locally discovered devices to automatically add devices to inventory.