networktocode.nautobot.inventory inventory – Nautobot inventory source

Note

This inventory plugin is part of the networktocode.nautobot collection (version 4.1.1).

To install it, use: ansible-galaxy collection install networktocode.nautobot.

To use it in a playbook, specify: networktocode.nautobot.inventory.

Synopsis

  • Get inventory hosts from Nautobot

Parameters

Parameter

Comments

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.

Choices:

  • false ← (default)

  • true

api_endpoint

string / required

Endpoint of the Nautobot API

Configuration:

  • Environment variable: NAUTOBOT_URL

api_version

string

added in 4.1.0 of networktocode.nautobot

The version of the Nautobot REST API.

cache

boolean

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

Choices:

  • false ← (default)

  • true

Configuration:

  • INI entry:

    [inventory]
    cache = false
    
  • Environment variable: ANSIBLE_INVENTORY_CACHE

cache_connection

string

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

Configuration:

  • INI entries:

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

  • Environment variable: ANSIBLE_INVENTORY_CACHE_CONNECTION

cache_plugin

string

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

Default: “memory”

Configuration:

  • INI entries:

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

  • Environment variable: ANSIBLE_INVENTORY_CACHE_PLUGIN

cache_prefix

string

Prefix to use for cache plugin files/tables

Default: “ansible_inventory_”

Configuration:

  • INI entries:

    [default]
    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

integer

Cache duration in seconds

Default: 3600

Configuration:

  • INI entries:

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

  • Environment variable: ANSIBLE_INVENTORY_CACHE_TIMEOUT

compose

dictionary

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

Default: {}

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 region, site, role, platform, and/or tenant. Please check official nautobot docs for more info.

Choices:

  • false ← (default)

  • true

device_query_filters

list / elements=string

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

Default: []

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.

Choices:

  • false ← (default)

  • true

fetch_all

boolean

added in 1.0.0 of networktocode.nautobot

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.

Choices:

  • false

  • true ← (default)

flatten_config_context

boolean

added in 1.0.0 of networktocode.nautobot

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.

Choices:

  • false ← (default)

  • true

flatten_custom_fields

boolean

added in 1.0.0 of networktocode.nautobot

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.

Choices:

  • false ← (default)

  • true

flatten_local_context_data

boolean

added in 1.0.0 of networktocode.nautobot

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.

Choices:

  • false ← (default)

  • true

follow_redirects

string

Determine how redirects are followed.

By default, follow_redirects is set to uses urllib2 default behavior.

Choices:

  • urllib2 ← (default)

  • all

  • yes

  • safe

  • none

group_by

list / elements=string

Keys used to create groups. The plurals option controls which of these are valid.

Choices:

  • sites

  • site

  • tenants

  • tenant

  • tenant_group

  • racks

  • rack

  • rack_group

  • rack_role

  • tags

  • tag

  • device_roles

  • role

  • device_types

  • device_type

  • manufacturers

  • manufacturer

  • platforms

  • platform

  • region

  • cluster

  • cluster_type

  • cluster_group

  • is_virtual

  • services

  • status

Default: []

group_names_raw

boolean

added in 1.0.0 of networktocode.nautobot

Will not add the group_by choice name to the group names

Choices:

  • false ← (default)

  • true

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

Default: {}

interfaces

boolean

added in 1.0.0 of networktocode.nautobot

If True, it adds the device or virtual machine interface information in host vars.

Choices:

  • false ← (default)

  • true

keyed_groups

list / elements=string

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

Default: []

max_uri_length

integer

added in 1.0.0 of networktocode.nautobot

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.

Default: 4000

plugin

string / required

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

Choices:

  • networktocode.nautobot.inventory

plurals

boolean

added in 1.0.0 of networktocode.nautobot

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.

Choices:

  • false

  • true ← (default)

query_filters

list / elements=string

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

Default: []

services

boolean

added in 1.0.0 of networktocode.nautobot

If True, it adds the device or virtual machine services information in host vars.

Choices:

  • false

  • true ← (default)

strict

boolean

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.

Choices:

  • false ← (default)

  • true

timeout

integer

Timeout for Nautobot requests in seconds

Default: 60

token

string

Nautobot API token to be able to read against Nautobot.

This may not be required depending on the Nautobot setup.

Configuration:

  • Environment variable: NAUTOBOT_TOKEN

validate_certs

boolean

Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

Choices:

  • false

  • true ← (default)

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.

Choices:

  • false ← (default)

  • true

vm_query_filters

list / elements=string

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

Default: []

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 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

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.