Using NetBox as an inventory source
Before we can use NetBox as an inventory source, we need to know the following 2 properties:
- The URL of your NetBox instance
- A NetBox API token
You can setup Nornir to leverage NetBoxInvetory2 as the inventory source in 2 ways:
- defining the inventory in Nornir's configuration
config.yaml
file - defining the inventory in Nornir's
InitNornir
constructor
Nornir configuration file
You can find more information about Nornir's configuration file in the Nornir documentation.
The relevant section of the configuration is the inventory
section. In this section we will have to specify the plugin we want to use and the options to configure the plugin.
---
inventory:
plugin: NetBoxInventory2
options:
nb_url: https://netbox.local:8000
nb_token: "1234567890"
We can then use the configuration file to initialise Nornir:
from nornir import InitNornir
nr = InitNornir(config_file="config.yaml")
Nornir constructor
We can achieve the same goal by using the Nornir InitNornir
constructor. InitNornir
accepts an inventory argument, which allows us to specify the inventory plugin to use.
from nornir import InitNornir
nr = InitNornir(
inventory={
"plugin":"NetBoxInventory2",
"options": {
"nb_url": "https://netbox.local:8000",
"nb_token": "1234567890"
}
}
)
Configuration options
NetBoxInventory2 has the following configuration options that influence it's behaviour.
Configuration options can be set in the options attribute of the inventory configuration.
NetBox URL
NetBox instance URL.
name | nb_url |
---|---|
type | string |
default | http://localhost:8000 |
required | True |
environment variable | NB_URL |
NetBox API token
NetBox API token.
name | nb_token |
---|---|
type | string |
default | 0123456789abcdef0123456789abcdef01234567 |
required | True |
environment variable | NB_TOKEN |
Enable / disable SSL verification
Allows for enabling or disabling certificate validation, when using HTTPS.
Alternatively accepts a path the CA bundle file to use for certificate validation.
name | ssl_verify |
---|---|
type | bool/string |
default | True |
required | False |
Flatten custom fields
This option allows you to "flatten" custom fields. By default a custom fields for a NetBox device or VM, will be stored in the custom_fields attribute of the data attribute of a Nornir host.
Enabling flatten_custom_fields
will modify that behaviour, so that each custom field is stored direclty as an attibute of the dat attribute of a Host, which makes working with custom fields a little bit easier.
flatten_custom_fields | |
---|---|
description | Store host/vm custom fields directly in NetBox data attribute |
type | bool |
default | False |
required | False |
Example with flatten_custom_fields
disabled
>>> pprint(nr.host["my_device"].data
{
...truncated...
"custom_fields": {
"cf_my_custom_field": "value"
}
...truncated...
}
Example with flatten_custom_fields
enabled
>>> pprint(nr.host["my_device"].data
{
...truncated...
"cf_my_custom_field": "value"
...truncated...
}
Filter parameters
Filter parameters allow you to filter the inventory data returned by thet NetBox API.
The NetBox API allows you to filter the returned data by attaching one or more query parameters to the request url. More information can be found in NetBox's documentation.
NetBoxInventory2 allows you to provide these query paramterers as key/value pairs using the filter_parameters
option. This works the same way as passing url paramters to a HTTP request using the Requests Python library.
name | filter_parmeters |
---|---|
type | dictionary |
default | None |
required | False |
Example: to filter the inventory for site site1
, we would need the following:
nr = InitNornir(
inventory={
"plugin": NetBoxInventory2,
"options": {
"nb_url": "http://netbox.local:8000",
"nb_token": "1234567890",
"filter_parameters": {"site": "site1"}
}
}
)
Example: to filter the inventory for site site1
and platform cisco_ios
, we would need the following:
nr = InitNornir(
inventory={
"plugin": NetBoxInventory2,
"options": {
"nb_url": "http://netbox.local:8000",
"nb_token": "1234567890",
"filter_parameters": {
"site": "site1",
"platform": "cisco_ios",
}
}
}
)
Example: to filter the inventory for site site1
or site site2
and platform cisco_ios
, we would need the following:
nr = InitNornir(
inventory={
"plugin": NetBoxInventory2,
"options": {
"nb_url": "http://netbox.local:8000",
"nb_token": "1234567890",
"filter_parameters": {
"site": ["site1", "site2"],
"platform": "cisco_ios",
}
}
}
)
Use platform slug
NetBox device/vm's have a platform attribute that indicates the type of operating system that is running on the device. This attribute is directly mappend to the Nornir Host's platform attribute, so that connection plugins understand which driver needs to be used to connect to the device.
By default the name attribute of a NetBox platform is mapped to the Nornir Host's platform. Use platform slug allows you to use the slug of the NetBox platform instead.
Whether or not you need to enable this option depends on how you defined your platforms in NetBox. Only one of use_platform_slug and use_platform_napalm_driver can be set as true.
name | use_platform_slug |
---|---|
type | bool |
default | False |
required | False |
Use platform NAPALM driver
Use platform NAPLAM driver works like use platform slugs, but uses the NAPLAM driver attibuted from the NetBox platform instead.
Whether or not you need to enable this option depends on how you defined your platforms in NetBox. Only one of use_platform_slug and use_platform_napalm_driver can be set as true.
name | use_platform_napalm_driver |
---|---|
type | bool |
default | False |
required | False |
Include Virtual Machines
Enable this option to also create Nornir Hosts for virtual machines stored in the NetBox database.
name | include_vms |
---|---|
type | bool |
default | False |
required | False |
Defaults file
Path to file with the defaults definition. If the file doesn't exist, it will be skipped. More information on on the defaults file can be found in Nornir's documentation.
name | defaults_file |
---|---|
type | str |
default | "defaults.yaml |
required | False |
Group file
Path to file with the groups definition. If the file doesn't exist, it will be skipped. More information on on the groups file can be found in Nornir's documentation.
name | group_file |
---|---|
type | str |
default | "groups.yaml |
required | False |
Ignore file permission errors
Ignore file defaults or group file permission errors. Enabling this option will continue loading the inventory when file permission errors are encountered for the defaults or group file.
name | ignore_file_permission_errors |
---|---|
type | bool |
default | False |
required | False |