Using NetBox Custom Objects

What is NetBox?

NetBox is the leading open source tool for Network Source of Truth (NSOT). A Source of Truth enables administrators to document the current state of systems, as well as model future changes, in a version-controlled system. This includes configuration-level items, such as IP addressing and interface settings, as well as physical attributes, including site location, rack location and cabling.

The introduction of custom objects

Why is the introduction of NetBox custom objects important? Sometimes we need to model devices or information that don't strictly adhere to NetBox's default data model for devices. This greater flexibility allows users to more easily reflect the uniqueness of their environment within NetBox. The previous solution involved managing text within a custom field, installing a custom plugin or even developing a custom plugin. NetBox Custom Objects bridges the gap between custom fields and full-blown plugins.

NetBox supports many vendors and models that can be imported natively. The first choice should still be to utilize as much standard functionality as we can for ease of use and supportability. There are still valid uses for custom fields and plugins; however, with custom objects, we have the ability to extend these functionalities. We also have the ability to store data about our networks that doesn't fit neatly into predefined constructs.

The components of a custom object

Custom objects are available via a NetBox-supported plugin. (Installing plugins is outside the scope of this article, but information can be found here.) With our newly installed plugin, we now have an 'Object Types' section where we create our blueprint for custom objects.

We assign a name to our object type, and then we delve into the actual structure by creating custom fields. Fields are the building blocks that determine the appearance of our custom object. When a user creates a new object, fields are the areas where the specific information is held. We can have many field types, such as text, integer, JSON or drop-down choices. We can also reference other objects within NetBox, for example, virtual machines or devices that we have already defined. These relationships enable us to integrate with existing components within NetBox. We can define required and optional fields. We can also perform data validation using regular expressions (regex) to ensure that entries conform to our standards.

Once we have our types created, then we are free to create our actual objects. The types will appear under the "Objects" subsection. We can then create our different objects and manage them like we would any other object within NetBox.

How do we architect our objects?

With the flexibility of custom objects comes the responsibility of creating a data model that is useful for NetBox users and for any programmatic interactions you may have with NetBox. Because custom objects offer us so much flexibility, creating a complex object can be daunting. If we think about this in the context of building automation, it is not dissimilar to how we would create a data model that represents the configuration data of an item. Think, for example, of building a vars file for an Ansible playbook.

I prefer to take a non-technical approach when thinking about what I want to create. The idea of a blank page can be daunting, so the concept of a more mind-map-like approach than a traditional hierarchy may be a useful first step. Think: What are the elements of this device or service that I want to capture? Once we have a rough idea of the data elements we need to document, we can then consider the relationships between those elements.

Example object

To make this exercise less abstract, let's introduce an example of data we may want to capture in a custom object. A very common automation use case is the lifecycle management of F5 Virtual Servers (VS). Virtual Servers are the VIPs in F5 parlance, where we define components such as the IP address for our website or service, the port on which that service resides, the pool of nodes that the Virtual Server is load balancing, and many more.

Think about the power of automation. If you are familiar with creating a VS within F5 LTMs, you know that there are numerous components that can be configured during each creation. Most of these, the requestors of these services should not concern themselves with. We can then abstract some of the components into standard builds, which reduces options and encourages standardization. By nature, automation enables standardization. When modeling our objects, we can consider these nesting characteristics, where one or two choices enable the implementation of those abstracted artifacts.

In our example, we have created two types: F5 Pools and F5 Virtual Servers.

We have created our web servers as a standard object under the virtual servers section within NetBox. In our custom objects, we create a new pool and our field references available virtual servers that we can choose from a multi-object selection. We simply have a pool name and our member nodes.

Our custom object, named F5 Virtual Servers, has fields for the name of our VS, our destination IP, which is a linked object in the NetBox IPAM section, the destination port and the VS Pool, which provides options to select previously created F5 Pools.

How do we integrate with automation?

What do we do once we have the objects documented? If we are using our NetBox instance as the Source-of-Truth, meaning that what exists in NetBox should be reflected on production devices, we can enforce this via automation. We can use native Python to interact with NetBox via the pynetbox package. This provides an easy abstraction for working with the full REST API of the NetBox appliance.

In our example, we are going to use Ansible and specifically the nblookup plugin provided by NetBox to the Ansible community. This lookup plugin allows users to retrieve items from NetBox and pass them to Ansible tasks or playbooks.

Conclusion

The introduction of custom objects is a major milestone for the NetBox Labs project. This matters because, as teams become more accustomed to having a solid Network Source of Truth, the inclination is naturally to extend its usage into other areas.

There is great potential in having a single place to have data modeled for use in our networks. In addition to the F5 example, other use cases we are developing related to firewall policy, storage volume management, and even end-of-support databases add real value to clients trying to model everything as code. This gives life to those corner use cases that may be unique to your organization's deployments. 

We'd love to hear other ways you've used custom objects. Reach out to our team for more information on all things infrastructure automation.