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

Note

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

You might already have this collection installed if you are using the ansible package. 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.

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

New in version 2.9: of netbox.netbox

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, private_key or 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
env:NETBOX_API
env:NETBOX_URL
The URL to the Netbox instance to query
api_filter
string
The api_filter to use. Filters should be key value pairs separated by a space.
key_file
string
The location of the private key tied to user account. Mutually exclusive with private_key.
plugin
string
The Netbox plugin to query
private_key
string
The private key as a string. Mutually exclusive with key_file.
raw_data
boolean
    Choices:
  • no
  • yes
Whether to return raw API data with the lookup/query or whether to return a key/value dict
token
string
env:NETBOX_TOKEN
env:NETBOX_API_TOKEN
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('netbox.netbox.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('netbox.netbox.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('netbox.netbox.nb_lookup', 'secrets', api_filter='device=R1-Device', api_endpoint='http://localhost/', token='<redacted>', key_file='~/.ssh/id_rsa') }}"

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

      msg: "{{ query('netbox.netbox.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)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/netbox/netbox/nb_lookup_lookup.html