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 dependency order. VRF assignments are owned by sync_vrfs. When an update clears interface mode, it also clears the untagged VLAN and tagged VLAN list in the same request.

Devices may begin with no interfaces in NetBox. The task treats an empty current interface set as valid and creates interfaces discovered from live data.

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 Nornir parse_ttp jobs using the interfaces configuration getter first, followed by the interfaces_status operational getter. Configuration remains authoritative; operational state fills only MTU, duplex, and speed values that configuration parsing returned as null. Operational speed_bps is converted to the Kbit/s value expected by NetBox. For existing interfaces, live MTU or speed values of null or 0 do not overwrite a value already set in NetBox.
3. Diff — Normalize both sides to a common schema, including the parsed 802.1Q interface mode, apply interface_map to live interface names, 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. Update changed interfaces
   5. Delete interfaces present in NetBox but absent in live data (only when process_deletions=True)

Each create, update, and delete phase sends sequential bulk requests of at most batch_size interfaces. The default is 1000; set any integer greater than zero to tune the request size. Successful batches are recorded in the result before the next request, so a failure can leave earlier batches applied in NetBox. Each batch emits a progress event and an info log before the request with its batch number, total batches, and interface count.

Set batch_fallback=True (CLI: batch-fallback True) to retry a failed create or update batch one interface at a time, then resume bulk requests for the next batch. Batch and individual failures are recorded in errors, logs, and error events. Fallback emits a warning and a summary of successful and failed retries; only successful writes appear in created and updated. With fallback enabled, these errors do not change the task failure flag. The default is False, which marks the task failed and returns after a failed batch. Deletion behavior is unchanged.

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

Interface Type Behavior

New interfaces retain the type inferred from live data. Creation accepts any NetBox interface type, including other, which remains the catch-all when the parser cannot identify a more specific physical type.

For existing interfaces, update_type=True is the default and enables safe logical type correction:

• other can change to virtual, bridge, or lag.
• virtual, bridge, and lag can change between one another.
• A specific physical type is never replaced with another type.
• A specific physical type does not receive a parent inferred from live parsing.
• No existing type is replaced with other.
• An interface with a connected cable is not changed to virtual; the rejected transition is reported as an error.

Loopback interfaces use NetBox type virtual; loopback is not submitted as an interface type. Set update_type=False to disable all type changes for existing interfaces. Unsafe transitions are omitted from the actionable diff and reported as warning events. When an ignored type transition is the only difference, the interface is reported as in sync for the fields managed by the task.

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, the task returns the dry-run result without requesting approval.

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.

Description Preservation

preserve_description controls descriptions on interfaces that already exist in NetBox. Its default value, None, keeps the NetBox description when the live description is empty and otherwise uses the live value. Set it to True to always keep the NetBox description. Set it to False to always use the live description, including an empty string. Newly created interfaces always use the live description.

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.

Interface Name Mapping

interface_map accepts an ordered list of rename rules inline or as an nf:// URL to a YAML file:

- device_name: leaf-*
  device_type: cEOS-*-CA
  match: Ethernet
  replace: Et

device_name and device_type are case-sensitive glob patterns. Device type matches the NetBox device type model. match is a case-sensitive literal substring in the live interface name and replace is its replacement, so the example renames Ethernet12 to Et12. All three match criteria must succeed. Rules are evaluated in list order and the first match wins. Interfaces that do not match a rule keep their live names.

Mapping is also applied to live parent and LAG interface references before name filtering and DeepDiff comparison.

interface_map: nf://netbox/interface_map.yaml

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.

VLAN ownership

The task synchronizes the 802.1Q interface mode directly from the live interface parser, including an access mode with no VLAN assigned. It does not create VLANs or update tagged VLANs, untagged VLAN, or Q-in-Q service VLAN fields. Run sync_vlans after interfaces exist to reconcile VLAN objects and tagged/untagged memberships. Q-in-Q membership is not supported by sync_vlans.

The task does not create VRFs or update interface VRF assignments. Run sync_vrfs after interfaces exist to reconcile those relationships.

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

Use smaller NetBox bulk requests:

