Netbox Sync Device Interfaces Task

task api name: sync_device_interfaces

The Netbox Sync Device Interfaces Task synchronizes device interface configuration from live network devices into NetBox using a normalized desired/current state model and DeepDiff-driven reconciliation. The task computes an explicit action plan and applies interface create, update, and delete operations in a safe dependency order.

How It Works

The task follows a four-step pipeline:

1. Fetch — Pull current interface state from NetBox for the target devices.
2. Collect live state — Run a Nornir parse_ttp job against the devices to collect real interface attributes (type, enabled, MTU, VLANs, VRF, mode, parent, LAG membership, etc.).
3. Diff — Normalize both sides to a common schema and compare using DeepDiff to classify each interface as create, update, delete, or in_sync.
4. Reconcile — Apply changes to NetBox in dependency order to avoid constraint errors:
   1. Create LAG interfaces first
   2. Create parent (non-child) interfaces
   3. Create child (sub)interfaces referencing their parents
   4. Bulk update changed interfaces
   5. Delete interfaces present in NetBox but absent in live data (only when process_deletions=True)

1. Client submits an on-demand request to the NorFab Netbox worker to sync device interfaces
2. Netbox worker sends a job request to the Nornir service to fetch live interface data from devices
3. Nornir service collects interface data from the network using parse_ttp
4. Nornir returns normalized interface data to the Netbox worker
5. Netbox worker applies planned actions and returns per-device action summaries and field-level diffs

Output

Dry-run mode (dry_run=True) returns the diff plan without making any changes, keyed by device name:

{
    "<device>": {
        "create": ["Loopback99", "Port-Channel41"],
        "update": {
            "Ethernet1": {
                "description": {"old_value": "old desc", "new_value": "new desc"}
            }
        },
        "delete": ["StaleInterface"],
        "in_sync": ["Loopback0", "Ethernet2"]
    }
}

With Approval — Pass with_approval=True to use interactive NFCLI workflow. Sync task displays its preview, and waits for approval before applying changes. Declining at that point will return dry-run result.

Note

When both dry-run and with_approval are True, dry-run logic ignored.

Live-run mode (dry_run=False, default) applies changes and returns a summary of actions taken:

{
    "<device>": {
        "created": ["Loopback99", "Port-Channel41"],
        "updated": ["Ethernet1"],
        "deleted": ["StaleInterface"],
        "in_sync": ["Loopback0", "Ethernet2"]
    }
}

In live-run mode res["diff"] is also populated with field-level change details for all interfaces that were created or updated.

Filtering

Interfaces can be scoped using glob patterns so that only a subset is considered on both the live and NetBox sides:

• filter_by_name — match interface names, e.g. "Loopback*" or "Ethernet[1-4]"
• filter_by_description — match interface descriptions, e.g. "uplink*" or "TEST_SYNC_*"

Both filters are applied before the diff, so interfaces that do not match are completely ignored by the sync — they are neither created, updated, nor deleted.

Deletion Behavior

By default process_deletions=False — interfaces present in NetBox but absent in live data are left untouched. Set process_deletions=True to enable deletion. Child interfaces are always deleted before their parents to avoid foreign-key constraint errors.

Branching Support

The task is branch-aware and can push changes into a NetBox branch. The Netbox Branching Plugin must be installed. Specify the branch parameter; the branch is created automatically if it does not already exist.

Examples

CLIPython

Sync interfaces for a list of devices:

nf#netbox sync interfaces devices ceos-spine-1 ceos-spine-2

Preview changes without writing to NetBox (dry run):

nf#netbox sync interfaces devices ceos-spine-1 dry-run

Sync and delete interfaces absent from live data:

nf#netbox sync interfaces devices ceos-spine-1 ceos-spine-2 process-deletions

Restrict sync to loopback interfaces only:

nf#netbox sync interfaces devices ceos-spine-1 filter-by-name "Loopback*"

Restrict sync to interfaces whose description matches a glob pattern:

nf#netbox sync interfaces devices ceos-spine-1 filter-by-description "TEST_SYNC_*"

