netbox.netbox.nb_lookup – Queries and returns elements from Netbox

Note

This plugin is part of the netbox.netbox collection.

To install it use: ansible-galaxy collection install netbox.netbox.

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

New in version 2.9: of

Synopsis

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

  • If wanting to obtain the plaintext attribute of a secret, key_file must be provided.

Requirements

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

  • pynetbox

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string / required
The Netbox object type to query
api_endpoint
string / required
The URL to the Netbox instance to query
api_filter
string
The api_filter to use.
key_file
string
The location of the private key tied to user account.
raw_data
string
Whether to return raw API data with the lookup/query or whether to return a key/value dict
token
string
The API token created through Netbox
This may not be required depending on the Netbox setup.
validate_certs
string
Default:
"yes"
Whether or not to validate SSL of the NetBox instance

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('nb_lookup', 'devices',
                    api_endpoint='http://localhost/',
                    token='<redacted>') }}"

# This example uses an API Filter

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('nb_lookup', 'devices',
                    api_endpoint='http://localhost/',
                    api_filter='role=management tag=Dell'),
                    token='<redacted>') }}"

# Obtain a secret for R1-device
tasks:
  - name: "Obtain secrets for R1-Device"
    debug:
      msg: "{{ query('nb_lookup', 'secrets', api_filter='device=R1-Device', api_endpoint='http://localhost/', token='<redacted>', key_file='~/.ssh/id_rsa') }}"

Return Values

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

Key Returned Description
_list
list / elements=string
success
list of composed dictionaries with key and value



Authors

  • Chris Mills (@cpmills1975)