Netbox Utils
Collection of functions for Salt-Nornir to interact with Netbox
using Execution module nr.netbox function.
To be able to retrieve data from netbox need to define Netbox URL
and API token parameters either under proxy minion pillar
salt_nornir_netbox_pillar section or in salt-master’ ext pillar
configuration. To be able to retrieve URL and toekn parameters from
master need to set pillar_opts parameter to True in salt-master’s
configuration.
Reference
- salt_nornir.netbox_utils.cache_list(keys='*', params=None, __salt__=None, proxy_id=None, **kwargs)
Function to list cached data for hosts.
- Parameters
keys – (str, list) glob pattern(s) to match cache keys to list
params – dictionary with salt_nornir_netbox parameters
__salt__ – reference to
__salt__execution modules dictionarykwargs – Fx filters to filter hosts to retrieve cache data for
- Returns
dictionary with cached data details
- salt_nornir.netbox_utils.cache_delete(keys=None, params=None, __salt__=None, proxy_id=None, **kwargs)
Function to delete cached data for hosts.
- Parameters
params – dictionary with salt_nornir_netbox parameters
__salt__ – reference to
__salt__execution modules dictionarykwargs – Fx filters to filter hosts to retrieve cache data for
keys – (str, list) glob pattern(s) to match cache keys to delete
- Returns
dictionary with
deleted_keyslist
- salt_nornir.netbox_utils.nb_graphql(field: Optional[dict] = None, filters: Optional[dict] = None, fields: Optional[list] = None, params: Optional[dict] = None, queries: Optional[dict] = None, query_string: Optional[str] = None, raise_for_status: bool = False, __salt__=None, proxy_id=None)
Function to send query to Netbox GraphQL API and return results.
- Parameters
field – dictionary of queies or string, field to return data for e.g. device, interface, ip_address
filters – dictionary of key-value pairs to filter by
fields – list of data fields to return
params – dictionary with salt_nornir_netbox parameters
queries – dictionary keyed by GraphQL aliases with query data
query_string – string with GraphQL query
raise_for_status – raise exception if requests response is not ok
__salt__ – reference to
__salt__execution modules dictionary
- salt_nornir.netbox_utils.nb_rest(method: str = 'get', api: str = '', __salt__=None, proxy_id=None, **kwargs) dict
Function to query Netbox REST API.
- Parameters
method – requests method name e.g. get, post, put etc.
api – api url to query e.g. “extras” or “dcim/interfaces” etc.
kwargs – any additional requests method’s arguments
__salt__ – reference to
__salt__execution modules dictionary
- salt_nornir.netbox_utils.get_interfaces(add_ip=False, add_inventory_items=False, sync=False, params=None, __salt__=None, proxy_id=None, hosts=None, cache=True, cache_ttl=3600, **kwargs)
Function to retrieve device interfaces from Netbox using GraphQL API.
- Parameters
add_ip – if True, retrieves interface IPs
add_inventory_items – if True, retrieves interface inventory items
sync – if True, saves get interfaces results to host’s in-memory inventory data under
interfaceskey, if sync is a string, provided value used as a key.__salt__ – reference to
__salt__execution modules dictionarykwargs – Fx filters to filter hosts to retrieve interfaces for
hosts – list of hosts to retrieve interface for
cache – boolean indicating whether to cache Netbox response or string
refreshto delete cached data, if set to False cached data ignored but not refreshedcache_ttl – integer indicating cache time to live
- Returns
dictionary keyed by device name with interface details
Note
add_inventory_itemsonly supported with Netbox 3.4 and above.Note
Either
hostsor__salt__withFxfilters should be provided, otherwiseCommandExecutionErrorraised.Starting with version
0.20.0support added to cache data retrieved from Netbox on a per-device basis. For this functionality to work need to have diskcache library installed on salt-nornir proxy minion. Cache is persistent and stored on the minion’s local file system.Sample data returned for interfaces when
add_ipandadd_inventory_itemsset to True:{'fceos4': {'Port-Channel1': {'bridge': None, 'bridge_interfaces': [], 'child_interfaces': [], 'custom_fields': {}, 'description': 'Main uplink interface', 'duplex': None, 'enabled': True, 'inventory_items': [], 'ip_addresses': [], 'last_updated': '2023-08-22T09:47:57.256446+00:00', 'mac_address': None, 'member_interfaces': [{'name': 'eth101'}, {'name': 'eth102'}], 'mode': None, 'mtu': None, 'parent': None, 'speed': None, 'tagged_vlans': [], 'tags': [], 'untagged_vlan': None, 'vrf': None, 'wwn': None}, 'eth1': {'bridge': None, 'bridge_interfaces': [], 'child_interfaces': [{'name': 'eth1.11'}], 'custom_fields': {}, 'description': 'Interface 1 description', 'duplex': None, 'enabled': True, 'ip_addresses': [{'address': '1.0.10.1/32', 'custom_fields': {}, 'description': '', 'dns_name': '', 'last_updated': '2023-08-22T09:48:03.287649+00:00', 'role': None, 'status': 'ACTIVE', 'tags': [], 'tenant': None}, {'address': '1.0.100.1/32', 'custom_fields': {}, 'description': '', 'dns_name': '', 'last_updated': '2023-08-22T09:48:01.692965+00:00', 'role': None, 'status': 'ACTIVE', 'tags': [], 'tenant': None}], 'inventory_items': [{'asset_tag': None, 'custom_fields': {}, 'description': '', 'label': '', 'manufacturer': None, 'name': 'SFP-1G-T', 'part_id': '', 'role': {'name': 'Transceiver'}, 'serial': '', 'tags': []}], 'ip_addresses': [], 'last_updated': '2023-08-22T09:47:57.809307+00:00', 'mac_address': None, 'member_interfaces': [], 'mode': 'TAGGED', 'mtu': 1500, 'parent': None, 'speed': None, 'tagged_vlans': [], 'tags': [], 'untagged_vlan': None, 'vrf': None, 'wwn': None}, 'loopback0': {'bridge': None, 'bridge_interfaces': [], 'child_interfaces': [], 'custom_fields': {}, 'description': '', 'duplex': None, 'enabled': True, 'inventory_items': [], 'ip_addresses': [{'address': '1.0.1.4/32', 'custom_fields': {}, 'description': '', 'dns_name': '', 'last_updated': '2023-08-22T09:48:00.728097+00:00', 'role': None, 'status': 'ACTIVE', 'tags': [], 'tenant': None}], 'last_updated': '2023-08-22T09:47:57.148611+00:00', 'mac_address': None, 'member_interfaces': [], 'mode': None, 'mtu': None, 'parent': None, 'speed': None, 'tagged_vlans': [], 'tags': [], 'untagged_vlan': None, 'vrf': None, 'wwn': None}}}}
- salt_nornir.netbox_utils.get_connections(params: Optional[dict] = None, sync=False, __salt__=None, proxy_id=None, hosts=None, cache=True, cache_ttl=3600, **kwargs) dict
Function to retrieve connections details from Netbox for interface and console ports.
- Parameters
params – dictionary with salt_nornir_netbox parameters
sync – if True, saves get connections results to host’s in-memory inventory data under
connectionskey, if sync is a string, provided value used as a key.__salt__ – reference to
__salt__execution modules dictionaryhosts – list of hosts to get connections for
cache – boolean indicating whether to cache Netbox response or string
refreshto delete cached data, if set to False cached data ignored but not refreshedcache_ttl – integer indicating cache time to live
kwargs – Fx filters to filter hosts to retrieve connections for
- Returns
dictionary keyed by device name with connections details
Warning
Get connections only supported for Netbox of 3.4 and above.
Note
Either
hostsor__salt__withFxfilters should be provided, otherwiseCommandExecutionErrorraised.Get connections returns a dictionary keyed by device name with value being a dictionary keyed by device interface names.
Sample return data:
{'fceos4': {'ConsolePort1': {'breakout': False, 'cable': {'custom_fields': {}, 'label': '', 'length': None, 'length_unit': None, 'peer_device': 'fceos5', 'peer_interface': 'ConsoleServerPort1', 'peer_termination_type': 'consoleserverport', 'status': 'CONNECTED', 'tags': [], 'tenant': {'name': 'SALTNORNIR'}, 'type': 'CAT6A'}, 'remote_device': 'fceos5', 'remote_interface': 'ConsoleServerPort1', 'remote_termination_type': 'consoleserverport', 'termination_type': 'consoleport'}, 'eth1': {'breakout': True, 'cable': {'custom_fields': {}, 'label': '', 'length': None, 'length_unit': None, 'peer_device': 'fceos5', 'peer_interface': ['eth1', 'eth10'], 'peer_termination_type': 'interface', 'status': 'CONNECTED', 'tags': [], 'tenant': {'name': 'SALTNORNIR'}, 'type': 'CAT6A'}, 'remote_device': 'fceos5', 'remote_interface': ['eth1', 'eth10'], 'remote_termination_type': 'interface', 'termination_type': 'interface'}, 'eth101': {'breakout': False, 'cable': {'custom_fields': {}, 'label': '', 'length': None, 'length_unit': None, 'peer_termination_type': 'circuittermination', 'status': 'CONNECTED', 'tags': [], 'tenant': None, 'type': 'SMF'}, 'circuit': {'cid': 'CID1', 'commit_rate': None, 'custom_fields': {}, 'description': '', 'provider': {'name': 'Provider1'}, 'status': 'ACTIVE', 'tags': []}, 'remote_device': 'fceos5', 'remote_interface': 'eth8', 'remote_termination_type': 'interface', 'termination_type': 'interface'}, 'eth3': {'breakout': False, 'cable': {'custom_fields': {}, 'label': '', 'length': None, 'length_unit': None, 'peer_device': 'fceos5', 'peer_interface': 'eth3', 'peer_termination_type': 'interface', 'status': 'CONNECTED', 'tags': [], 'tenant': {'name': 'SALTNORNIR'}, 'type': 'CAT6A'}, 'remote_device': 'fceos5', 'remote_interface': 'eth3', 'remote_termination_type': 'interface', 'termination_type': 'interface'}, 'eth7': {'breakout': False, 'cable': {'custom_fields': {}, 'label': '', 'length': None, 'length_unit': None, 'peer_device': 'PatchPanel-1', 'peer_interface': 'FrontPort1', 'peer_termination_type': 'frontport', 'status': 'CONNECTED', 'tags': [], 'tenant': {'name': 'SALTNORNIR'}, 'type': 'SMF'}, 'remote_device': 'fceos5', 'remote_interface': 'eth7', 'remote_termination_type': 'interface', 'termination_type': 'interface'}}}}
Where:
ConsolePort1is a direct cable between deviceseth101has circuit connected to iteth1is a direct between devices breakout cableeth3is a direct between devices normal (non-breakout) cableeth7connected to another device through patch panels
- salt_nornir.netbox_utils.get_circuits(params=None, sync=False, __salt__=None, proxy_id=None, hosts=None, cache=True, cache_ttl=3600, get_interface_details=True, **kwargs) dict
Function to retrieve circuits details from Netbox
- Parameters
params – dictionary with salt_nornir_netbox parameters
sync – if True, saves get circuits results to host’s in-memory inventory data under
circuitskey, if sync is a string, provided value used as a key.__salt__ – reference to
__salt__execution modules dictionaryhosts – list of hosts to get circuits for
cache – boolean indicating whether to cache Netbox response or string
refreshto delete cached data, if set to False cached data ignored but not refreshedcache_ttl – integer indicating cache time to live
kwargs – Fx filters to filter hosts to retrieve circuits for
get_interface_details – boolen, indicating if need to retrieve interface details, inventory items and IP addresses
- Returns
dictionary keyed by device name with circuits details
Circuits data retrived for a set of hosts first by queriyng netbox for a list of sites where hosts belongs to, next all circuits for given sites retrived from Netbox using GraphQL API, after that for each circuit one of the terminations path traced using REST API endpoint - /api/circuits/circuit-terminations/{id}/paths/. Once full path for the circuit retrived interface and device details extracted from path data for each end and stored in circuits data.
When get_interface_details set to True interface details retrieved from Netbox using get_interfaces function together with inventory items, child interfaces and IP addresses. For each IP address peer_ip calculated and added to IP data if subnet is one of prefix length - /30, /31, /127, /126, /120 by calculating second IP value.
When circuit connects to provider network, no interface, instead of remote_device and remote_interface keys, circuit contains provider_network key with value referring to provider network name.
Sample circuits data with
get_interface_detailsset to True:{'CID2': {'comments': 'some comments', 'commit_rate': 10000, 'custom_fields': {}, 'description': 'some description', 'interface': {'bridge': None, 'bridge_interfaces': [], 'custom_fields': {}, 'description': '', 'duplex': None, 'enabled': True, 'inventory_items': [], 'ip_addresses': [{'address': '10.0.1.1/30', 'custom_fields': {}, 'description': '', 'dns_name': '', 'last_updated': '2023-08-06T01:15:09.847777+00:00', 'peer_ip': '10.0.1.2/30', 'role': None, 'status': 'ACTIVE', 'tags': [], 'tenant': None}], 'last_updated': '2023-08-06T01:15:09.790266+00:00', 'mac_address': None, 'member_interfaces': [], 'mode': None, 'mtu': None, 'name': 'eth11', 'parent': None, 'speed': None, 'tagged_vlans': [], 'tags': [], 'untagged_vlan': None, 'vrf': 'OOB_CTRL', 'wwn': None}, 'is_active': True, 'provider': 'Provider1', 'provider_account': '', 'remote_device': 'fceos5', 'remote_interface': 'eth11', 'status': 'ACTIVE', 'subinterfaces': {'eth11.123': {'bridge': None, 'bridge_interfaces': [], 'child_interfaces': [{'name': 'eth123.123'}], 'custom_fields': {}, 'description': '', 'duplex': None, 'enabled': True, 'inventory_items': [], 'ip_addresses': [{'address': '10.0.0.1/30', 'custom_fields': {}, 'description': '', 'dns_name': '', 'last_updated': '2023-08-06T01:15:09.227279+00:00', 'peer_ip': '10.0.0.2/30', 'role': None, 'status': 'ACTIVE', 'tags': [], 'tenant': None}], 'last_updated': '2023-08-06T01:15:09.175047+00:00', 'mac_address': None, 'member_interfaces': [], 'mode': None, 'mtu': None, 'parent': {'name': 'eth11'}, 'speed': None, 'tagged_vlans': [], 'tags': [], 'untagged_vlan': None, 'vrf': 'MGMT', 'wwn': None}}, 'tags': ['ACCESS'], 'tenant': None, 'type': 'DarkFibre'}, }
- salt_nornir.netbox_utils.parse_config(__salt__=None, proxy_id=None, **kwargs)
Function to return results of devices configuration parsing produced by TTP Templates for Netbox.
- Parameters
__salt__ – reference to
__salt__execution modules dictionarykwargs – dictionary of Fx filters
- salt_nornir.netbox_utils.update_config_context(__salt__=None, proxy_id=None, **kwargs)
Function to populate device configuration context with parsed results.
- Parameters
__salt__ – reference to
__salt__execution modules dictionary
- salt_nornir.netbox_utils.update_vrf(__salt__=None, proxy_id=None, **kwargs)
Function to create or update VRFs and Route-Targets in Netbox.
This function creates or updates:
VRFs with their names and description (if present in confiugration)
Route-Targets values
Reference to import and export RT for VRFs
- Parameters
__salt__ – reference to
__salt__execution modules dictionary