nf#netbox sync interfaces devices ceos-spine-1 batch-size 250

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*"

Map a live interface name to the preferred NetBox name:

nf#netbox sync interfaces devices leaf-1 interface-map '[{"device_name":"leaf-*","device_type":"cEOS-*-CA","match":"Ethernet","replace":"Et"}]'

Download interface mapping rules from a YAML file:

nf#netbox sync interfaces devices leaf-1 interface-map nf://netbox/interface_map.yaml

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"],
        "batch_size": 250,
    },
)

# 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*",
    },
)

# map live interface names to preferred NetBox names before comparison
result = client.run_job(
    "netbox",
    "sync_device_interfaces",
    workers="any",
    kwargs={
        "devices": ["leaf-1"],
        "interface_map": [
            {
                "device_name": "leaf-*",
                "device_type": "cEOS-*-CA",
                "match": "Ethernet",
                "replace": "Et",
            }
        ],
    },
)

# 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_*",
        "preserve_description": None,
    },
)

# 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
            ├── batch-size:    Maximum interfaces per NetBox bulk request, default '1000'
            ├── process-deletions:    Delete interfaces present in NetBox but absent in live data
            ├── interface-map:    Ordered rules mapping live interface names to preferred NetBox names
            ├── 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
            ├── preserve-description:    Preserve NetBox descriptions always (true), when live text is empty (null), or never (false)
            ├── update-type:    Safely update existing NetBox logical interface types, default 'True'
            ├── 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 Nornir parse_ttp interface configuration and status jobs against devices. Configuration is authoritative, while status fills missing MTU, duplex, and speed values. Existing NetBox MTU and speed values are preserved when live values are None or 0.
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).

Prerequisites

• Device must exist in Netbox

Limitations

