Skip to content

inventory

Collection Note

This module is part of the networktocode.nautobot collection. To install the collection, use:

ansible-galaxy collection install networktocode.nautobot

Synopsis

  • Get inventory hosts from Nautobot
  • Note: If gathering an endpoint that has significant number of objects (such as interfaces), you may have failures caused by gathering too much data.
  • Look to leverage the GraphQL inventory or gather data as a first task in the playbook rather than in inventory.

Parameters

Parameter Defaults / Choices Comments
allow_unsafe
boolean		 If True, allows for potentially unsafe variables to be returned as-is in the inventory.
ansible_host_dns_name
boolean		 If True, sets DNS Name (fetched from primary_ip) to be used in ansible_host variable, instead of IP Address.
api_endpoint
required		 Endpoint of the Nautobot API
Env: NAUTOBOT_URL
api_version The version of the Nautobot REST API.
Version Added: 4.1.0
cache
bool		 Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
Env: ANSIBLE_INVENTORY_CACHE
cache_connection
str		 Cache connection data or path, read cache plugin documentation for specifics.
Env: ANSIBLE_CACHE_PLUGIN_CONNECTION
Env: ANSIBLE_INVENTORY_CACHE_CONNECTION
cache_plugin
str		 Default: memory
 Cache plugin to use for the inventory's source data.
Env: ANSIBLE_CACHE_PLUGIN
Env: ANSIBLE_INVENTORY_CACHE_PLUGIN
cache_prefix Default: ansible_inventory_
 Prefix to use for cache plugin files/tables.
Env: ANSIBLE_CACHE_PLUGIN_PREFIX
Env: ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX
cache_timeout
int		 Default: 3600
 Cache duration in seconds.
Env: ANSIBLE_CACHE_PLUGIN_TIMEOUT
Env: ANSIBLE_INVENTORY_CACHE_TIMEOUT
compose
dict		 List of custom ansible host vars to create from the device object fetched from Nautobot
computed_fields
boolean		 If True, it adds computed_fields in host vars.
Computed fields are Jinja2 templates that Nautobot renders at read time, and are only returned by the API when explicitly requested.
Each computed field is rendered per object per request, so enabling this on a large inventory adds server-side work.
Version Added: 6.3.0
config_context
boolean		 If True, it adds config_context in host vars.
Config-context enables the association of arbitrary data to devices and virtual machines grouped by location, role, platform, and/or tenant. Please check official nautobot docs for more info.
device_query_filters
list / elements=str		 List of parameters passed to the query string for devices (Multiple values may be separated by commas)
dns_name
boolean		 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		 Default: True
 By default, fetching interfaces and services will get all of the contents of Nautobot 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, querying Nautobot may be faster with fetch_all 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.
