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

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.