Sync interfaces into a NetBox branch:

nf#netbox sync interfaces devices ceos-spine-1 ceos-spine-2 branch sprint-42-interfaces

Sync using Nornir host filters instead of explicit device names:

nf#netbox sync interfaces FC spine

from norfab.core.nfapi import NorFab

nf = NorFab(inventory="./inventory.yaml")
nf.start()
client = nf.make_client()

# sync interfaces for specific devices
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1", "ceos-spine-2"],
    },
)

# dry run — preview creates/updates/deletes without writing
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1", "ceos-spine-2"],
        "dry_run": True,
    },
)

# sync and delete interfaces absent from live data
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1"],
        "process_deletions": True,
    },
)

# restrict sync to loopback interfaces only
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1"],
        "filter_by_name": "Loopback*",
    },
)

# restrict sync to interfaces with a specific description pattern
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1"],
        "process_deletions": True,
        "filter_by_description": "TEST_SYNC_*",
    },
)

# sync into a NetBox branch
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["ceos-spine-1", "ceos-spine-2"],
        "branch": "sprint-42-interfaces",
    },
)

# use Nornir host filters instead of explicit device names
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "FC": "spine",
    },
)

nf.destroy()

NORFAB Netbox Sync Device Interfaces Command Shell Reference

NorFab shell supports these command options for the sync_device_interfaces task:

nf# man tree netbox.sync.interfaces
root
└── netbox:    Netbox service
    └── sync:    Sync Netbox data
        └── interfaces:    Sync device interfaces with NetBox
            ├── timeout:    Job timeout in seconds
            ├── 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 diff plan without pushing changes to NetBox
            ├── devices:    List of NetBox device names to sync
            ├── process-deletions:    Delete interfaces present in NetBox but absent in live data
            ├── filter-by-name:    Glob pattern to restrict sync by interface name, e.g. 'Loopback*'
            ├── filter-by-description:    Glob pattern to restrict sync by interface description
            ├── branch:    Branching plugin branch name to push changes into
            ├── FO:    Filter Nornir hosts using Filter Object
            ├── FB:    Filter Nornir hosts by name using Glob Patterns
            ├── FH:    Filter Nornir hosts by hostname
            ├── FC:    Filter Nornir hosts by name containment
            ├── FR:    Filter Nornir hosts by name using Regular Expressions
            ├── FG:    Filter Nornir hosts by group
            ├── FP:    Filter Nornir hosts by hostname using IP Prefix
            ├── FL:    Filter Nornir hosts by names list
            ├── FM:    Filter Nornir hosts by platform
            └── FN:    Negate the Nornir host filter match
nf#

Python API Reference

Synchronize device interface configuration from live devices into NetBox using a normalized state model and DeepDiff-based reconciliation.

The task follows a four-step pipeline:

1. Fetch: Pull current interface state from NetBox (source of truth).
2. Collect live state: Run a Nornir parse_ttp get interfaces job against devices to collect live interface attributes (type, enabled, MTU, VLANs, VRF, etc.).
3. Diff: Compare normalized NetBox state against normalized live state using DeepDiff to classify each interface as create, update, delete, or in_sync.
4. Reconcile: Apply changes to NetBox in a safe order — LAG interfaces first, then parent interfaces, then child (sub)interfaces, then updates, and finally deletions (only when process_deletions=True).

Side-Effects

• Sync interfaces task creates VRFs if they do not exist in Netbox
• Sync interfaces task creates VLANs if they do not exist in Netbox

Prerequisites

• Device must exist in Netbox
• If specified, vlan group must exist in Netbox

Limitations

• Sync interfaces task does not handles IP Addresses
• Sync interfaces task does not handles MAC Addresses
• Sync interfaces uses devices running configuration to pull interfaces data, interfaces operational state data not used

Dry-run mode (dry_run=True): returns the raw diff plan without making any changes. Result is keyed by device name::

{
    "<device>": {
        "create": ["Loopback99", ...],
        "update": {"Ethernet1": {"description": {"old_value": "x", "new_value": "y"}}},
        "delete": ["StrayIface"],
        "in_sync": ["Loopback0", ...]
    }
}