Version Added: 1.0.0
flatten_computed_fields
boolean		 By default, host computed fields are added as a dictionary host var named computed_fields.
If flatten_computed_fields is set to True, the fields will be added directly to the host instead.
Version Added: 6.3.0
flatten_config_context
boolean		 If I(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.
Version Added: 1.0.0
flatten_custom_fields
boolean		 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.
Version Added: 1.0.0
flatten_local_context_data
boolean		 If I(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.
Version Added: 1.0.0
follow_redirects Default: urllib2
Choices: urllib2, all, yes, safe, none		 Determine how redirects are followed.
By default, I(follow_redirects) is set to uses urllib2 default behavior.
group_by
list / elements=str		 Choices: locations, location, tenants, tenant, tenant_group, racks, rack, rack_group, rack_role, tags, tag, device_roles, role, device_types, device_type, manufacturers, manufacturer, platforms, platform, cluster, cluster_type, cluster_group, is_virtual, services, status, computed_fields Keys used to create groups. The I(plurals) option controls which of these are valid.
group_names_raw
boolean		 Will not add the group_by choice name to the group names
Version Added: 1.0.0
groups
dict		 Add hosts to group based on Jinja2 conditionals.
interfaces
boolean		 If True, it adds the device or virtual machine interface information in host vars.
Version Added: 1.0.0
keyed_groups
list / elements=dict		 Add hosts to group based on the values of a variable.
keyed_groups.default_value The default value when the host variable's value is an empty string.
This option is mutually exclusive with O(keyed_groups[].trailing_separator).
keyed_groups.key The key from input dictionary used to generate groups.
keyed_groups.parent_group parent group for keyed group.
keyed_groups.prefix A keyed group name will start with this prefix.
keyed_groups.separator Default: _
 separator used to build the keyed group name.
keyed_groups.trailing_separator Default: True
 Set this option to V(false) to omit the O(keyed_groups[].separator) after the host variable when the value is an empty string.
This option is mutually exclusive with O(keyed_groups[].default_value).
leading_separator
boolean		 Default: True
 Use in conjunction with O(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 V("") and the default separator is V("_").
Set this option to V(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.
Version Added: 2.11
max_uri_length
int		 Default: 4000
 When fetch_all is False, GET requests to Nautobot 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.
Version Added: 1.0.0
module_interfaces
boolean		 If True, it adds module interfaces to the list of device interfaces in the inventory.
Modules are only available in Nautobot v2.3.0+
Requires I(interfaces) to be enabled as well.
Version Added: 5.12.0
plugin
required		 Choices: networktocode.nautobot.inventory token that ensures this is a source file for the 'nautobot' plugin.
plurals
boolean		 Default: True
 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. "locations_mylocation" instead of "location_mylocation")
The choices of I(group_by) will be changed by this option.
Version Added: 1.0.0
query_filters
list / elements=str		 List of parameters passed to the query string for both devices and VMs (Multiple values may be separated by commas)
rename_variables
list / elements=dict		 Rename variables evaluated by nb_inventory, before writing them.
Each list entry contains a dict with a 'pattern' and a 'repl'.
Both 'pattern' and 'repl' are regular expressions.
The first matching expression is used, subsequent matches are ignored.
Internally `re.sub` is used.
services
boolean		 Default: True
 If True, it adds the device or virtual machine services information in host vars.
Version Added: 1.0.0
strict
bool		 If V(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
int		 Default: 60
 Timeout for Nautobot requests in seconds
token Nautobot API token to be able to read against Nautobot.
This may not be required depending on the Nautobot setup.
Env: NAUTOBOT_TOKEN
use_extra_vars
bool		 Merge extra vars into the available variables for composition (highest precedence).
Env: ANSIBLE_INVENTORY_USE_EXTRA_VARS
Version Added: 2.11
validate_certs
boolean		 Default: True
 Allows connection when SSL certificates are not valid. Set to C(false) when certificates are not trusted.
virtual_chassis_name
boolean		 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=str		 List of parameters passed to the query string for VMs (Multiple values may be separated by commas)

Examples

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

plugin: networktocode.nautobot.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 Nautobot documentation at https://nautobot.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 Nautobot query string

query_filters:
  - cf_foo: bar

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

plugin: networktocode.nautobot.inventory
compose:
  foo: last_updated
  bar: display
  nested_variable: rack.display
  # You can also use custom fields on the device or a nested object
  device_owner: custom_fields.device_owner
  ansible_network_os: platforms.custom_fields.ansible_network_os

---
# Computed fields are Jinja2 templates rendered by Nautobot at read time.
# They are opt-in: nothing is fetched unless computed_fields is enabled.

plugin: networktocode.nautobot.inventory
computed_fields: true
compose:
  device_summary: computed_fields.my_device_summary

---
# Set flatten_computed_fields to add each computed field as its own host var
# instead of a computed_fields dictionary.

plugin: networktocode.nautobot.inventory
computed_fields: true
flatten_computed_fields: true

---
# group_by creates one group per computed field key/value pair, named
# computed_field_<key>_<value>. It requires the computed_fields option.

plugin: networktocode.nautobot.inventory
computed_fields: true
group_by:
  - computed_fields

---
# 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: networktocode.nautobot.inventory
keyed_groups:
  - prefix: status
    key: status.value

# You can use rename_variables to change variable names before the inventory gets loaded.
rename_variables:
  - pattern: "cluster"
    repl: "nautobot_cluster"
  - pattern: "ansible_host"
    repl: "host"

Authors

  • Remy Leone (@sieben)
  • Anthony Ruhier (@anthony25)
  • Nikhil Singh Baliyan (@nikkytub)
  • Sander Steffann (@steffann)
  • Douglas Heriot (@douglasheriot)
  • Yannis Ansermoz (@yannis100)