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
