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

Note

This inventory plugin is part of the networktocode.nautobot collection (version 5.1.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:

  • Environment variable: NAUTOBOT_URL

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:

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

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:

  • Environment variable: NAUTOBOT_TOKEN

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