lookup¶

Collection Note

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

ansible-galaxy collection install networktocode.nautobot

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis¶

Queries Nautobot via its API to return virtually any information capable of being held in Nautobot.

Requirements¶

The following Python packages are needed on the host that executes this module:

pynautobot

Parameters¶

Parameter	Environment Variable	Comments
_terms required		The Nautobot object type to query
api_endpoint required	NAUTOBOT_URL	The URL to the Nautobot instance to query
api_filter		The api_filter to use.
api_version		The Nautobot Rest API version to use. Version Added: 4.1.0
num_retries		Number of retries This will only affect HTTP codes 429, 500, 502, 503, and 504.
plugin		The Nautobot plugin to query
raw_data		Whether to return raw API data with the lookup/query or whether to return a key/value dict
token	NAUTOBOT_TOKEN	The API token created through Nautobot This may not be required depending on the Nautobot setup.
validate_certs		Whether or not to validate SSL of the Nautobot instance

Examples¶

tasks:
  # query a list of devices
  - name: Obtain list of devices from Nautobot
    debug:
      msg: >
        "Device {{ item.value.display_name }} (ID: {{ item.key }}) was
         manufactured by {{ item.value.device_type.manufacturer.name }}"
    loop: "{{ query('networktocode.nautobot.lookup', 'devices',
                    api_endpoint='http://localhost/',
                    api_version='2.0',
                    token='<redacted>') }}"

# This example uses an API Filter
  # query a list of devices
  - name: Obtain list of devices from Nautobot
    debug:
      msg: >
        "Device {{ item.value.display_name }} (ID: {{ item.key }}) was
         manufactured by {{ item.value.device_type.manufacturer.name }}"
    loop: "{{ query('networktocode.nautobot.lookup', 'devices',
                    api_endpoint='http://localhost/',
                    api_version='2.0',
                    api_filter='role=management tags=Dell',
                    token='<redacted>') }}"

  # This example uses an API filter with depth set to get additional details from the lookup
  # Query a list of locations with API depth=1 to retrieve related details (like status, prefix_count, vlan_count)
  # Note: `location_name` should be set to the name of the desired location
  - name: Obtain location information from Nautobot and print some facts
    ansible.builtin.debug:
      msg: >-
        Location {{ item.value.name }} is {{ item.value['status']['name'] }} and has
        {{ item.value.prefix_count }} Prefixes and {{ item.value.vlan_count }} VLANs.
    loop: >-
      {{ query(
        'networktocode.nautobot.lookup',
        'locations',
        url=NAUTOBOT_URL,
        token=NAUTOBOT_TOKEN,
        api_filter='name=' + location_name + ' depth=1'
      ) }}

  # Fetch bgp sessions for R1-device
  - name: "Obtain bgp sessions for R1-Device"
    debug:
      msg: "{{ query('networktocode.nautobot.lookup', 'bgp_sessions',
                     api_filter='device=R1-Device',
                     api_endpoint='http://localhost/',
                     api_version='2.0',
                     token='<redacted>',
                     plugin='mycustomstuff') }}"

Return Values¶

Key	Data Type	Description	Returned
_list	list	list of composed dictionaries with key and value

Authors¶

Chris Mills (@cpmills1975)