netbox.netbox.nb_inventory – NetBox inventory source

Note

This plugin is part of the netbox.netbox collection (version 2.1.0).

To install it use: ansible-galaxy collection install netbox.netbox.

To use it in a playbook, specify: netbox.netbox.nb_inventory.

Synopsis

  • Get inventory hosts from NetBox

Parameters

Parameter Choices/Defaults Configuration Comments
ansible_host_dns_name
boolean
    Choices:
  • no ←
  • yes
If True, sets DNS Name (fetched from primary_ip) to be used in ansible_host variable, instead of IP Address.
api_endpoint
string / required
env:NETBOX_API
Endpoint of the NetBox API
cache
boolean
    Choices:
  • no ←
  • yes
ini entries:

[inventory]
cache = no

env:ANSIBLE_INVENTORY_CACHE
Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
cache_connection
string
ini entries:

[defaults]
fact_caching_connection = None

[inventory]
cache_connection = None

env:ANSIBLE_CACHE_PLUGIN_CONNECTION
env:ANSIBLE_INVENTORY_CACHE_CONNECTION
Cache connection data or path, read cache plugin documentation for specifics.
cache_plugin
string
Default:
"memory"
ini entries:

[defaults]
fact_caching = memory

[inventory]
cache_plugin = memory

env:ANSIBLE_CACHE_PLUGIN
env:ANSIBLE_INVENTORY_CACHE_PLUGIN
Cache plugin to use for the inventory's source data.
cache_prefix
string
Default:
"ansible_inventory_"
ini entries:

[default]
fact_caching_prefix = ansible_inventory_

[inventory]
cache_prefix = ansible_inventory_

env:ANSIBLE_CACHE_PLUGIN_PREFIX
env:ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
Prefix to use for cache plugin files/tables
cache_timeout
integer
Default:
3600
ini entries:

[defaults]
fact_caching_timeout = 3600

[inventory]
cache_timeout = 3600

env:ANSIBLE_CACHE_PLUGIN_TIMEOUT
env:ANSIBLE_INVENTORY_CACHE_TIMEOUT
Cache duration in seconds
compose
dictionary
Default:
{}
List of custom ansible host vars to create from the device object fetched from NetBox
config_context
boolean
    Choices:
  • no ←
  • yes
If True, it adds config_context in host vars.
Config-context enables the association of arbitrary data to devices and virtual machines grouped by region, site, role, platform, and/or tenant. Please check official netbox docs for more info.
device_query_filters
list / elements=string
Default:
[]
List of parameters passed to the query string for devices (Multiple values may be separated by commas)
dns_name
boolean
    Choices:
  • no ←
  • yes
Force IP Addresses to be fetched so that the dns_name for the primary_ip of each device or VM is set as a host_var.
Setting interfaces will also fetch IP addresses and the dns_name host_var will be set.
fetch_all
boolean
added in 0.2.1 of netbox.netbox
    Choices:
  • no
  • yes ←
By default, fetching interfaces and services will get all of the contents of NetBox regardless of query_filters applied to devices and VMs.
When set to False, separate requests will be made fetching interfaces, services, and IP addresses for each device_id and virtual_machine_id.
If you are using the various query_filters options to reduce the number of devices, you may find querying Netbox faster with fetch_all set to False.
For efficiency, when False, these requests will be batched, for example /api/dcim/interfaces?limit=0&device_id=1&device_id=2&device_id=3
These GET request URIs can become quite large for a large number of devices. If you run into HTTP 414 errors, you can adjust the max_uri_length option to suit your web server.
flatten_config_context
boolean
added in 0.2.1 of netbox.netbox
    Choices:
  • no ←
  • yes
If config_context is enabled, by default it's added as a host var named config_context.
If flatten_config_context is set to True, the config context variables will be added directly to the host instead.
flatten_custom_fields
boolean
added in 0.2.1 of netbox.netbox
    Choices:
  • no ←
  • yes
By default, host custom fields are added as a dictionary host var named custom_fields.
If flatten_custom_fields is set to True, the fields will be added directly to the host instead.
flatten_local_context_data
boolean
added in 0.3.0 of netbox.netbox
    Choices:
  • no ←
  • yes
If local_context_data is enabled, by default it's added as a host var named local_context_data.
If flatten_local_context_data is set to True, the config context variables will be added directly to the host instead.
follow_redirects
string
    Choices:
  • urllib2 ←
  • all
  • yes
  • safe
  • none
