netbox.netbox.nb_lookup lookup – Queries and returns elements from NetBox

Note

This lookup plugin is part of the netbox.netbox collection (version 3.20.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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

To use it in a playbook, specify: netbox.netbox.nb_lookup.

New in netbox.netbox 0.1.0

Synopsis

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

Requirements

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

• pynetbox

Terms

Parameter	Comments
Terms	The NetBox object type to query

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('netbox.netbox.nb_lookup', key1=value1, key2=value2, ...) and query('netbox.netbox.nb_lookup', key1=value1, key2=value2, ...)

Parameter	Comments
api_endpoint	The URL to the NetBox instance to query :ansible-option-configuration:`Configuration:` Environment variable: NETBOX_API Environment variable: NETBOX_URL
api_filter	The api_filter to use. Filters should be key value pairs separated by a space.
key_file	(DEPRECATED) - NetBox 2.11 and earlier only The location of the private key tied to user account. Mutually exclusive with private_key.
plugin	The NetBox plugin to query
private_key	(DEPRECATED) - NetBox 2.11 and earlier only The private key as a string. Mutually exclusive with key_file.
raw_data	Whether to return raw API data with the lookup/query or whether to return a key/value dict :ansible-option-choices:`Choices:` :ansible-option-choices-entry:`false` :ansible-option-choices-entry:`true`
token	The API token created through NetBox This may not be required depending on the NetBox setup. :ansible-option-configuration:`Configuration:` Environment variable: NETBOX_TOKEN Environment variable: NETBOX_API_TOKEN
validate_certs	Whether or not to validate SSL of the NetBox instance :ansible-option-default-bold:`Default:` :ansible-option-default:`true`

Notes

Note

• When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('netbox.netbox.nb_lookup', term1, term2, key1=value1, key2=value2) and query('netbox.netbox.nb_lookup', term1, term2, key1=value1, key2=value2)

Examples

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

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

Return Value

Key	Description
Return value	list of composed dictionaries with key and value :ansible-option-returned-bold:`Returned:` success

Authors

• Chris Mills (@cpmills1975)

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.

Collection links