• Interface sync does not handle IP addresses
• Clearing interface mode also clears untagged and tagged VLAN assignments
• Interface sync does not handle MAC addresses
• Sync interfaces uses device running configuration as the primary source; operational state only fills missing MTU, duplex, and speed values

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
interface_map	Union[None, str, list]	Ordered interface rename rules, or an nf:// YAML file containing them. Rules match by device name glob, device type model glob, and a literal live interface name substring. The first matching rule wins.	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
preserve_description	bool	Description preservation policy. None preserves NetBox text when the live description is empty, True always preserves NetBox text, and False always uses live text.	None
batch_size	int	Maximum interfaces in each NetBox bulk create, update, or delete request. Defaults to 1000.	1000
batch_fallback	bool	Retry failed create and update batches one interface at a time, reporting errors and continuing with the next bulk batch. Defaults to False. Deletions are unaffected.	False
update_type	bool	Safely update existing interface types. Updates are allowed from other to virtual, bridge, or lag, and between those logical types. Specific physical types are protected, and transitions to other are ignored. Set to False to disable all type updates. New interfaces can use any parsed type regardless of this setting. Defaults to True.	True
**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": ["POST"], "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,
    interface_map: Union[None, str, list] = None,
    filter_by_name: Union[None, str] = None,
    filter_by_description: Union[None, str] = None,
    update_type: bool = True,
    preserve_description: Union[None, bool] = None,
    batch_size: int = 1000,
    batch_fallback: bool = False,
    **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 Nornir ``parse_ttp`` interface configuration
       and status jobs against devices. Configuration is authoritative, while
       status fills missing MTU, duplex, and speed values. Existing NetBox MTU
       and speed values are preserved when live values are ``None`` or ``0``.
    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``).

    **Prerequisites**

    - Device must exist in Netbox

    **Limitations**

    - Interface sync does not handle IP addresses
    - Clearing interface mode also clears untagged and tagged VLAN assignments
    - Interface sync does not handle MAC addresses
    - Sync interfaces uses device running configuration as the primary source;
      operational state only fills missing MTU, duplex, and speed values

    **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.
        interface_map: Ordered interface rename rules, or an ``nf://`` YAML
            file containing them. Rules match by device name glob, device
            type model glob, and a literal live interface name substring.
            The first matching rule wins.
        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*'``.
        preserve_description (bool, optional): Description preservation policy.
            ``None`` preserves NetBox text when the live description is empty,
            ``True`` always preserves NetBox text, and ``False`` always uses
            live text.
        batch_size (int, optional): Maximum interfaces in each NetBox bulk
            create, update, or delete request. Defaults to 1000.
        batch_fallback (bool, optional): Retry failed create and update batches
            one interface at a time, reporting errors and continuing with the
            next bulk batch. Defaults to False. Deletions are unaffected.
        update_type (bool): Safely update existing interface types. Updates are
            allowed from ``other`` to ``virtual``, ``bridge``, or ``lag``, and
            between those logical types. Specific physical types are protected,
            and transitions to ``other`` are ignored. Set to False to disable
            all type updates. New interfaces can use any parsed type regardless
            of this setting. Defaults to True.
        **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 = list(devices or [])
    if self.is_url(interface_map):
        interface_map = TypeAdapter(list[InterfaceMapRule]).validate_python(
            yaml.safe_load(self.fetch_file(interface_map, raise_on_fail=True)) or []
        )
    interface_map = [
        rule.model_dump() if hasattr(rule, "model_dump") else dict(rule)
        for rule in interface_map or []
    ]
    instance = instance or self.default_instance
    ret = Result(
        task=f"{self.name}:sync_device_interfaces",
        result=SyncActionSummaryMap().model_dump(),
        resources=[instance],
        dry_run=dry_run,
        diff={},
    )
    nb = self._get_pynetbox(instance, branch=branch, job=job)
    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)
        devices.extend(nornir_hosts)
        job.event(
            f"resolved {len(nornir_hosts)} device(s) from Nornir filters, "
            f"{len(set(devices))} total device(s) selected"
        )
    devices = sorted(set(devices))

    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,
            "device_type": d.device_type.model,
        }
        for d in self.bulk_filter(
            nb.dcim.devices,
            name=devices,
            fields="id,name,device_type",
        )
    }
    object_cache = {
        ("device", device_name): data["id"]
        for device_name, data in nb_devices_data.items()
    }
    for device_name in devices:
        if device_name not in nb_devices_data:
            msg = f"{device_name} - device not found in NetBox"
            log.error(msg)
            job.event(msg, severity="ERROR")
            ret.errors.append(msg)
    devices = [name for name in devices if name in nb_devices_data]
    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 the current NetBox interface state.
    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",
        raise_on_empty=False,
    )
    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():
            object_cache[("interface", device_name, intf_name)] = data["id"]
            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
            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
            )
            normalised_nb_all[device_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["duplex"].get("value")
                    if isinstance(data.get("duplex"), dict)
                    else data.get("duplex")
                ),
                "description": str(data.get("description") or ""),
                "mode": (data.get("mode") or {}).get("value"),
            }
    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,
    )
    job.event(f"retrieving live interface status for {len(devices)} devices")
    parse_status_data = self.client.run_job(
        "nornir",
        "parse_ttp",
        kwargs={"get": "interfaces_status", "FL": devices},
        workers="all",
        timeout=timeout,
    )
    interface_status = {}
    for wname, wdata in parse_status_data.items():
        resources_failed = wdata.get("resources_failed") or []
        if resources_failed:
            ret.resources_failed = sorted(
                set(ret.resources_failed) | set(resources_failed)
            )
            msg = (
                f"{wname} failed to fetch interface status data from devices "
                f"{', '.join(sorted(resources_failed))}"
            )
            job.event(msg, severity="ERROR")
            log.error(f"{self.name} - {msg}")
            ret.errors.append(msg)
        if wdata.get("failed"):
            msg = f"{wname} - failed to parse interface status data from devices"
            log.warning(msg)
            job.event(msg, severity="WARNING")
            continue
        for device_name, host_interfaces in wdata["result"].items():
            device_status = interface_status.setdefault(device_name, {})
            for data in host_interfaces or []:
                if data.get("name"):
                    device_status[data["name"]] = data

    # Normalize live interface data per device.
    job.event("normalising live interface data")
    normalised_live_all = {}
    for wname, wdata in parse_data.items():
        resources_failed = wdata.get("resources_failed") or []
        if resources_failed:
            ret.resources_failed = sorted(
                set(ret.resources_failed) | set(resources_failed)
            )
            msg = (
                f"{wname} failed to fetch interface data from devices "
                f"{', '.join(sorted(resources_failed))}"
            )
            job.event(msg, severity="ERROR")
            log.error(f"{self.name} - {msg}")
            ret.errors.append(msg)
        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 []:
                status = interface_status.get(device_name, {}).get(
                    data.get("name"), {}
                )
                mapped_names = {
                    field: data.get(field) for field in ("name", "parent", "lag")
                }
                for field, live_name in mapped_names.items():
                    mapped_names[field] = map_interface_name(
                        live_name,
                        interface_map,
                        device_name,
                        nb_devices_data[device_name]["device_type"],
                    )
                intf_name = mapped_names["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] = {
                    "type": data["type"],
                    "enabled": bool(
                        data.get("enabled", data.get("is_enabled", True))
                    ),
                    "parent": mapped_names["parent"],
                    "lag": mapped_names["lag"],
                    "mtu": data.get("mtu"),
                    "speed": data.get("speed"),
                    "duplex": data.get("duplex"),
                    "description": str(data.get("description") or ""),
                    "mode": data.get("mode"),
                }
                interface = normalised_live_all[device_name][intf_name]
                status_mtu = status.get("mtu")
                if interface["mtu"] is None and status_mtu and status_mtu > 0:
                    interface["mtu"] = status_mtu
                status_speed = status.get("speed_bps")
                if interface["speed"] is None and status_speed and status_speed > 0:
                    interface["speed"] = status_speed // 1_000
                if interface["duplex"] is None:
                    interface["duplex"] = status.get("duplex")
                # Preserve existing NetBox values when live data has no usable value.
                nb_interface = normalised_nb_all.get(device_name, {}).get(intf_name)
                if nb_interface:
                    interface["description"] = apply_description_policy(
                        interface["description"],
                        nb_interface["description"],
                        preserve_description,
                    )
                    for field in ("mtu", "speed"):
                        if interface[field] in (None, 0) and nb_interface[field]:
                            interface[field] = nb_interface[field]
    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)

    # Apply the existing-interface type update policy. Interface creation is
    # intentionally unrestricted and continues to use any parsed type.
    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]
            type_change = intf_updates.get("type")
            if type_change:
                old_type = type_change["old_value"]
                new_type = type_change["new_value"]
                safe_type_transition = old_type in (
                    "other",
                    "virtual",
                    "bridge",
                    "lag",
                ) and new_type in ("virtual", "bridge", "lag")

                # Remove all existing-interface type changes when disabled.
                if update_type is False:
                    intf_updates.pop("type")

                # NetBox does not allow cabled interfaces to become virtual.
                elif new_type == "virtual" and nb_interfaces_result.result[
                    dev_name
                ][intf_name].get("cable"):
                    intf_updates.pop("type")
                    msg = (
                        f"{dev_name}:{intf_name} - cannot transition interface "
                        f"type from {old_type} to virtual while a cable is connected"
                    )
                    ret.errors.append(msg)
                    log.error(msg)
                    job.event(msg, severity="ERROR")

                # Protect physical types and never transition to ``other``.
                elif safe_type_transition is False:
                    intf_updates.pop("type")
                    job.event(
                        f"skipping unsafe interface type transition for "
                        f"{dev_name}:{intf_name}: {old_type} -> {new_type}",
                        severity="WARNING",
                    )
                # Do not assign a parsed parent when NetBox keeps a non-virtual type.
                if old_type != "virtual" and "type" not in intf_updates:
                    intf_updates.pop("parent", None)
            # remove interface from updates if nothing remains to update
            if not intf_updates:
                dev_diff["update"].pop(intf_name)
                dev_diff["in_sync"].append(intf_name)
        dev_diff["in_sync"].sort()
    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"
    )

    ret.result = {
        device_name: SyncActionSummary(in_sync=actions["in_sync"]).model_dump()
        for device_name, actions in full_diff.items()
    }
    ret.diff = full_diff
    if dry_run:
        job.event(
            "dry-run requested, returning interface sync diff without changes"
        )
        ret.result = full_diff
        ret.dry_run = True
        return ret
    if not sync_diff_has_changes(full_diff):
        job.event("no interface sync changes required")
        return ret
    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
    device_names_by_id = {
        data["id"]: device_name for device_name, data in nb_devices_data.items()
    }
    # create LAG interfaces
    job.event("preparing LAG interface create payloads")
    bulk_create_lag_interfaces = []
    for device_name, actions in full_diff.items():
        for intf_name in actions["create"]:
            desired = normalised_live_all[device_name][intf_name]
            if desired["type"] == "lag":
                payload = _build_interface_payload(
                    desired=desired,
                    changed_fields={
                        k for k in desired.keys() if desired[k] is not None
                    },
                    object_cache=object_cache,
                    device_name=device_name,
                    intf_name=intf_name,
                )
                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:
        created_lag_count = 0
        job.event("creating LAG interfaces")
        total_batches = (
            len(bulk_create_lag_interfaces) + batch_size - 1
        ) // batch_size
        for batch_start in range(0, len(bulk_create_lag_interfaces), batch_size):
            batch = bulk_create_lag_interfaces[
                batch_start : batch_start + batch_size
            ]
            batch_number = batch_start // batch_size + 1
            msg = f"creating LAG interface batch {batch_number}/{total_batches} ({len(batch)} interface(s))"
            job.event(msg)
            log.info(msg)
            try:
                created_interfaces = nb.dcim.interfaces.create(batch)
            except Exception as exc:
                msg = f"failed to create LAG interface batch {batch_number}/{total_batches}: {exc}"
                ret.errors.append(msg)
                log.error(msg)
                job.event(msg, severity="ERROR")
                if not batch_fallback:
                    ret.failed = True
                    return ret
                msg = f"retrying LAG interface batch {batch_number}/{total_batches} one interface at a time"
                log.warning(msg)
                job.event(msg, severity="WARNING")
                created_interfaces = []
                for payload in batch:
                    device_name = device_names_by_id[payload["device"]]
                    try:
                        interface = nb.dcim.interfaces.create(payload)
                    except Exception as item_exc:
                        msg = f"failed to create {device_name}:{payload['name']}: {item_exc}"
                        ret.errors.append(msg)
                        log.error(msg)
                        job.event(msg, severity="ERROR")
                    else:
                        created_interfaces.append(interface)
                        msg = (
                            f"created {device_name}:{interface.name} using fallback"
                        )
                        log.info(msg)
                        job.event(msg)
                msg = f"completed LAG interface batch {batch_number}/{total_batches} fallback: {len(created_interfaces)} succeeded, {len(batch) - len(created_interfaces)} failed"
                log.info(msg)
                job.event(msg)
            for interface in created_interfaces:
                device_name = interface.device.name
                object_cache[("interface", device_name, interface.name)] = (
                    interface.id
                )
                ret.result[device_name]["created"].append(interface.name)
                created_lag_count += 1
        job.event(f"created {created_lag_count} LAG interface(s)")
    else:
        job.event("no LAG interfaces to create")

    # 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():
        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(
                    desired=desired,
                    changed_fields={
                        k for k in desired.keys() if desired[k] is not None
                    },
                    object_cache=object_cache,
                    device_name=device_name,
                    intf_name=intf_name,
                )
                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:
        created_parent_count = 0
        job.event("creating non-child/main interfaces")
        total_batches = (
            len(bulk_create_parent_interfaces) + batch_size - 1
        ) // batch_size
        for batch_start in range(0, len(bulk_create_parent_interfaces), batch_size):
            batch = bulk_create_parent_interfaces[
                batch_start : batch_start + batch_size
            ]
            batch_number = batch_start // batch_size + 1
            msg = f"creating non-child/main interface batch {batch_number}/{total_batches} ({len(batch)} interface(s))"
            job.event(msg)
            log.info(msg)
            try:
                created_interfaces = nb.dcim.interfaces.create(batch)
            except Exception as exc:
                msg = f"failed to create non-child/main interface batch {batch_number}/{total_batches}: {exc}"
                ret.errors.append(msg)
                log.error(msg)
                job.event(msg, severity="ERROR")
                if not batch_fallback:
                    ret.failed = True
                    return ret
                msg = f"retrying non-child/main interface batch {batch_number}/{total_batches} one interface at a time"
                log.warning(msg)
                job.event(msg, severity="WARNING")
                created_interfaces = []
                for payload in batch:
                    device_name = device_names_by_id[payload["device"]]
                    try:
                        interface = nb.dcim.interfaces.create(payload)
                    except Exception as item_exc:
                        msg = f"failed to create {device_name}:{payload['name']}: {item_exc}"
                        ret.errors.append(msg)
                        log.error(msg)
                        job.event(msg, severity="ERROR")
                    else:
                        created_interfaces.append(interface)
                        msg = (
                            f"created {device_name}:{interface.name} using fallback"
                        )
                        log.info(msg)
                        job.event(msg)
                msg = f"completed non-child/main interface batch {batch_number}/{total_batches} fallback: {len(created_interfaces)} succeeded, {len(batch) - len(created_interfaces)} failed"
                log.info(msg)
                job.event(msg)
            for interface in created_interfaces:
                device_name = interface.device.name
                object_cache[("interface", device_name, interface.name)] = (
                    interface.id
                )
                ret.result[device_name]["created"].append(interface.name)
                created_parent_count += 1
        job.event(f"created {created_parent_count} non-child/main interface(s)")
    else:
        job.event("no non-child/main interfaces to create")

    # 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():
        for intf_name in actions["create"]:
            desired = normalised_live_all[device_name][intf_name]
            if desired["parent"]:
                payload = _build_interface_payload(
                    desired=desired,
                    changed_fields={
                        k for k in desired.keys() if desired[k] is not None
                    },
                    object_cache=object_cache,
                    device_name=device_name,
                    intf_name=intf_name,
                )
                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:
        created_child_count = 0
        job.event("creating child interfaces")
        total_batches = (
            len(bulk_create_child_interfaces) + batch_size - 1
        ) // batch_size
        for batch_start in range(0, len(bulk_create_child_interfaces), batch_size):
            batch = bulk_create_child_interfaces[
                batch_start : batch_start + batch_size
            ]
            batch_number = batch_start // batch_size + 1
            msg = f"creating child interface batch {batch_number}/{total_batches} ({len(batch)} interface(s))"
            job.event(msg)
            log.info(msg)
            try:
                created_interfaces = nb.dcim.interfaces.create(batch)
            except Exception as exc:
                msg = f"failed to create child interface batch {batch_number}/{total_batches}: {exc}"
                ret.errors.append(msg)
                log.error(msg)
                job.event(msg, severity="ERROR")
                if not batch_fallback:
                    ret.failed = True
                    return ret
                msg = f"retrying child interface batch {batch_number}/{total_batches} one interface at a time"
                log.warning(msg)
                job.event(msg, severity="WARNING")
                created_interfaces = []
                for payload in batch:
                    device_name = device_names_by_id[payload["device"]]
                    try:
                        interface = nb.dcim.interfaces.create(payload)
                    except Exception as item_exc:
                        msg = f"failed to create {device_name}:{payload['name']}: {item_exc}"
                        ret.errors.append(msg)
                        log.error(msg)
                        job.event(msg, severity="ERROR")
                    else:
                        created_interfaces.append(interface)
                        msg = (
                            f"created {device_name}:{interface.name} using fallback"
                        )
                        log.info(msg)
                        job.event(msg)
                msg = f"completed child interface batch {batch_number}/{total_batches} fallback: {len(created_interfaces)} succeeded, {len(batch) - len(created_interfaces)} failed"
                log.info(msg)
                job.event(msg)
            for interface in created_interfaces:
                device_name = interface.device.name
                object_cache[("interface", device_name, interface.name)] = (
                    interface.id
                )
                ret.result[device_name]["created"].append(interface.name)
                created_child_count += 1
        job.event(f"created {created_child_count} child interface(s)")
    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():
        for intf_name, field_changes in actions["update"].items():
            desired = normalised_live_all[device_name][intf_name]
            payload = _build_interface_payload(
                desired=desired,
                changed_fields=set(field_changes.keys()),
                object_cache=object_cache,
                device_name=device_name,
                intf_name=intf_name,
            )
            # Clear VLAN assignments in the same request when removing interface mode.
            if "mode" in field_changes and desired["mode"] is None:
                payload["untagged_vlan"] = None
                payload["tagged_vlans"] = []
            payload["id"] = object_cache[("interface", device_name, intf_name)]
            bulk_update_interfaces[(device_name, intf_name)] = payload
    job.event(f"prepared {len(bulk_update_interfaces)} interface update payload(s)")
    if bulk_update_interfaces:
        updated_count = 0
        job.event(f"updating {len(bulk_update_interfaces)} interface(s)")
        update_items = list(bulk_update_interfaces.items())
        total_batches = (len(update_items) + batch_size - 1) // batch_size
        for batch_start in range(0, len(update_items), batch_size):
            batch = update_items[batch_start : batch_start + batch_size]
            batch_number = batch_start // batch_size + 1
            msg = f"updating interface batch {batch_number}/{total_batches} ({len(batch)} interface(s))"
            job.event(msg)
            log.info(msg)
            try:
                nb.dcim.interfaces.update([payload for _, payload in batch])
            except Exception as exc:
                msg = f"failed to update interface batch {batch_number}/{total_batches}: {exc}"
                ret.errors.append(msg)
                log.error(msg)
                job.event(msg, severity="ERROR")
                if not batch_fallback:
                    ret.failed = True
                    return ret
                msg = f"retrying interface update batch {batch_number}/{total_batches} one interface at a time"
                log.warning(msg)
                job.event(msg, severity="WARNING")
                updated_items = []
                for (device_name, intf_name), payload in batch:
                    try:
                        nb.dcim.interfaces.update([payload])
                    except Exception as item_exc:
                        msg = f"failed to update {device_name}:{intf_name}: {item_exc}"
                        ret.errors.append(msg)
                        log.error(msg)
                        job.event(msg, severity="ERROR")
                    else:
                        updated_items.append(((device_name, intf_name), payload))
                        msg = f"updated {device_name}:{intf_name} using fallback"
                        log.info(msg)
                        job.event(msg)
                msg = f"completed interface update batch {batch_number}/{total_batches} fallback: {len(updated_items)} succeeded, {len(batch) - len(updated_items)} failed"
                log.info(msg)
                job.event(msg)
                batch = updated_items
            for (device_name, intf_name), _ in batch:
                ret.result[device_name]["updated"].append(intf_name)
                updated_count += 1
        job.event(f"updated {updated_count} interface(s)")
    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("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 = object_cache[("interface", 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)")
        delete_items = list(bulk_delete_interfaces.items())
        total_batches = (len(delete_items) + batch_size - 1) // batch_size
        for batch_start in range(0, len(delete_items), batch_size):
            batch = delete_items[batch_start : batch_start + batch_size]
            batch_number = batch_start // batch_size + 1
            msg = f"deleting interface batch {batch_number}/{total_batches} ({len(batch)} interface(s))"
            job.event(msg)
            log.info(msg)
            try:
                nb.dcim.interfaces.delete([intf_id for intf_id, _ in batch])
            except Exception as exc:
                msg = f"failed to delete interface batch {batch_number}/{total_batches}: {exc}"
                ret.errors.append(msg)
                ret.failed = True
                log.error(msg)
                job.event(msg, severity="ERROR")
                return ret
            for _, intf_data in batch:
                device_name = intf_data["device"]
                intf_name = intf_data["interface"]
                ret.result[device_name]["deleted"].append(intf_name)
        job.event(f"deleted {len(bulk_delete_interfaces)} interface(s)")
    elif process_deletions:
        job.event("no interfaces to delete")

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