networktocode.nautobot.gql_inventory inventory – Nautobot inventory source using GraphQL capability

Note

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

To install it, use: ansible-galaxy collection install networktocode.nautobot. You need further requirements to be able to use this inventory plugin, see Requirements for details.

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

Synopsis

  • Get inventory hosts from Nautobot using GraphQL queries

Requirements

The below requirements are needed on the local controller node that executes this inventory.

  • netutils

Parameters

Parameter

Comments

api_endpoint

string / required

Endpoint of the Nautobot API

Configuration:

cache

boolean

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

Choices:

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 = VALUE
    
    [inventory]
    cache_connection = VALUE
    
  • 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: :ansible-option-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-option-default:`"ansible\_inventory\_"`

Configuration:

  • INI entries:

    [default]
    fact_caching_prefix = ansible_inventory_
    

    Removed in: version 2.16 of ansible.builtin

    Why: Fixes typing error in INI section name

    Alternative: Use the ‘defaults’ section instead

    [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

integer

Cache duration in seconds

Default: :ansible-option-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

Create vars from jinja2 expressions.

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

follow_redirects

string

Determine how redirects are followed.

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

Choices:

group_by

list / elements=string

List of dot-sparated paths to index graphql query results (e.g. `platform.display`)

The final value returned by each path is used to derive group names and then group the devices into these groups.

Valid group names must be string, so indexing the dotted path should return a string (i.e. `platform.display` instead of `platform`)

If value returned by the defined path is a dictionary, an attempt will first be made to access the `name` field, and then the `display` field. (i.e. `platform` would attempt to lookup `platform.name`, and if that data was not returned, it would then try `platform.display`)

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

group_names_raw

boolean

added in networktocode.nautobot 4.6.0

Will not add the group_by choice name to the group names

Choices:

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

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

keyed_groups

list / elements=dictionary

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

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

default_value

string

added in ansible-core 2.12

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

This option is mutually exclusive with trailing_separator.

key

string

The key from input dictionary used to generate groups

parent_group

string

parent group for keyed group

prefix

string

A keyed group name will start with this prefix

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

separator

string

separator used to build the keyed group name

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

trailing_separator

boolean

added in ansible-core 2.12

Set this option to False to omit the separator after the host variable when the value is an empty string.

This option is mutually exclusive with default_value.

Choices:

leading_separator

boolean

added in ansible-core 2.11

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.

Choices:

plugin

string / required

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

Choices:

query

dictionary

GraphQL query parameters or filters to send to Nautobot to obtain desired data

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

devices

dictionary

Additional query parameters or filters for devices

virtual_machines

dictionary

Additional query parameters or filters for VMs

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:

timeout

integer

Timeout for Nautobot requests in seconds

Default: :ansible-option-default:`60`

token

string / required

Nautobot API token to be able to read against Nautobot.

This may not be required depending on the Nautobot setup.

Configuration:

use_extra_vars

boolean

added in ansible-core 2.11

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

Choices:

Configuration:

validate_certs

boolean

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

Choices:

Examples

# inventory.yml file in YAML format
# Example command line: ansible-inventory -v --list -i inventory.yml
# Add -vvv to the command to also see the GraphQL query that gets sent in the debug output.
# Add -vvvv to the command to also see the JSON response that comes back in the debug output.

# Minimum required parameters
plugin: networktocode.nautobot.gql_inventory
api_endpoint: http://localhost:8000  # Can be omitted if the NAUTOBOT_URL environment variable is set
token: 1234567890123456478901234567  # Can be omitted if the NAUTOBOT_TOKEN environment variable is set

# This will send the default GraphQL query of:
# query {
#   devices {
#     name
#     primary_ip4 {
#       host
#     }
#     platform {
#       napalm_driver
#     }
#   }
#   virtual_machines {
#     name
#     primary_ip4 {
#       host
#     }
#     platform {
#       name
#     }
#   }
# }

# This module will automatically add the ansible_host key and set it equal to primary_ip4.host
# as well as the ansible_network_os key and set it to platform.napalm_driver via netutils mapping
# if the primary_ip4.host and platform.napalm_driver are present on the device in Nautobot.

# Add additional query parameters with the query key.
plugin: networktocode.nautobot.gql_inventory
api_endpoint: http://localhost:8000
query:
  devices:
    tags: name
    serial:
    tenant: name
    location:
      name:
      contact_name:
      description:
      parent: name
  virtual_machines:
    tags: name
    tenant: name

# To group by use group_by key
# Specify the full path to the data you would like to use to group by.
# Ensure all paths are also included in the query.
plugin: networktocode.nautobot.gql_inventory
api_endpoint: http://localhost:8000
query:
  devices:
    tags: name
    serial:
    tenant: name
    status: display
    location:
      name:
      contact_name:
      description:
      parent: name
  virtual_machines:
    tags: name
    tenant: name
    status: display
group_by:
  - tenant.name
  - status.display

# Filter output using any supported parameters.
# To get supported parameters check the api/docs page for devices.
# Add `filters` to any level of the dictionary and a filter will be added to the GraphQL query at that level.
# (use -vvv to see the underlying GraphQL query being sent)
plugin: networktocode.nautobot.gql_inventory
api_endpoint: http://localhost:8000
query:
  devices:
    filters:
      name__ic: ams
    interfaces:
      filters:
        name__ic: ethernet
      name:
      ip_addresses: address

# You can filter to just devices/virtual_machines by filtering the opposite type to a name that doesn't exist.
# For example, to only get devices:
plugin: networktocode.nautobot.gql_inventory
api_endpoint: http://localhost:8000
query:
  virtual_machines:
    filters:
      name: EXCLUDE ALL

Return Values

Common return values are documented here, the following are the fields unique to this inventory:

Key

Description

_list

list / elements=string

list of composed dictionaries with key and value

Returned: success

Authors

  • Network to Code (@networktocode)

  • Armen Martirosyan (@armartirosyan)

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.