Determine how redirects are followed.
By default, follow_redirects is set to uses urllib2 default behavior.
group_by
list / elements=string
    Choices:
  • sites
  • site
  • tenants
  • tenant
  • racks
  • rack
  • rack_group
  • rack_role
  • tags
  • tag
  • device_roles
  • role
  • device_types
  • device_type
  • manufacturers
  • manufacturer
  • platforms
  • platform
  • region
  • cluster
  • cluster_type
  • cluster_group
  • is_virtual
  • services
  • status
Default:
[]
Keys used to create groups. The plurals option controls which of these are valid.
group_names_raw
boolean
added in 0.2.0 of netbox.netbox
    Choices:
  • no ←
  • yes
Will not add the group_by choice name to the group names
groups
dictionary
Default:
{}
Add hosts to group based on Jinja2 conditionals.
interfaces
boolean
added in 0.1.7 of netbox.netbox
    Choices:
  • no ←
  • yes
If True, it adds the device or virtual machine interface information in host vars.
keyed_groups
list / elements=string
Default:
[]
Add hosts to group based on the values of a variable.
max_uri_length
integer
added in 0.2.1 of netbox.netbox
Default:
4000
When fetch_all is False, GET requests to NetBox may become quite long and return a HTTP 414 (URI Too Long).
You can adjust this option to be smaller to avoid 414 errors, or larger for a reduced number of requests.
plugin
string / required
    Choices:
  • netbox.netbox.nb_inventory
token that ensures this is a source file for the 'netbox' plugin.
plurals
boolean
added in 0.2.1 of netbox.netbox
    Choices:
  • no
  • yes ←
If True, all host vars are contained inside single-element arrays for legacy compatibility with old versions of this plugin.
Group names will be plural (ie. "sites_mysite" instead of "site_mysite")
The choices of group_by will be changed by this option.
query_filters
list / elements=string
Default:
[]
List of parameters passed to the query string for both devices and VMs (Multiple values may be separated by commas)
services
boolean
added in 0.2.0 of netbox.netbox
    Choices:
  • no
  • yes ←
If True, it adds the device or virtual machine services information in host vars.
strict
boolean
    Choices:
  • no ←
  • yes
If yes make invalid entries a fatal error, otherwise skip and continue.
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
timeout
integer
Default:
60
Timeout for Netbox requests in seconds
token
string
env:NETBOX_TOKEN
env:NETBOX_API_KEY
NetBox API token to be able to read against NetBox.
This may not be required depending on the NetBox setup.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
virtual_chassis_name
boolean
    Choices:
  • no ←
  • yes
When a device is part of a virtual chassis, use the virtual chassis name as the Ansible inventory hostname.
The host var values will be from the virtual chassis master.
vm_query_filters
list / elements=string
Default:
[]
List of parameters passed to the query string for VMs (Multiple values may be separated by commas)

Examples

# netbox_inventory.yml file in YAML format
# Example command line: ansible-inventory -v --list -i netbox_inventory.yml

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
validate_certs: True
config_context: False
group_by:
  - device_roles
query_filters:
  - role: network-edge-router
device_query_filters:
  - has_primary_ip: 'true'

# has_primary_ip is a useful way to filter out patch panels and other passive devices

# Query filters are passed directly as an argument to the fetching queries.
# You can repeat tags in the query string.

query_filters:
  - role: server
  - tag: web
  - tag: production

# See the NetBox documentation at https://netbox.readthedocs.io/en/latest/api/overview/
# the query_filters work as a logical **OR**
#
# Prefix any custom fields with cf_ and pass the field value with the regular NetBox query string

query_filters:
  - cf_foo: bar

# NetBox inventory plugin also supports Constructable semantics
# You can fill your hosts vars using the compose option:

plugin: netbox.netbox.nb_inventory
compose:
  foo: last_updated
  bar: display_name
  nested_variable: rack.display_name

# You can use keyed_groups to group on properties of devices or VMs.
# NOTE: It's only possible to key off direct items on the device/VM objects.
plugin: netbox.netbox.nb_inventory
keyed_groups:
  - prefix: status
    key: status.value

Authors

  • Remy Leone (@sieben)

  • Anthony Ruhier (@Anthony25)

  • Nikhil Singh Baliyan (@nikkytub)

  • Sander Steffann (@steffann)

  • Douglas Heriot (@DouglasHeriot)