Skip to content

Netbox Update Device Interfaces Task¤

task api name: update_device_interfaces

The Netbox Update Device Interfaces Task is a feature of the NorFab Netbox Service that allows you to synchronize and update the interface data of your network devices in Netbox. This task ensures that the interface configurations in Netbox are accurate and up-to-date, reflecting the current state of your network infrastructure.

Keeping interface data accurate and up-to-date is crucial for effective network management. The Netbox Update Device Interfaces Task automates the process of updating interface information, such as interface names, statuses, mac addresses, and other relevant details.

Branching Support¤

Update device interfaces task is branch aware and can push updates to the branch. Netbox Branching Plugin need to be installed on Netbox instance.

How it works - Netbox worker on a call to update interfaces task fetches live data from network devices using nominated datasource, by default it is Nornir service parse task using NAPALM get_interfaces getter. Once data retrieved from network, Netbox worker updates records in Netbox database for device interfaces.

Netbox Update Device Interfaces

  1. Client submits and on-demand request to NorFab Netbox worker to update device interfaces

  2. Netbox worker sends job request to nominated datasource service to fetch live data from network devices

  3. Datasource service fetches data from the network

  4. Datasource returns devices interfaces data back to Netbox Service worker

  5. Netbox worker processes device interfaces data and updates records in Netbox for requested devices

Limitations¤

Datasource nornir uses NAPALM get_interfaces getter and as such only supports these device platforms:

  • Arista EOS
  • Cisco IOS
  • Cisco IOSXR
  • Cisco NXOS
  • Juniper JUNOS

Update Device Interfaces Sample Usage¤

NORFAB Netbox Update Device Interfaces Command Shell Reference¤

NorFab shell supports these command options for Netbox update_device_interfaces task:

nf# man tree netbox.update.device.interfaces
root
└── netbox:    Netbox service
    └── update:    Update Netbox data
        └── device:    Update device data
            └── interfaces:    Update device interfaces
                ├── timeout:    Job timeout
                ├── workers:    Filter worker to target, default 'any'
                ├── verbose-result:    Control output details, default 'False'
                ├── progress:    Display progress events, default 'True'
                ├── instance:    Netbox instance name to target
                ├── dry-run:    Return information that would be pushed to Netbox but do not push it
                ├── devices:    List of Netbox devices to update
                ├── datasource:    Service to use to retrieve device data, default 'nornir'
                │   └── nornir:    Use Nornir service to retrieve data from devices
                │       ├── FO:    Filter hosts using Filter Object
                │       ├── FB:    Filter hosts by name using Glob Patterns
                │       ├── FH:    Filter hosts by hostname
                │       ├── FC:    Filter hosts containment of pattern in name
                │       ├── FR:    Filter hosts by name using Regular Expressions
                │       ├── FG:    Filter hosts by group
                │       ├── FP:    Filter hosts by hostname using IP Prefix
                │       ├── FL:    Filter hosts by names list
                │       ├── FM:    Filter hosts by platform
                │       ├── FN:    Negate the match
                │       ├── add-details:    Add task details to results, default 'False'
                │       ├── num-workers:    RetryRunner number of threads for tasks execution
                │       ├── num-connectors:    RetryRunner number of threads for device connections
                │       ├── connect-retry:    RetryRunner number of connection attempts
                │       ├── task-retry:    RetryRunner number of attempts to run task
                │       ├── reconnect-on-fail:    RetryRunner perform reconnect to host on task failure
                │       ├── connect-check:    RetryRunner test TCP connection before opening actual connection
                │       ├── connect-timeout:    RetryRunner timeout in seconds to wait for test TCP connection to establish
                │       ├── creds-retry:    RetryRunner list of connection credentials and parameters to retry
                │       ├── tf:    File group name to save task results to on worker file system
                │       ├── tf-skip-failed:    Save results to file for failed tasks
                │       ├── diff:    File group name to run the diff for
                │       ├── diff-last:    File version number to diff, default is 1 (last)
                │       └── progress:    Display progress events, default 'True'
                ├── batch-size:    Number of devices to process at a time, default '10'
                └── branch:    Branching plugin branch name to use
nf#

Python API Reference¤