Live-run mode (dry_run=False, default): applies changes and returns a summary of what was done, keyed by device name::

{
    "<device>": {
        "created": ["Loopback99"],
        "updated": ["Ethernet1"],
        "deleted": ["StrayIface"],
        "in_sync": ["Loopback0", ...]
    }
}

In non dry-run mode res["diff"] contains difference detail for interfaces that were (or would be) created/updated/deleted.

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
with_approval	bool	Preview changes, ask for review, then apply them.	False
timeout	int	Timeout in seconds for the Nornir parse_ttp job.	600
devices	list	List of device names to sync.	None
process_deletions	bool	If True, delete interfaces present in NetBox but absent in live data. Defaults to False (safe by default).	False
branch	str	NetBox branch name to use. The branching plugin must be installed. The branch is created automatically if it does not exist.	None
filter_by_name	str	Glob pattern to restrict which interfaces are included by name, e.g. 'Loopback*' or 'Eth*'.	None
filter_by_description	str	Glob pattern to restrict which interfaces are included by description, e.g. 'uplink*'.	None
update_type	(str, boolean)	update existing interfaces types or not, sync interfaces task unable to fully resolve interface types and defaults to interface type other for most interfaces, this knob allows to keep existing Netbox interfaces type intact.	False
vlan_group	(str, int)	VLAN group name, slug, or ID to use when resolving interface VLANs. Missing VLANs are created in this group; otherwise they are created in the device site.	None
**kwargs	Any	Additional Nornir host filter keyword arguments passed to parse_ttp (e.g. FL, FC, FB).	{}

Returns:

Name	Type	Description
dict	Result	Per-device action summary. Structure depends on dry_run; see above. Diff details are available in res["diff"] for non dry-run mode.

Source code in norfab\workers\netbox_worker\interfaces_tasks.py

