inventory¶
Collection Note
This module is part of the networktocode.nautobot collection. To install the collection, use:
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 | |
| 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_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 | 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
---
# 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)