netbox – NetBox inventory source

Synopsis

• Get inventory hosts from NetBox

Parameters

Parameter	Choices/Defaults	Configuration	Comments
api_endpoint - / required		env:NETBOX_API	Endpoint of the NetBox API
compose dictionary	Default: {}		List of custom ansible host vars to create from the device object fetched from NetBox
config_context boolean	Default: "no"		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.
group_by list	Choices: sites tenants racks tags device_roles device_types manufacturers platforms Default: []		Keys used to create groups.
groups dictionary	Default: {}		Add hosts to group based on Jinja2 conditionals.
keyed_groups list	Default: []		Add hosts to group based on the values of a variable.
plugin - / required	Choices: netbox		token that ensures this is a source file for the 'netbox' plugin.
query_filters list	Default: []		List of parameters passed to the query string (Multiple values may be separated by commas)
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 - / required		env:NETBOX_TOKEN env:NETBOX_API_KEY	NetBox token.
validate_certs boolean	Default: "yes"		Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

Examples

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

plugin: netbox
api_endpoint: http://localhost:8000
validate_certs: True
config_context: False
group_by:
  - device_roles
query_filters:
  - role: network-edge-router

# 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
compose:
  foo: last_updated
  bar: display_name
  nested_variable: rack.display_name

Status

• This inventory is not guaranteed to have a backwards compatible interface. [preview]
• This inventory is maintained by the Ansible Community. [community]

Authors

• Remy Leone (@sieben)
• Anthony Ruhier (@Anthony25)
• Nikhil Singh Baliyan (@nikkytub)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.