Learn How NetBox Can Be Inventory Source of Truth for Cisco NSO

Many challenges NetDevOps teams run up against relate to staying true to the Source of Truth approach to automation.  To truly matter, a Source of Truth must be used everywhere, not just where and when convenient.  I recently tackled on of these challenges within our network automation projects over in Learning at Cisco.

For more details on Source of Truth checkout

The challenge was how to keep the device inventory in our Cisco NSO servers accurate based on our NetBox based Source of Truth.  This type of problem is common in network automation systems. While APIs and programmability open up a lot of options for integrating tools together, the truth of the matter (no pun intended) is that most tools expect to be self-contained and hold their own “truth.”

In many ways, Cisco NSO acts as a Source of Truth for your network already.  Within its CDB, NSO keeps track of the intended configuration state of the network, and will work hard to enforce this state onto the running network.  While we want NSO to perform this role in our environment, many aspects of the desired configuration state of the network are documented within NetBox.  And, the inventory of network devices under NSO management is the first such aspect that we needed to tackle for the integration of NetBox to NSO.

Both Cisco NSO and NetBox offer robust APIs and well formatted data models. I’ve used these in previous projects to generate the device inventory for Cisco NSO from NetBox in an ad-hoc fashion.  However for this project, I wanted to make the integration a bit “better.”  Specifically, I had the following goals.

1. Something built into either Cisco NSO or NetBox directly, rather than an independent script or utility
2. The ability to easily verify the current state of the inventory in NSO with NetBox at anytime, with details about what deviations were found
3. Support for adding and updating devices in NSO to support the full lifecycle of network devices
4. In the future, the ability to support more than just device inventory management with NSO.

After considering the ways I could tackle this challenge, I opted to build a Python based NSO package that had the following initial features.

1. Define one or more “NetBox Servers” as NSO objects
2. Define one or more “NetBox Inventory” instances that supported querying a NetBox server and returning a set of network devices
3. Independent options to “verify” or “build” the NSO device inventory from the NetBox inventory

As with many of my coding projects, I also wanted to build something I could share with the community.  You can find the code for the nso-netbox on GitHub and on Code Exchange!

Let us explore NSO-Netbox!

With the background out of the way, let’s see the integration in action. Here you can see I have a NetBox server that has details on my firewalls, routers, switches, etc.

Adding NetBox to NSO

The first step is to add a “netbox-server” instance to NSO.

netbox-server dev-netbox
  fqdn netbox
  port 8080
  protocol http
  api-token "HMChcW4nsANPrv5C649cBdscFvkZUEqqQtNjnDob1QLZ2EKMP5ih82uwZhBbOnjudQaMu7nAT4lCHi9Ps7HlQ=="

You’ll need either the dns name or address of the NetBox server, the port and protocol it is available on, and an API token with read permissions.

With it added to NSO, you can take advantage of the first “action” the nso-netbox package offers.  We’ll verify that NSO can successfully communicate with NetBox.

admin@ncs# netbox-server dev-netbox verify-status 

output NetBox Version: 2.10.4, Python Version: 3.8.7, Plugins: {}, Workers Running: 1
success true

The action will return a boolean success value as well as some data about the NetBox server it is talking to.  All looks good here, let’s move on.

Adding a netbox-inventory query to NSO

Now we can create our first netbox-inventory instance. In this case, we’ll target all our data center fabric switches.

netbox-inventory dev01-fabric-switches
 auth-group          dev01
 connection-protocol ssh
 update-nso-devices true
 netbox-server       dev-netbox
 site                [ DEV01 DEV02 ]
 tenant              [ dev01-z0-admin ]
 device-type "Nexus 9300v"
  ned cisco-nx-cli-5.21
 !
 device-type "Nexus 9500v"
  ned cisco-nx-cli-5.21
 !
 device-role         [ "Virtual/Physical Switch" ]

As you can see the netbox-inventory instance provides a series of NetBox attributes to filter all the possible devices in NetBox down to the ones that you’d like to add to NSO. Above, we are looking for devices that:

• Are in either the DEV01 or DEV02 site
• Assigned to the dev01-z0-admin tenant
• Have the device-role of “Virtual/Physical Switch”
• And are either “Nexus 9300v” or “Nexus 9500v” device-types

Of these attributes, only “device-type” is required.  This is because NSO needs to know what types of devices you are trying to add, and what NED to use for them.

