netbox.netbox.nb_inventory inventory – NetBox inventory source

Note

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

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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

Comments

ansible_host_dns_name

If True, sets DNS Name (fetched from primary_ip) to be used in ansible_host variable, instead of IP Address.

:ansible-option-choices:`Choices:`

api_endpoint

Endpoint of the NetBox API

:ansible-option-configuration:`Configuration:`

ca_path

cache

Toggle to enable/disable the caching of the inventory’s source data, requires a cache plugin setup to work.

:ansible-option-choices:`Choices:`

:ansible-option-configuration:`Configuration:`

  • INI entry:

    [inventory]
    cache = false
    
  • Environment variable: ANSIBLE_INVENTORY_CACHE

cache_connection

Cache connection data or path, read cache plugin documentation for specifics.

:ansible-option-configuration:`Configuration:`

  • INI entries:

    [defaults]
    fact_caching_connection = VALUE
    
    [inventory]
    cache_connection = VALUE
    
  • Environment variable: ANSIBLE_CACHE_PLUGIN_CONNECTION

  • Environment variable: ANSIBLE_INVENTORY_CACHE_CONNECTION

cache_plugin

Cache plugin to use for the inventory’s source data.

:ansible-option-default-bold:`Default:` :ansible-option-default:`"memory"`

:ansible-option-configuration:`Configuration:`

  • INI entries:

    [defaults]
    fact_caching = memory
    
    [inventory]
    cache_plugin = memory
    
  • Environment variable: ANSIBLE_CACHE_PLUGIN

  • Environment variable: ANSIBLE_INVENTORY_CACHE_PLUGIN

cache_prefix

Prefix to use for cache plugin files/tables

:ansible-option-default-bold:`Default:` :ansible-option-default:`"ansible\_inventory\_"`

:ansible-option-configuration:`Configuration:`

  • INI entries:

    [defaults]
    fact_caching_prefix = ansible_inventory_
    
    [inventory]
    cache_prefix = ansible_inventory_
    
  • Environment variable: ANSIBLE_CACHE_PLUGIN_PREFIX

  • Environment variable: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX

cache_timeout

Cache duration in seconds

:ansible-option-default-bold:`Default:` :ansible-option-default:`3600`

:ansible-option-configuration:`Configuration:`

  • INI entries:

    [defaults]
    fact_caching_timeout = 3600
    
    [inventory]
    cache_timeout = 3600
    
  • Environment variable: ANSIBLE_CACHE_PLUGIN_TIMEOUT

  • Environment variable: ANSIBLE_INVENTORY_CACHE_TIMEOUT

cert

compose

List of custom ansible host vars to create from the device object fetched from NetBox

:ansible-option-default-bold:`Default:` :ansible-option-default:`{}`

config_context

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.

:ansible-option-choices:`Choices:`

device_query_filters

List of parameters passed to the query string for devices (Multiple values may be separated by commas).

You can also use Jinja2 templates.

:ansible-option-default-bold:`Default:` :ansible-option-default:`[]`

dns_name

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.

:ansible-option-choices:`Choices:`

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.

:ansible-option-choices:`Choices:`

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.

:ansible-option-choices:`Choices:`

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.

:ansible-option-choices:`Choices:`

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.

:ansible-option-choices:`Choices:`

follow_redirects

group_by

Keys used to create groups. The plurals and racks options control which of these are valid.

rack_group is supported on NetBox versions 2.10 or lower only

location is supported on NetBox versions 2.11 or higher only

:ansible-option-choices:`Choices:`

:ansible-option-default-bold:`Default:` :ansible-option-default:`[]`

groups

Add hosts to group based on Jinja2 conditionals.

:ansible-option-default-bold:`Default:` :ansible-option-default:`{}`

key

keyed_groups

Add hosts to group based on the values of a variable.

:ansible-option-default-bold:`Default:` :ansible-option-default:`[]`

The default value when the host variable’s value is an empty string.

This option is mutually exclusive with :ansopt:`netbox.netbox.nb\_inventory#inventory:keyed\_groups[].trailing\_separator`.

key

The key from input dictionary used to generate groups

parent_group

parent group for keyed group

prefix

A keyed group name will start with this prefix

:ansible-option-default-bold:`Default:` :ansible-option-default:`""`

