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

Note

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

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.

  • 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

Terms

Parameter

Comments

Terms

string / required

The NetBox object type to query

Parameters

Parameter

Comments

api_endpoint

string / required

The URL to the NetBox instance to query

Configuration:

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

Whether to return raw API data with the lookup/query or whether to return a key/value dict

Choices:

token

string

The API token created through NetBox

This may not be required depending on the NetBox setup.

Configuration:

validate_certs

string

Whether or not to validate SSL of the NetBox instance

Default: :ansible-option-default:`true`

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 Value

Key

Description

Return value

list / elements=string

list of composed dictionaries with key and value

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.