As you can see a single “netbox-inventory” can have 1 or more device-types included. This allows users to pick the granularity of their NSO inventory management activities.

In addition to the NetBox filters, you also need to specify the following details for the inventory:

• What NSO auth-group will be used to communicate with the devices.  The auth-group must be configured in NSO already.
• The connection-protocol to talk to devices. Options are ssh, telnet, http, https
• The netbox-server to query for this inventory

The configuration of value of “update-nso-devices” is a boolean flag that controls whether this instance of a netbox-inventory can be used to change the devices inventory in NSO.  If set to false, which is the default, this inventory definition can be used to verify and report discrepancies between NetBox and NSO, but would not allow changing the configured NSO devices list.

Verifying the NSO devices against NetBox

Let’s assume for a moment that you have been using NSO for awhile, and have devices already manually added all the NetBox devices to NSO.  We can use this package to verify if all devices were added correctly, or if any details differ between the two.

admin@ncs# netbox-inventory dev01-fabric-switches verify-inventory

output 
Device dev01-z0-sw-tor-hosting01-01 has a NetBox Role of Virtual/Physical Switch, which doesn't match NSO description of None
Device dev01-z0-sw-tor-shared-svcs-01 not found in NSO <devices>.
success false

Here we can see that a few differences have indeed been found.  One device is completely missing, and another has a description that doesn’t match the role in NetBox. The returned success value of false shows that there is a problem.

Updating the NSO devices to match NetBox

While we could manually repair these issues, let’s see how we can use nso-netbox to do it for us.

admin@ncs# netbox-inventory dev01-fabric-switches build-inventory
output # Adding Devices to NSO from NetBox inventory.
devices: 
.
.
.

# Action input commit: False. Devices will NOT be added to NSO.
- device: dev01-z0-sw-tor-shared-svcs-02
  address: 10.252.128.38
  port: 22
  description: Virtual/Physical Switch
  auth-group: dev01
  device-type: 
    cli:
      ned-id: cisco-nx-cli-5.21
      protocol: ssh
    state: unlocked
    source:
      context: {"web": "http://netbox:8080/dcim/devices/49/", "api": "http://netbox:8080/api/dcim/devices/49/"}
      when: 2021-04-19T18:34:44
      source: /nso-netbox:netbox-inventory{dev01-fabric-switches}
  device-groups: 
  - NetBoxInventory dev01-fabric-switches
  - NetBoxInventory dev01-fabric-switches dev01-z0-admin
  - NetBoxInventory dev01-fabric-switches Nexus 9300v
  - NetBoxInventory dev01-fabric-switches Virtual/Physical Switch


# Action input commit: False. Devices will NOT be added to NSO.
success false

The above command and output shows the “build-inventory” action in the package.  This action will build and display the configuration for NSO that would be needed to align to NetBox.  Notice how in addition to just the device configurations, several device-groups are also created based on the NetBox configuration.  This command is a great final check for what configuration would be applied, but as the “success false” and final line in the output, “build-inventory” doesn’t apply the configuration by default.  You must add “commit true” to the command when you run it.

admin@ncs# netbox-inventory dev01-fabric-switches build-inventory commit true
output # Adding Devices to NSO from NetBox inventory.
devices: 
.
.
.

success true
admin@ncs# 
System message at 2021-04-19 18:34:26...
Commit performed by admin via tcp using build-inventory.

The “success true” plus the system messages about the commit show that now we have updated our devices list.  Another “verify-inventory” action will show we are in good shape.

admin@ncs# netbox-inventory dev01-fabric-switches verify-inventory

output 
success true

Summing Up

Well, I hope you found this post interesting and showing how combining the tools in your NetDevOps Toolchest can be done to provide an excellent experience for you and your team.  If you’d like to see more about how this package works, I’d suggest reviewing the code on  GitHub or Code Exchange. The README will show you how to install the package, how to add NetBox VMs in addition to NetBox Devices, and the action “connect-inventory” can be used to establish that most important initial connection to managed devices.

Have any questions on this post, Cisco NSO, NetBox, or something else you’d like to ask me?  Let me know if the comments, on Twitter, or email.

And if you’d like to dig into using Cisco NSO as your network automation tool, don’t forget you can download and use NSO for free on DevNet for non-production use.  As well as explore the great NSO DevNet Sandbox. The Sandbox even includes NetBox!

We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

Twitter @CiscoDevNet | Facebook | LinkedIn

Visit the new Developer Video Channel

Share: