salt.pillar.netbox

A module that adds data to the Pillar structure from a NetBox API.

New in version 2019.2.0.

Configuring the NetBox ext_pillar

To use this pillar, you must first create a token in your NetBox instance at http://netbox.example.com/user/api-tokens/ (substituting the hostname of your NetBox instance)

The NetBox api_url and api_token must be set in the master config.

For example /etc/salt/master.d/netbox.conf:

ext_pillar:
  - netbox:
      api_url: http://netbox.example.com/api/
      api_token: 123abc

The following options are optional, and determine whether or not the module will attempt to configure the proxy pillar data for use with the napalm proxy-minion:

proxy_return: True
proxy_username: admin

By default, this module will query the NetBox API for the platform associated with the device, and use the 'NAPALM driver' field to set the napalm proxy-minion driver. (Currently only 'napalm' is supported for drivertype.)

This module currently only supports the napalm proxy minion and assumes you will use SSH keys to authenticate to the network device. If password authentication is desired, it is recommended to create another proxy key in pillar_roots (or git_pillar) with just the passwd key and use salt.renderers.gpg to encrypt the value.

If you use more than one username for your devices, leave proxy_username unset, and set the username key in your pillar as well. If any additional options for the proxy setup are needed, they should also be configured in pillar_roots.

Other available configuration options:

site_details: True

Whether should retrieve details of the site the device belongs to.

site_prefixes: True

Whether should retrieve the prefixes of the site the device belongs to.

devices: True

New in version 3004.

Whether should retrieve physical devices.

virtual_machines: False

New in version 3004.

Whether should retrieve virtual machines.

interfaces: False

New in version 3004.

Whether should retrieve the interfaces of the device.

interface_ips: False

New in version 3004.

Whether should retrieve the IP addresses for interfaces of the device. (interfaces must be set to True as well)

api_query_result_limit: Use NetBox default

New in version 3004.

An integer specifying how many results should be returned for each query to the NetBox API. Leaving this unset will use NetBox's default value.

connected_devices: False

New in version 3006.0.

Whether connected_devices key should be populated with device objects. If set to True it will force interfaces to also be true as a dependency

Note that each option you enable can have a detrimental impact on pillar performance, so use them with caution.

After configuring the pillar, you must restart the Salt master for the changes to take effect.

For example:

systemctl restart salt-master

To query perform a quick test of the pillar, you should refresh the pillar on the minion with the following:

salt minion1 saltutil.refresh_pillar

And then query the pillar:

salt minion1 pillar.items 'netbox'

Example output:

