Skip to content

Netbox Update Device IP Task¤

task api name: update_device_ip

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

How it works - Netbox worker on a call to update IP addresses task fetches live data from network devices using nominated datasource, by default it is Nornir service parse task using NAPALM get_interfaces_ip 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 IP addresses

  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 IP addresses data back to Netbox Service worker

  5. Netbox worker processes device data and updates or creates IP address records in Netbox for requested devices

Branching Support¤

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

Limitations¤

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

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

Update Device IP Sample Usage¤

NORFAB Netbox Update Device IP Command Shell Reference¤

NorFab shell supports these command options for Netbox update_device_ip task:

nf# man tree netbox.update.device.ip-addresses
root
└── netbox:    Netbox service
    └── update:    Update Netbox data
        └── device:    Update device data
            └── ip-addresses:    Update device interface IP addresses
                ├── 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 the IP addresses of devices in Netbox.

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.

False
datasource str

The data source to use. Supported datasources:

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

The timeout for the operation.

60
devices list

The list of devices to update.

None
create bool

If True, new IP addresses 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.

{}

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
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
@Task(fastapi={"methods": ["PATCH"]})
def update_device_ip(
    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 the IP addresses of devices in Netbox.

    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.
        datasource (str, optional): The data source to use. Supported datasources:

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

        timeout (int, optional): The timeout for the operation.
        devices (list, optional): The list of devices to update.
        create (bool, optional): If True, new IP addresses 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.

    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_ip", 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_ip"
            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_ip failed, errors: {'; '.join(results['errors'])}"
                    )
                    continue
                for host, host_data in results["result"].items():
                    updated, created = {}, {}
                    result[host] = {
                        "updated_ip_dry_run" if dry_run else "updated_ip": updated,
                        "created_ip_dry_run" if dry_run else "created_ip": created,
                    }
                    if branch is not None:
                        result[host]["branch"] = branch
                    interfaces = host_data["napalm_get"]["get_interfaces_ip"]
                    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 interface IP addresses
                    for nb_interface in nb_interfaces:
                        if nb_interface.name not in interfaces:
                            continue
                        interface = interfaces.pop(nb_interface.name)
                        # merge v6 into v4 addresses to save code repetition
                        ips = {
                            **interface.get("ipv4", {}),
                            **interface.get("ipv6", {}),
                        }
                        # update/create IP addresses
                        for ip, ip_data in ips.items():
                            prefix_length = ip_data["prefix_length"]
                            # get IP address info from Netbox
                            nb_ip = nb.ipam.ip_addresses.filter(
                                address=f"{ip}/{prefix_length}"
                            )
                            if len(nb_ip) > 1:
                                log.warning(
                                    f"{host} got multiple {ip}/{prefix_length} IP addresses from Netbox, "
                                    f"NorFab Netbox Service only supports handling of non-duplicate IPs."
                                )
                                continue
                            # decide what to do
                            if not nb_ip and create is False:
                                continue
                            elif not nb_ip and create is True:
                                if dry_run is not True:
                                    try:
                                        nb_ip = nb.ipam.ip_addresses.create(
                                            address=f"{ip}/{prefix_length}"
                                        )
                                    except Exception as e:
                                        msg = f"{host} failed to create {ip}/{prefix_length}, error: {e}"
                                        log.error(msg)
                                        job.event(msg, resource=instance)
                                        continue
                                    nb_ip.assigned_object_type = "dcim.interface"
                                    nb_ip.assigned_object_id = nb_interface.id
                                    nb_ip.status = "active"
                                    nb_ip.save()
                                created[f"{ip}/{prefix_length}"] = nb_interface.name
                                job.event(
                                    f"{host} created IP address {ip}/{prefix_length} for {nb_interface.name} interface",
                                    resource=instance,
                                )
                            elif nb_ip:
                                nb_ip = list(nb_ip)[0]
                                if dry_run is not True:
                                    nb_ip.assigned_object_type = "dcim.interface"
                                    nb_ip.assigned_object_id = nb_interface.id
                                    nb_ip.status = "active"
                                    nb_ip.save()
                                updated[nb_ip.address] = nb_interface.name
                                job.event(
                                    f"{host} updated IP address {ip}/{prefix_length} for {nb_interface.name} interface",
                                    resource=instance,
                                )

    else:
        raise UnsupportedServiceError(
            f"'{datasource}' datasource service not supported"
        )

    return ret