Update or create device interfaces in Netbox. Interface parameters updated:

  • interface name
  • interface description
  • mtu
  • mac address
  • admin status
  • speed

Parameters:

Name Type Description Default
job Job

NorFab Job object containing relevant metadata.

required
instance str

The Netbox instance name to use.

None
dry_run bool

If True, no changes will be made to Netbox.

False
datasource str

The data source to use. Supported datasources:

  • nornir - uses Nornir Service parse task to retrieve devices' data using NAPALM get_interfaces getter
'nornir'
timeout int

The timeout for the job.

60
devices list

List of devices to update.

None
create bool

If True, new interfaces will be created if they do not exist.

True
batch_size int

The number of devices to process in each batch.

10
branch str

Branch name to use, need to have branching plugin installed, automatically creates branch if it does not exist in Netbox.

None
**kwargs

Additional keyword arguments to pass to the datasource job.

{}

Returns:

Name Type Description
dict Result

A dictionary containing the results of the update operation.

Raises:

Type Description
Exception

If a device does not exist in Netbox.

UnsupportedServiceError

If the specified datasource is not supported.

Source code in norfab\workers\netbox_worker.py
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
@Task(fastapi={"methods": ["PATCH"]})
def update_device_interfaces(
    self,
    job: Job,
    instance: Union[None, str] = None,
    dry_run: bool = False,
    datasource: str = "nornir",
    timeout: int = 60,
    devices: Union[None, list] = None,
    create: bool = True,
    batch_size: int = 10,
    branch: str = None,
    **kwargs,
) -> Result:
    """
    Update or create device interfaces in Netbox. Interface parameters updated:

    - interface name
    - interface description
    - mtu
    - mac address
    - admin status
    - speed

    Args:
        job: NorFab Job object containing relevant metadata.
        instance (str, optional): The Netbox instance name to use.
        dry_run (bool, optional): If True, no changes will be made to Netbox.
        datasource (str, optional): The data source to use. Supported datasources:

            - **nornir** - uses Nornir Service parse task to retrieve devices' data
                using NAPALM get_interfaces getter

        timeout (int, optional): The timeout for the job.
        devices (list, optional): List of devices to update.
        create (bool, optional): If True, new interfaces will be created if they do not exist.
        batch_size (int, optional): The number of devices to process in each batch.
        branch (str, optional): Branch name to use, need to have branching plugin installed,
            automatically creates branch if it does not exist in Netbox.
        **kwargs: Additional keyword arguments to pass to the datasource job.

    Returns:
        dict: A dictionary containing the results of the update operation.

    Raises:
        Exception: If a device does not exist in Netbox.
        UnsupportedServiceError: If the specified datasource is not supported.
    """
    result = {}
    devices = devices or []
    instance = instance or self.default_instance
    ret = Result(
        task=f"{self.name}:update_device_interfaces",
        result=result,
        resources=[instance],
    )
    nb = self._get_pynetbox(instance, branch=branch)

    if datasource == "nornir":
        # source hosts list from Nornir
        if kwargs:
            devices.extend(self.get_nornir_hosts(kwargs, timeout))
        # iterate over devices in batches
        for i in range(0, len(devices), batch_size):
            kwargs["FL"] = devices[i : i + batch_size]
            kwargs["getters"] = "get_interfaces"
            data = self.client.run_job(
                "nornir",
                "parse",
                kwargs=kwargs,
                workers="all",
                timeout=timeout,
            )
            for worker, results in data.items():
                if results["failed"]:
                    log.error(
                        f"{worker} get_interfaces failed, errors: {'; '.join(results['errors'])}"
                    )
                    continue
                for host, host_data in results["result"].items():
                    updated, created = {}, {}
                    result[host] = {
                        (
                            "update_device_interfaces_dry_run"
                            if dry_run
                            else "update_device_interfaces"
                        ): updated,
                        (
                            "created_device_interfaces_dry_run"
                            if dry_run
                            else "created_device_interfaces"
                        ): created,
                    }
                    if branch is not None:
                        result[host]["branch"] = branch
                    interfaces = host_data["napalm_get"]["get_interfaces"]
                    nb_device = nb.dcim.devices.get(name=host)
                    if not nb_device:
                        raise Exception(f"'{host}' does not exist in Netbox")
                    nb_interfaces = nb.dcim.interfaces.filter(
                        device_id=nb_device.id
                    )
                    # update existing interfaces
                    for nb_interface in nb_interfaces:
                        if nb_interface.name not in interfaces:
                            continue
                        interface = interfaces.pop(nb_interface.name)
                        if dry_run is not True:
                            nb_interface.description = interface["description"]
                            if interface["mtu"] > 0:
                                nb_interface.mtu = interface["mtu"]
                            if interface["speed"] > 0:
                                nb_interface.speed = interface["speed"] * 1000
                            if interface["mac_address"].strip().lower() not in [
                                "none",
                                "",
                            ]:
                                mac_address = interface["mac_address"]
                                if self.nb_version[instance] >= (4, 2, 0):
                                    try:
                                        nb_mac_addr = nb.dcim.mac_addresses.get(
                                            mac_address=mac_address,
                                            interface_id=nb_interface.id,
                                        )
                                    except Exception as e:
                                        msg = f"{worker} failed to get {mac_address} mac-address from netbox: {e}"
                                        job.event(msg, severity="WARNING")
                                        ret.messages.append(msg)
                                        log.error(msg)
                                    else:
                                        if not nb_mac_addr:
                                            nb_mac_addr = nb.dcim.mac_addresses.create(
                                                mac_address=mac_address,
                                                assigned_object_type="dcim.interface",
                                                assigned_object_id=nb_interface.id,
                                            )
                                        elif not nb_mac_addr.assigned_object_id:
                                            nb_mac_addr.assigned_object_type = (
                                                "dcim.interface"
                                            )
                                            nb_mac_addr.assigned_object_id = (
                                                nb_interface.id
                                            )
                                        if not nb_interface.primary_mac_address:
                                            nb_interface.primary_mac_address = (
                                                nb_mac_addr.id
                                            )
                                            job.event(
                                                f"{host} {mac_address} MAC associating with interface {nb_interface.name}",
                                                resource=instance,
                                            )
                                    nb_interface.mac_address = mac_address
                            nb_interface.enabled = interface["is_enabled"]
                            nb_interface.save()
                        updated[nb_interface.name] = interface
                        job.event(
                            f"{host} updated interface {nb_interface.name}",
                            resource=instance,
                        )
                    # create new interfaces
                    if create is not True:
                        continue
                    for interface_name, interface in interfaces.items():
                        interface["type"] = "other"
                        if dry_run is not True:
                            nb_interface = nb.dcim.interfaces.create(
                                name=interface_name,
                                device={"name": nb_device.name},
                                type=interface["type"],
                            )
                            nb_interface.description = interface["description"]
                            if interface["mtu"] > 0:
                                nb_interface.mtu = interface["mtu"]
                            if interface["speed"] > 0:
                                nb_interface.speed = interface["speed"] * 1000
                            # create MAC address
                            if interface["mac_address"].strip().lower() not in [
                                "none",
                                "",
                            ]:
                                mac_address = interface["mac_address"]
                                if self.nb_version[instance] >= (4, 2, 0):
                                    try:
                                        nb_mac_addr = nb.dcim.mac_addresses.create(
                                            mac_address=mac_address,
                                            assigned_object_type="dcim.interface",
                                            assigned_object_id=nb_interface.id,
                                        )
                                    except Exception as e:
                                        msg = f"{host} {mac_address} MAC failed to create, interface {nb_interface.name}: {e}"
                                        job.event(msg, severity="WARNING")
                                        ret.messages.append(msg)
                                        log.error(msg)
                                    else:
                                        nb_interface.primary_mac_address = (
                                            nb_mac_addr.id
                                        )
                                else:
                                    nb_interface.mac_address = mac_address
                                job.event(
                                    f"{host} {mac_address} MAC created, associating with interface {nb_interface.name}",
                                    resource=instance,
                                )
                            nb_interface.enabled = interface["is_enabled"]
                            nb_interface.save()
                        created[interface_name] = interface
                        job.event(
                            f"{host} created interface {interface_name}",
                            resource=instance,
                        )
    else:
        raise UnsupportedServiceError(
            f"'{datasource}' datasource service not supported"
        )

    return ret