minion1:
    netbox:
        ----------
        id:
            511
        url:
            https://netbox.example.com/api/dcim/devices/511/
        name:
            minion1
        node_type:
            device
        display_name:
            minion1
        device_type:
            ----------
            id:
                4
            url:
                https://netbox.example.com/api/dcim/device-types/4/
            manufacturer:
                ----------
                id:
                    1
                url:
                    https://netbox.example.com/api/dcim/manufacturers/1/
                name:
                    Cisco
                slug:
                    cisco
            model:
                ISR2901
            slug:
                isr2901
            display_name:
                Cisco ISR2901
        device_role:
            ----------
            id:
                45
            url:
                https://netbox.example.com/api/dcim/device-roles/45/
            name:
                Network
            slug:
                network
        interfaces:
            |_
              ----------
              id:
                  8158
              ip_addresses:
                  |_
                    ----------
                    id:
                        1146
                    url:
                        https://netbox.example.com/api/ipam/ip-addresses/1146/
                    family:
                        ----------
                        value:
                            4
                        label:
                            IPv4
                    address:
                        192.0.2.1/24
                    vrf:
                        None
                    tenant:
                        None
                    status:
                        ----------
                        value:
                            active
                         label:
                            Active
                    role:
                        None
                    nat_inside:
                        None
                    nat_outside:
                        None
                    dns_name:
                    description:
                    tags:
                    custom_fields:
                    created:
                        2021-02-19
                    last_updated:
                        2021-02-19T06:12:04.153386Z
              url:
                  https://netbox.example.com/api/dcim/interfaces/8158/
              name:
                  GigabitEthernet0/0
              label:
              type:
                  ----------
                  value:
                      1000base-t
                  label:
                      1000BASE-T (1GE)
              enabled:
                  True
              lag:
                  None
              mtu:
                  None
              mac_address:
                  None
              mgmt_only:
                  False
              description:
              mode:
                  None
              untagged_vlan:
                  None
              tagged_vlans:
              cable:
                  None
              cable_peer:
                  None
              cable_peer_type:
                  None
              connected_endpoint:
                  None
              connected_endpoint_type:
                  None
              connected_endpoint_reachable:
                  None
              tags:
              count_ipaddresses:
                  1
            |_
              ----------
              id:
                  8159
              ip_addresses:
                  |_
                    ----------
                    id:
                        1147
                    url:
                        https://netbox.example.com/api/ipam/ip-addresses/1147/
                    family:
                        ----------
                        value:
                            4
                        label:
                            IPv4
                    address:
                        198.51.100.1/24
                    vrf:
                        None
                    tenant:
                        None
                    status:
                        ----------
                        value:
                            active
                        label:
                            Active
                    role:
                        None
                    nat_inside:
                        None
                    nat_outside:
                        None
                    dns_name:
                    description:
                    tags:
                    custom_fields:
                    created:
                        2021-02-19
                    last_updated:
                        2021-02-19T06:12:40.508154Z
                    url:
                        https://netbox.example.com/api/dcim/interfaces/8159/
                    name:
                        GigabitEthernet0/1
                    label:
                    type:
                        ----------
                        value:
                            1000base-t
                        label:
                            1000BASE-T (1GE)
                    enabled:
                        True
                    lag:
                        None
                    mtu:
                        None
                    mac_address:
                        None
                    mgmt_only:
                        False
                    description:
                    mode:
                        None
                    untagged_vlan:
                        None
                    tagged_vlans:
                    cable:
                        None
                    cable_peer:
                        None
                    cable_peer_type:
                        None
                    connected_endpoint:
                        None
                    connected_endpoint_type:
                        None
                    connected_endpoint_reachable:
                        None
                    tags:
                    count_ipaddresses:
                        1
        tenant:
            None
        platform:
            ----------
            id:
                1
            url:
                https://netbox.example.com/api/dcim/platforms/1/
            name:
                Cisco IOS
            slug:
                ios
        serial:
        asset_tag:
            None
        site:
            ----------
            id:
                18
            url:
                https://netbox.example.com/api/dcim/sites/18/
            name:
                Site 1
            slug:
                site1
            status:
                ----------
                value:
                    active
                label:
                    Active
            region:
                None
            tenant:
                None
            facility:
            asn:
                None
            time_zone:
                None
            description:
            physical_address:
            shipping_address:
            latitude:
                None
            longitude:
                None
            contact_name:
            contact_phone:
            contact_email:
            comments:
            tags:
            custom_fields:
            created:
                2021-02-25
            last_updated:
                2021-02-25T14:21:07.898957Z
            circuit_count:
                0
            device_count:
                1
            prefix_count:
                2
            rack_count:
                0
            virtualmachine_count:
                1
            vlan_count:
                0
            prefixes:
                |_
                  ----------
                  id:
                      284
                  url:
                      https://netbox.example.com/api/ipam/prefixes/284/
                  family:
                      ----------
                      value:
                          4
                      label:
                          IPv4
                  prefix:
                      192.0.2.0/24
                  vrf:
                      None
                  tenant:
                      None
                  vlan:
                      None
                        ----------
                      value:
                          active
                      label:
                          Active
                  role:
                      None
                  is_pool:
                      False
                  description:
                  tags:
                  custom_fields:
                  created:
                      2021-02-25
                  last_updated:
                      2021-02-25T15:08:27.136305Z
                |_
                  ----------
                  id:
                      285
                  url:
                      https://netbox.example.com/api/ipam/prefixes/285/
                  family:
                      ----------
                      value:
                          4
                      label:
                          IPv4
                  prefix:
                      198.51.100.0/24
                  vrf:
                      None
                  tenant:
                      None
                  vlan:
                      None
                  status:
                      ----------
                      value:
                          active
                      label:
                          Active
                  role:
                      None
                  is_pool:
                      False
                  description:
                  tags:
                  custom_fields:
                  created:
                      2021-02-25
                  last_updated:
                      2021-02-25T15:08:59.880440Z
        rack:
            None
        position:
            None
        face:
            None
        parent_device:
            None
        status:
            ----------
            value:
                active
            label:
                Active
        primary_ip:
            ----------
            id:
                1146
            url:
                https://netbox.example.com/api/ipam/ip-addresses/1146/
            family:
                4
            address:
                192.0.2.1/24
        primary_ip4:
            ----------
            id:
                1146
            url:
                https://netbox.example.com/api/ipam/ip-addresses/1146/
            family:
                4
            address:
                192.0.2.1/24
        primary_ip6:
            None
        cluster:
            None
        virtual_chassis:
            None
        vc_position:
            None
        vc_priority:
            None
        comments:
        local_context_data:
            None
        tags:
        custom_fields:
        config_context:
        connected_devices:
      ----------
      512:
          ----------
          airflow:
              None
          asset_tag:
              001
          cluster:
              None
          comments:
          config_context:
          created:
              2022-03-10T00:00:00Z
          custom_fields:
          device_role:
              ----------
              display:
                  Network switch
              id:
                  512
              name:
                  Network switch
              slug:
                  network_switch
              url:
                  https://netbox.example.com/api/dcim/device-roles/5/
          device_type:
              ----------
              display:
                  Nexus 3048
              id:
                  40
              manufacturer:
                  ----------
                  display:
                      Cisco
                  id:
                      1
                  name:
                      Cisco
                  slug:
                      cisco
                  url:
                      https://netbox.example.com/api/dcim/manufacturers/1/
              model:
                  Nexus 3048
              slug:
                  n3k-c3048tp-1ge
              url:
                  https://netbox.example.com/api/dcim/device-types/40/
          display:
              another device (001)
          face:
              ----------
              label:
                  Front
              value:
                  front
          id:
              1533
          last_updated:
              2022-08-22T13:50:15.923868Z
          local_context_data:
              None
          location:
              ----------
              _depth:
                  2
              display:
                  Location Name
              id:
                  2
              name:
                  Location Name
              slug:
                  location-name
              url:
                  https://netbox.example.com/api/dcim/locations/2
          name:
              another device
          parent_device:
              None
          platform:
              None
          position:
              18.0
          primary_ip:
              ----------
              address:
                  192.168.1.1/24
              display:
                  192.168.1.1/24
              family:
                  4
              id:
                  1234
              url:
                  https://netbox.example.com/api/ipam/ip-addresses/1234/
          primary_ip4:
              ----------
              address:
                  192.168.1.1/24
              display:
                  192.168.1.1/24
              family:
                  4
              id:
                  1234
              url:
                  https://netbox.example.com/api/ipam/ip-addresses/1234/
          primary_ip6:
              None
          rack:
              ----------
              display:
                  RackName
              id:
                  139
              name:
                  RackName
              url:
                  https://netbox.example.com/api/dcim/racks/139/
          serial:
              ABCD12345
          site:
              ----------
              display:
                  SiteName
              id:
                  2
              name:
                  SiteName
              slug:
                  sitename
              url:
                  https://netbox.example.com/api/dcim/sites/2/
          status:
              ----------
              label:
                  Active
              value:
                  active
          tags:
          tenant:
              None
          url:
              https://netbox.example.com/api/dcim/devices/1533/
          vc_position:
              None
          vc_priority:
              None
          virtual_chassis:
              None
        created:
            2021-02-19
        last_updated:
            2021-02-19T06:12:04.171105Z
salt.pillar.netbox.ext_pillar(minion_id, pillar, *args, **kwargs)

Query NetBox API for minion data