separator

separator used to build the keyed group name

:ansible-option-default-bold:`Default:` :ansible-option-default:`"\_"`

Use in conjunction with keyed_groups.

By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.

This is because the default prefix is “” and the default separator is “_”.

Set this option to False to omit the leading underscore (or other separator) if no prefix is given.

If the group name is derived from a mapping the separator is still used to concatenate the items.

To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.

:ansible-option-choices:`Choices:`

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.

:ansible-option-default-bold:`Default:` :ansible-option-default:`4000`

plugin

token that ensures this is a source file for the ‘netbox’ plugin.

:ansible-option-choices:`Choices:`

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.

:ansible-option-choices:`Choices:`

If True, it adds the device or virtual machine prefixes to hostvars nested under “site”.

Must match selection for “site_data”, as this changes the structure of “site” in hostvars

:ansible-option-choices:`Choices:`

query_filters

List of parameters passed to the query string for both devices and VMs (Multiple values may be separated by commas).

You can also use Jinja2 templates.

:ansible-option-default-bold:`Default:` :ansible-option-default:`[]`

If False, skip querying the racks for information, which can be slow with great amounts of racks.

The choices of group_by will be changed by this option.

:ansible-option-choices:`Choices:`

strict

If :ansval:`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.

:ansible-option-choices:`Choices:`

timeout

token

NetBox API token to be able to read against NetBox.

This may not be required depending on the NetBox setup.

You can provide a “type” and “value” for a token if your NetBox deployment is using a more advanced authentication like OAUTH.

If you do not provide a “type” and “value” parameter, the HTTP authorization header will be set to “Token”, which is the NetBox default

:ansible-option-configuration:`Configuration:`

Merge extra vars into the available variables for composition (highest precedence).

:ansible-option-choices:`Choices:`

:ansible-option-configuration:`Configuration:`

validate_certs

virtual_chassis_name

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.

:ansible-option-choices:`Choices:`

vm_query_filters

List of parameters passed to the query string for VMs (Multiple values may be separated by commas).

You can also use Jinja2 templates.

:ansible-option-default-bold:`Default:` :ansible-option-default:`[]`

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'
  - tenant__n: internal

# has_primary_ip is a useful way to filter out patch panels and other passive devices
# Adding '__n' to a field searches for the negation of the value.
# The above searches for devices that are NOT "tenant = internal"

# 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/stable/rest-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

# For use in Ansible Tower (AWX), please see this blog from RedHat: https://www.ansible.com/blog/using-an-inventory-plugin-from-a-collection-in-ansible-tower
# The credential for NetBox will need to expose NETBOX_API and NETBOX_TOKEN as environment variables.
# Example Ansible Tower credential Input Configuration:

fields:
  - id: NETBOX_API
    type: string
    label: NetBox Host URL
  - id: NETBOX_TOKEN
    type: string
    label: NetBox API Token
    secret: true
required:
  - NETBOX_API
  - NETBOX_TOKEN

# Example Ansible Tower credential Injector Configuration:

env:
  NETBOX_API: '{{ NETBOX_API }}'
  NETBOX_TOKEN: '{{ NETBOX_TOKEN }}'

# Example of time_zone and utc_offset usage

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
token: <insert token>
validate_certs: True
config_context: True
group_by:
  - site
  - role
  - time_zone
  - utc_offset
device_query_filters:
  - has_primary_ip: 'true'
  - manufacturer_id: 1

# using group by time_zone, utc_offset it will group devices in ansible groups depending on time zone configured on site.
# time_zone gives grouping like:
# - "time_zone_Europe_Bucharest"
# - "time_zone_Europe_Copenhagen"
# - "time_zone_America_Denver"
# utc_offset gives grouping like:
# - "time_zone_utc_minus_7"
# - "time_zone_utc_plus_1"
# - "time_zone_utc_plus_10"

# Example of using a token type

plugin: netbox.netbox.nb_inventory
api_endpoint: http://localhost:8000
token:
  type: Bearer
  value: test123456

Authors

  • Remy Leone (@sieben)

  • Anthony Ruhier (@Anthony25)

  • Nikhil Singh Baliyan (@nikkytub)

  • Sander Steffann (@steffann)

  • Douglas Heriot (@DouglasHeriot)

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.