@Task(
    fastapi={"methods": ["PATCH"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=SyncDeviceInterfacesInput,
    output=SyncDeviceInterfacesResult,
    mcp={
        "annotations": {
            "title": "Sync Device Interfaces",
            "readOnlyHint": False,
            "destructiveHint": True,
            "idempotentHint": True,
            "openWorldHint": True,
        }
    },
)
def sync_device_interfaces(
    self,
    job: Job,
    instance: Union[None, str] = None,
    dry_run: bool = False,
    with_approval: bool = False,
    timeout: int = 600,
    devices: Union[None, list] = None,
    process_deletions: bool = False,
    branch: str = None,
    filter_by_name: Union[None, str] = None,
    filter_by_description: Union[None, str] = None,
    update_type: Union[None, bool] = False,
    vlan_group: Union[None, str, int] = None,
    **kwargs: Any,
) -> Result:
    """
    Synchronize device interface configuration from live devices into NetBox using a
    normalized state model and DeepDiff-based reconciliation.

    The task follows a four-step pipeline:

    1. **Fetch**: Pull current interface state from NetBox (source of truth).
    2. **Collect live state**: Run a Nornir ``parse_ttp`` get interfaces job against
       devices to collect live interface attributes (type, enabled, MTU, VLANs, VRF, etc.).
    3. **Diff**: Compare normalized NetBox state against normalized live state using
       DeepDiff to classify each interface as ``create``, ``update``, ``delete``, or
       ``in_sync``.
    4. **Reconcile**: Apply changes to NetBox in a safe order — LAG interfaces
       first, then parent interfaces, then child (sub)interfaces, then updates,
       and finally deletions (only when ``process_deletions=True``).

    **Side-Effects**

    - Sync interfaces task creates VRFs if they do not exist in Netbox
    - Sync interfaces task creates VLANs if they do not exist in Netbox

    **Prerequisites**

    - Device must exist in Netbox
    - If specified, vlan group must exist in Netbox

    **Limitations**

    - Sync interfaces task does not handles IP Addresses
    - Sync interfaces task does not handles MAC Addresses
    - Sync interfaces uses devices running configuration to pull interfaces data, interfaces
      operational state data not used

    **Dry-run mode** (``dry_run=True``): returns the raw diff plan without making
    any changes. Result is keyed by device name::

    ```
    {
        "<device>": {
            "create": ["Loopback99", ...],
            "update": {"Ethernet1": {"description": {"old_value": "x", "new_value": "y"}}},
            "delete": ["StrayIface"],
            "in_sync": ["Loopback0", ...]
        }
    }
    ```

    **Live-run mode** (``dry_run=False``, default): applies changes and returns a summary
    of what was done, keyed by device name::

    ```
    {
        "<device>": {
            "created": ["Loopback99"],
            "updated": ["Ethernet1"],
            "deleted": ["StrayIface"],
            "in_sync": ["Loopback0", ...]
        }
    }
    ```

    In non dry-run mode ``res["diff"]`` contains difference detail
    for interfaces that were (or would be) created/updated/deleted.

    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.
        with_approval (bool, optional): Preview changes, ask for review, then apply them.
        timeout (int, optional): Timeout in seconds for the Nornir parse_ttp job.
        devices (list, optional): List of device names to sync.
        process_deletions (bool, optional): If True, delete interfaces present in
            NetBox but absent in live data. Defaults to False (safe by default).
        branch (str, optional): NetBox branch name to use. The branching plugin
            must be installed. The branch is created automatically if it does
            not exist.
        filter_by_name (str, optional): Glob pattern to restrict which interfaces
            are included by name, e.g. ``'Loopback*'`` or ``'Eth*'``.
        filter_by_description (str, optional): Glob pattern to restrict which
            interfaces are included by description, e.g. ``'uplink*'``.
        update_type (str, boolean): update existing interfaces types or not,
            sync interfaces task unable to fully resolve interface types and
            defaults to interface type `other` for most interfaces, this knob
            allows to keep existing Netbox interfaces type intact.
        vlan_group (str, int, optional): VLAN group name, slug, or ID to use
            when resolving interface VLANs. Missing VLANs are created in this
            group; otherwise they are created in the device site.
        **kwargs: Additional Nornir host filter keyword arguments passed to
            ``parse_ttp`` (e.g. ``FL``, ``FC``, ``FB``).

    Returns:
        dict: Per-device action summary. Structure depends on ``dry_run``; see
            above. Diff details are available in ``res["diff"]`` for non
            dry-run mode.
    """
    devices = devices or []
    instance = instance or self.default_instance
    ret = Result(
        task=f"{self.name}:sync_device_interfaces",
        result={},
        resources=[instance],
        dry_run=dry_run,
        diff={},
    )
    nb = self._get_pynetbox(instance, branch=branch)
    log.info(
        f"{self.name} - Sync device interfaces: Processing {len(devices)} device(s) in '{instance}'"
    )

    # Source additional hosts from Nornir filters.
    if kwargs:
        job.event("resolving devices from Nornir filters")
        nornir_hosts = self.get_nornir_hosts(kwargs, timeout)
        for host in nornir_hosts:
            if host not in devices:
                devices.append(host)
        job.event(
            f"resolved {len(nornir_hosts)} device(s) from Nornir filters, "
            f"{len(devices)} total device(s) selected"
        )

    if not devices:
        msg = "no devices specified"
        job.event(msg, severity="ERROR")
        ret.errors.append(msg)
        ret.failed = True
        return ret

    job.event(f"syncing interfaces for {len(devices)} devices, dry_run={dry_run}")

    # filter out devices not define in Netbox
    job.event(f"validating {len(devices)} device(s) exist in NetBox")
    nb_devices_data = {
        d.name: {"id": d.id, "site_id": d.site.id, "name": d.name}
        for d in self.bulk_filter(
            nb.dcim.devices, name=devices, fields="id,name,site"
        )
    }
    for d in list(devices):
        if d not in nb_devices_data:
            msg = f"{d} - device not found in Netbox"
            log.error(msg)
            job.event(msg, severity="ERROR")
            ret.errors.append(msg)
            devices.remove(d)
    if not devices:
        job.event(
            "no valid NetBox devices remain after validation", severity="ERROR"
        )
        ret.failed = True
        return ret
    job.event(f"validated {len(devices)} device(s) in NetBox")

    # Gather NetBox source of truth with interface IP/MAC details.
    job.event("fetching current interface data from NetBox")
    nb_interfaces_result = self.get_interfaces(
        job=job,
        instance=instance,
        branch=branch,
        devices=devices,
        ip_addresses=False,
        cache="refresh",
    )
    if nb_interfaces_result.errors:
        job.event("failed to fetch NetBox interface data", severity="ERROR")
        ret.errors.extend(nb_interfaces_result.errors)
        ret.failed = True
        return ret

    # Normalize NetBox interface data per device.
    job.event("normalising NetBox interface data")
    normalised_nb_all: dict = {}
    for device_name, interfaces in nb_interfaces_result.result.items():
        normalised_nb_all[device_name] = {}
        for intf_name, data in (interfaces or {}).items():
            if filter_by_name and not fnmatch.fnmatch(intf_name, filter_by_name):
                continue
            if filter_by_description and not fnmatch.fnmatch(
                str(data.get("description") or ""), filter_by_description
            ):
                continue
            tagged_vlans = sorted(
                v.get("vid")
                for v in (data.get("tagged_vlans") or [])
                if isinstance(v, dict) and v.get("vid") is not None
            )
            parent_name = (
                data["parent"].get("name")
                if isinstance(data.get("parent"), dict)
                else None
            )
            lag = (
                data["lag"].get("name")
                if isinstance(data.get("lag"), dict)
                else None
            )
            vrf_name = (
                data["vrf"].get("name")
                if isinstance(data.get("vrf"), dict)
                else None
            )
            normalised_nb_all[device_name][intf_name] = {
                "name": intf_name,
                "type": data["type"]["value"],
                "enabled": bool(data.get("enabled", True)),
                "parent": parent_name,
                "lag": lag,
                "mtu": data.get("mtu"),
                "speed": data.get("speed"),
                "duplex": data.get("duplex"),
                "description": str(data.get("description") or ""),
                "mode": (data.get("mode") or {}).get("value"),
                "untagged_vlan": (
                    data.get("untagged_vlan").get("vid")
                    if data.get("untagged_vlan")
                    else None
                ),
                "tagged_vlans": tagged_vlans,
                "qinq_svlan": (
                    data.get("qinq_svlan").get("vid")
                    if data.get("qinq_svlan")
                    else None
                ),
                "vrf": vrf_name,
            }
    nb_interface_count = sum(len(v) for v in normalised_nb_all.values())
    job.event(
        f"normalised {nb_interface_count} NetBox interface(s) after applying filters"
    )

    # Gather live source of truth from Nornir parse_ttp.
    job.event(f"retrieving live interfaces for {len(devices)} devices")
    parse_data = self.client.run_job(
        "nornir",
        "parse_ttp",
        kwargs={"get": "interfaces", "FL": devices},
        workers="all",
        timeout=timeout,
    )
    # Normalize live interface data per device.
    job.event("normalising live interface data")
    normalised_live_all = {}
    for wname, wdata in parse_data.items():
        if wdata.get("failed"):
            msg = f"{wname} - failed to parse interface data from devices"
            log.warning(msg)
            job.event(msg, severity="WARNING")
            continue
        for device_name, host_interfaces in wdata["result"].items():
            normalised_live_all.setdefault(device_name, {})
            for data in host_interfaces or []:
                intf_name = data["name"]
                if filter_by_name and not fnmatch.fnmatch(
                    intf_name, filter_by_name
                ):
                    continue
                if filter_by_description and not fnmatch.fnmatch(
                    str(data.get("description") or ""), filter_by_description
                ):
                    continue
                normalised_live_all[device_name][intf_name] = {
                    "name": intf_name,
                    "type": data["type"],
                    "enabled": bool(
                        data.get("enabled", data.get("is_enabled", True))
                    ),
                    "parent": data.get("parent"),
                    "lag": data.get("lag"),
                    "mtu": data.get("mtu"),
                    "speed": data.get("speed"),
                    "duplex": data.get("duplex"),
                    "description": str(data.get("description") or ""),
                    "mode": data.get("mode"),
                    "untagged_vlan": data.get("untagged_vlan"),
                    "tagged_vlans": data.get("tagged_vlans") or [],
                    "qinq_svlan": data.get("qinq_svlan"),
                    "vrf": data.get("vrf"),
                }
    live_interface_count = sum(len(v) for v in normalised_live_all.values())
    job.event(
        f"normalised {live_interface_count} live interface(s) after applying filters"
    )

    # remove devices that returned no parsing results
    for device_name in devices:
        if device_name not in normalised_live_all:
            msg = f"{device_name} - parsing returned no interfaces data, skipping device"
            log.error(msg)
            job.event(msg, severity="ERROR")
            _ = normalised_nb_all.pop(device_name)
    if not normalised_nb_all:
        job.event(
            "no interface parsing results collected for devices", severity="ERROR"
        )
        ret.failed = True
        ret.errors.append("no interfaces parsing results collected for devices")
        return ret

    # Single diff on the full normalised datasets
    job.event("calculating interface sync diff")
    full_diff = self.make_diff(normalised_live_all, normalised_nb_all)

    # remove interface type from updates
    if update_type is False:
        for dev_name, dev_diff in full_diff.items():
            for intf_name in list(dev_diff["update"].keys()):
                intf_updates = dev_diff["update"][intf_name]
                _ = intf_updates.pop("type", None)
                # remove interface from updates if nothing to update
                if not intf_updates:
                    _ = dev_diff["update"].pop(intf_name)
    create_count = sum(len(actions["create"]) for actions in full_diff.values())
    update_count = sum(len(actions["update"]) for actions in full_diff.values())
    delete_count = sum(len(actions["delete"]) for actions in full_diff.values())
    in_sync_count = sum(len(actions["in_sync"]) for actions in full_diff.values())
    job.event(
        "interface sync diff complete: "
        f"{create_count} create, {update_count} update, "
        f"{delete_count} delete, {in_sync_count} in sync"
    )

    if with_approval and not review_sync_task_result(
        job, "interface sync", full_diff
    ):
        ret.status = "skipped"
        ret.result = full_diff
        ret.dry_run = True
        ret.messages.append("review declined; changes were not applied")
        return ret
    elif dry_run is True:
        job.event(
            "dry-run requested, returning interface sync diff without changes"
        )
        ret.result = full_diff
        ret.dry_run = True
        return ret
    else:
        ret.diff = full_diff

    # Shared lookup cache for VLAN and VRF objects — avoids redundant NetBox
    # API calls when the same VID or VRF name appears across multiple interfaces.
    _lookup_cache: dict = {}

    # Per-device result tracking
    device_results = {
        device_name: {
            "created": [],
            "updated": [],
            "deleted": [],
            "in_sync": actions["in_sync"],
        }
        for device_name, actions in full_diff.items()
    }
    ret.result = device_results

    # create LAG interfaces
    job.event("preparing LAG interface create payloads")
    bulk_create_lag_interfaces = []
    for device_name, actions in full_diff.items():
        nb_device = nb_devices_data[device_name]
        for intf_name in actions["create"]:
            desired = normalised_live_all[device_name][intf_name]
            if desired["type"] == "lag":
                payload = _build_interface_payload(
                    job=job,
                    ret=ret,
                    worker_name=self.name,
                    desired=desired,
                    changed_fields=[
                        k for k in desired.keys() if desired[k] is not None
                    ],
                    device=nb_device,
                    name_to_id={},
                    intf_name=intf_name,
                    nb=nb,
                    _lookup_cache=_lookup_cache,
                    vlan_group=vlan_group,
                )
                bulk_create_lag_interfaces.append(payload)
    job.event(
        f"prepared {len(bulk_create_lag_interfaces)} LAG interface create payload(s)"
    )
    if bulk_create_lag_interfaces:
        job.event(f"creating LAG interfaces")
        try:
            nb.dcim.interfaces.create(bulk_create_lag_interfaces)
            job.event(f"created {len(bulk_create_lag_interfaces)} LAG interface(s)")
            for device_name, device_data in nb_devices_data.items():
                for intf in bulk_create_lag_interfaces:
                    if intf["device"] == device_data["id"]:
                        device_results[device_name]["created"].append(intf["name"])
        except Exception as e:
            msg = f"failed to bulk create LAG interfaces: {e}"
            ret.errors.append(msg)
            log.error(msg)
            job.event(msg, severity="ERROR")
            return ret
    else:
        job.event("no LAG interfaces to create")

    # re-fetch interface IDs after creating LAG interfaces
    job.event("refreshing interface IDs after LAG interface creation")
    nb_intf_ids = {}
    for intf in self.bulk_filter(
        nb.dcim.interfaces, device=devices, fields="id,name,device"
    ):
        nb_intf_ids.setdefault(intf.device.name, {})[intf.name] = intf.id

    # create parent interfaces associating with LAG if required
    job.event("preparing non-child/main interface create payloads")
    bulk_create_parent_interfaces = []
    for device_name, actions in full_diff.items():
        name_to_id = nb_intf_ids[device_name]
        nb_device = nb_devices_data[device_name]
        for intf_name in actions["create"]:
            desired = normalised_live_all[device_name][intf_name]
            if not desired["parent"] and desired["type"] != "lag":
                payload = _build_interface_payload(
                    job=job,
                    ret=ret,
                    worker_name=self.name,
                    desired=desired,
                    changed_fields=[
                        k for k in desired.keys() if desired[k] is not None
                    ],
                    device=nb_device,
                    name_to_id=name_to_id,
                    intf_name=intf_name,
                    nb=nb,
                    _lookup_cache=_lookup_cache,
                    vlan_group=vlan_group,
                )
                bulk_create_parent_interfaces.append(payload)
    job.event(
        f"prepared {len(bulk_create_parent_interfaces)} non-child/main interface create payload(s)"
    )
    if bulk_create_parent_interfaces:
        job.event(f"creating non-child/main interfaces")
        try:
            nb.dcim.interfaces.create(bulk_create_parent_interfaces)
            job.event(
                f"created {len(bulk_create_parent_interfaces)} non-child/main interface(s)"
            )
            for device_name, device_data in nb_devices_data.items():
                for intf in bulk_create_parent_interfaces:
                    if intf["device"] == device_data["id"]:
                        device_results[device_name]["created"].append(intf["name"])
        except Exception as e:
            msg = f"failed to bulk create non-child/main interfaces: {e}"
            ret.errors.append(msg)
            log.error(msg)
            job.event(msg, severity="ERROR")
            return ret
    else:
        job.event("no non-child/main interfaces to create")

    # re-fetch interface IDs after creating parent interfaces
    job.event("refreshing interface IDs after non-child/main interface creation")
    nb_intf_ids = {}
    for intf in self.bulk_filter(
        nb.dcim.interfaces, device=devices, fields="id,name,device"
    ):
        nb_intf_ids.setdefault(intf.device.name, {})[intf.name] = intf.id

    # create child interfaces associating with parent interfaces
    job.event("preparing child interface create payloads")
    bulk_create_child_interfaces = []
    for device_name, actions in full_diff.items():
        name_to_id = nb_intf_ids[device_name]
        nb_device = nb_devices_data[device_name]
        for intf_name in actions["create"]:
            desired = normalised_live_all[device_name][intf_name]
            if desired["parent"]:
                payload = _build_interface_payload(
                    job=job,
                    ret=ret,
                    worker_name=self.name,
                    desired=desired,
                    changed_fields=[
                        k for k in desired.keys() if desired[k] is not None
                    ],
                    device=nb_device,
                    name_to_id=name_to_id,
                    intf_name=intf_name,
                    nb=nb,
                    _lookup_cache=_lookup_cache,
                    vlan_group=vlan_group,
                )
                bulk_create_child_interfaces.append(payload)
    job.event(
        f"prepared {len(bulk_create_child_interfaces)} child interface create payload(s)"
    )
    if bulk_create_child_interfaces:
        job.event(f"creating child interfaces")
        try:
            nb.dcim.interfaces.create(bulk_create_child_interfaces)
            job.event(
                f"created {len(bulk_create_child_interfaces)} child interface(s)"
            )
            for device_name, device_data in nb_devices_data.items():
                for intf in bulk_create_child_interfaces:
                    if intf["device"] == device_data["id"]:
                        device_results[device_name]["created"].append(intf["name"])
        except Exception as e:
            msg = f"failed to bulk create child interfaces: {e}"
            ret.errors.append(msg)
            log.error(msg)
            job.event(msg, severity="ERROR")
            return ret
    else:
        job.event("no child interfaces to create")

    # Build bulk_update_interfaces list from full_diff
    job.event("preparing interface update payloads")
    bulk_update_interfaces = {}
    for device_name, actions in full_diff.items():
        nb_device = nb_devices_data[device_name]
        name_to_id = nb_intf_ids[device_name]
        for intf_name, field_changes in actions["update"].items():
            desired = normalised_live_all[device_name][intf_name]
            intf_id = nb_intf_ids[device_name][intf_name]
            payload = _build_interface_payload(
                job=job,
                ret=ret,
                worker_name=self.name,
                desired=desired,
                changed_fields=set(field_changes.keys()),
                device=nb_device,
                name_to_id=name_to_id,
                intf_name=intf_name,
                nb=nb,
                _lookup_cache=_lookup_cache,
                vlan_group=vlan_group,
            )
            # skip if nothing else to update
            if set(payload) == {"device", "name"}:
                continue
            payload["id"] = intf_id
            bulk_update_interfaces[(device_name, intf_name)] = payload
    job.event(f"prepared {len(bulk_update_interfaces)} interface update payload(s)")
    if bulk_update_interfaces:
        job.event(f"updating {len(bulk_update_interfaces)} interface(s)")
        try:
            nb.dcim.interfaces.update(list(bulk_update_interfaces.values()))
            job.event(f"updated {len(bulk_update_interfaces)} interface(s)")
            for k in bulk_update_interfaces.keys():
                device_name, intf_name = k
                device_results[device_name]["updated"].append(intf_name)
        except Exception as e:
            msg = f"failed to bulk update interfaces: {e}"
            ret.errors.append(msg)
            log.error(msg)
            job.event(msg, severity="ERROR")
            return ret
    else:
        job.event("no interfaces to update")

    # Build bulk_delete_interfaces payload from full_diff
    bulk_delete_interfaces = {}  # keyed by intf id, values intf names
    if process_deletions:
        job.event(f"processing interface deletions")
        for device_name, actions in full_diff.items():
            # delete children before parents to avoid constraint errors
            ordered_deletes = sorted(
                actions["delete"], key=lambda x: (x.count("."), x), reverse=True
            )
            for intf_name in ordered_deletes:
                intf_id = nb_intf_ids[device_name][intf_name]
                bulk_delete_interfaces[intf_id] = {
                    "device": device_name,
                    "interface": intf_name,
                }
        job.event(
            f"prepared {len(bulk_delete_interfaces)} interface delete payload(s)"
        )
    elif delete_count:
        job.event(
            f"skipping {delete_count} interface deletion(s), process_deletions=False"
        )
    if bulk_delete_interfaces:
        job.event(f"deleting {len(bulk_delete_interfaces)} interface(s)")
        try:
            nb.dcim.interfaces.delete(list(bulk_delete_interfaces.keys()))
            job.event(f"deleted {len(bulk_delete_interfaces)} interface(s)")
            for intf_data in bulk_delete_interfaces.values():
                device_name = intf_data["device"]
                intf_name = intf_data["interface"]
                device_results[device_name]["deleted"].append(intf_name)
        except Exception as exc:
            msg = f"failed to bulk delete interfaces: {exc}"
            ret.errors.append(msg)
            log.error(msg)
            job.event(msg, severity="ERROR")
    elif process_deletions:
        job.event("no interfaces to delete")

    job.event("interface sync complete")
    return ret