Skip to content

Sync VLANs¤

Use sync_vlans to create missing VLANs and update VLAN names, descriptions, and tagged or untagged interface assignments in Netbox from live devices. Select devices by name or with Nornir host filters. Use a dry run to review changes before applying them.

Devices must exist in Netbox and be reachable through the Nornir service with a supported TTP vlans getter. Run sync_device_interfaces first if their interfaces are missing.

Output¤

Each worker returns created, updated, deleted, and in_sync lists per device. All references use scope:VID, such as group:CAMPUS:100. Membership changes place the affected VLAN in updated. A newly created VLAN can also appear in updated when its interface assignments change. A dry run reports planned actions; a live run reports completed actions.

{
  "leaf-1": {
    "created": ["group:CAMPUS:100"],
    "updated": ["group:CAMPUS:100", "group:CAMPUS:110"],
    "deleted": [],
    "in_sync": ["group:CAMPUS:120"]
  }
}

diff[device].vlans[scope] contains create, update, delete, and in_sync actions. VLAN updates are keyed by VID and show old_value and new_value for each field. diff[device].interfaces contains the same action keys, with updates keyed by interface name and showing previous and desired VLAN assignments. The diff retains this preview after writes are applied. Existing VLANs are matched by VID and scope independently of interface assignments. Check errors for skipped VLANs, missing interfaces, and conflicting live data. Skipped name updates remain visible in the diff; selected values already matching NetBox do not trigger writes. The task does not delete VLAN records, so deleted remains empty. Shared VLAN writes may appear under multiple contributing devices.

Interface names mapped to the same NetBox interface contribute to one membership target; their tagged VLAN assignments are combined.

Examples¤

Preview VLANs 100-199 on leaf-1 in the existing CAMPUS group, keeping existing Netbox names. Remove dry_run or dry-run to apply the changes. Python examples assume an established NorFab client. FastAPI examples require a running NorFab FastAPI service that has discovered the Netbox tasks.

nf# netbox sync vlans devices leaf-1 vlan-ids 100-199 vlan-group CAMPUS preserve-name dry-run

To review and approve changes interactively:

nf# netbox sync vlans devices leaf-1 vlan-ids 100-199 vlan-group CAMPUS preserve-name with-approval
result = client.run_job(
    "netbox",
    "sync_vlans",
    workers="any",
    kwargs={
        "devices": ["leaf-1"],
        "filter_by_vlan_ids": ["100-199"],
        "vlan_group": "CAMPUS",
        "preserve_name": True,
        "dry_run": True,
    },
)
print(result)

Replace the service URL and bearer token with your deployment values.

import requests

response = requests.post(
    "http://localhost:8000/api/netbox/sync_vlans/",
    headers={"Authorization": "Bearer <TOKEN>"},
    json={
        "workers": "any",
        "devices": ["leaf-1"],
        "filter_by_vlan_ids": ["100-199"],
        "vlan_group": "CAMPUS",
        "preserve_name": True,
        "dry_run": True,
    },
    timeout=660,
)
response.raise_for_status()
print(response.json())
curl -X POST 'http://localhost:8000/api/netbox/sync_vlans/' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"workers":"any","devices":["leaf-1"],"filter_by_vlan_ids":["100-199"],"vlan_group":"CAMPUS","preserve_name":true,"dry_run":true}'
Use the NorFab Netbox sync_vlans tool to preview VLANs 100-199 from leaf-1
in the CAMPUS VLAN group. Preserve existing Netbox VLAN names and report
planned VLAN and interface changes without applying them.

Preserve names and descriptions¤

preserve_name=False is the default. Descriptive live names replace differing Netbox names. Set preserve_name=True to keep existing names. In either mode, a generated live name such as VLAN100 does not replace an existing Netbox name. New VLANs always use live names.

For existing VLAN descriptions, preserve_description=None keeps Netbox text when live text is empty. Use True to always keep Netbox text or False to always use live text, including an empty string. New VLANs use live descriptions.

VLAN Groups Mapping¤

VLANs are matched by VID and scope, not name. Supply vlan_group to select an existing group. Its scope must apply to the device, and its allowed VID ranges must include the VLAN IDs.

Use vlan_map for ordered group selection rules, supplied inline or as an nf:// YAML file. For example:

- set_vlan_group: CAMPUS
  match_vlan_ids: ["100-199"]
  vlan_names: ["USERS*", "VOICE*"]
  match_device_names: ["leaf-*"]
  match_interface_names: ["Ethernet*"]

The first matching rule wins. All supplied criteria must match. Values within one criterion are alternatives. Name patterns are case-sensitive, and VLAN ID ranges must stay within 1-4094. Interface patterns match any member interface. VLANs without a matching rule use vlan_group. Set require_vlan_group=True to skip VLANs without either selection.

Without an explicit group, the task prefers a device-compatible group, then a VLAN in the device's site, then a global VLAN. Equally preferred matches are reported as ambiguous and skipped. If no match exists, it creates a site VLAN. An invalid explicit group selection is skipped without falling back.

Group scopes support sites, regions, site groups, locations, racks, and rack groups. Region matching includes up to five levels, starting with the site's region. Other scopes require a direct match. If device location is unset, the rack's location is used. Cluster scopes are ignored.

Interface assignments¤

Reported tagged memberships are added to existing assignments. Empty live membership lists do not clear assignments. A reported untagged VLAN replaces the current untagged VLAN, even if the old VLAN is outside the selected ID range. Interfaces with tagged VLANs use tagged mode. Interfaces with only an untagged VLAN use access mode. Q-in-Q service VLANs are not synchronized.

If live and Netbox interface names differ, pass the same interface_map to this task and sync_device_interfaces.

Review and apply changes¤

dry_run=True previews changes without writing. with_approval=True asks for review before applying them and is ignored during a dry run. Use branch to target a branch when the Netbox Branching plugin is configured.

Bulk writes use batch_size=1000 by default. If a request fails, earlier successful writes remain applied. Review the error and preview again before retrying.

Troubleshooting¤

  • Missing live data: check device connectivity and support for the TTP vlans getter on the Nornir worker.
  • Missing interface: create it with sync_device_interfaces, then rerun.
  • Group not found or incompatible: check its exact name, scope, and allowed VID ranges. Groups must already exist.
  • Ambiguous VLAN match: select the intended group with vlan_group or vlan_map.
  • Conflicting live names or descriptions: correct differences between devices sharing the VLAN. The first descriptive name and first non-empty description in device-name order are used. Conflicts are reported even when existing names are preserved.
  • Name collision: choose a unique VLAN name within the scope, or preserve the existing name with preserve_name=True. Conflicting creations or updates are skipped.

Task Command Shell Reference¤

nf#man tree netbox.sync.vlans

R - required field, M - supports multiline input, D - dynamic key

root
└── netbox:    Netbox service
    └── sync:    Sync Netbox data
        └── vlans:    Sync live VLAN configuration with NetBox
            ├── instance:    Netbox instance name to target
            ├── dry-run:    Calculate the VLAN diff without writing to NetBox, default 'False'
            ├── branch:    NetBox branching plugin branch name to use
            ├── batch-size:    Number of objects per NetBox bulk request, default '1000'
            ├── FO:    Filter hosts using Filter Object
            ├── FB:    Filter hosts by name using Glob Patterns
            ├── FH:    Filter hosts by hostname
            ├── FC:    Filter hosts containment of pattern in name
            ├── FR:    Filter hosts by name using Regular Expressions
            ├── FG:    Filter hosts by group
            ├── FP:    Filter hosts by hostname using IP Prefix
            ├── FL:    Filter hosts by names list
            ├── FM:    Filter hosts by platform
            ├── FX:    Filter hosts excluding them by name
            ├── FN:    Negate the match
            ├── devices:    List of NetBox devices to collect VLANs from
            ├── timeout:    Job timeout
            ├── with-approval:    Preview VLAN changes and ask for review before writing to NetBox, default 'False'
            ├── vlan-group:    Exact group name for live VLANs not matched by vlan-map
            ├── vlan-map:    Ordered VLAN and interface membership mapping rules or nf:// YAML file reference
            ├── interface-map:    Interface name mapping rules shared with interface sync
            ├── require-vlan-group:    Require every live VLAN to resolve to a VLAN group, default 'False'
            ├── vlan-ids:    VLAN IDs or inclusive ranges to reconcile
            ├── preserve-description:    Preserve existing NetBox descriptions always (true), only when live text is empty (null), or never (false)
            ├── preserve-name:    Keep existing NetBox VLAN names; new VLANs use live names, default 'False'
            ├── workers:    Filter worker to target, default 'any'
            ├── verbose-result:    Control output details, default 'False'
            └── nowait:    Do not wait for job to complete, default 'False'
nf#

Python API Reference¤

Synchronize live VLAN attributes and interface memberships with NetBox.

VLANs are mapped by the first matching vlan_map rule. Rule criteria match VLAN IDs, VLAN names, device names, and each interface name; populated criteria are combined with AND. VLANs which match no rule use vlan_group when supplied. Otherwise, they use their device site unless require_vlan_group=True.

Name conflicts with NetBox or between proposed VLANs in the same scope are reported and skipped. The first proposed name is retained; skipped creations are also removed from interface membership targets.

Parameters:

Name Type Description Default
job Job

NorFab job object.

required
instance Union[None, str]

NetBox instance name. Uses the default instance when omitted.

None
dry_run bool

Return the calculated diff without writing to NetBox.

False
with_approval bool

Ask for approval before applying the prepared diff.

False
timeout int

Timeout in seconds for Nornir host resolution and parsing.

600
devices Union[None, list]

Explicit NetBox and Nornir device names.

None
branch Union[None, str]

NetBox Branching plugin branch name.

None
interface_map Union[None, str, list]

Interface rename rules shared with interface sync.

None
vlan_group Union[None, str]

Group for VLANs not matched by vlan_map.

None
vlan_map Union[None, str, list]

Ordered VLAN-to-group mapping rules, or an nf:// YAML file containing them.

None
require_vlan_group bool

Require every VLAN to resolve to a VLAN group instead of falling back to its device site.

False
filter_by_vlan_ids Union[None, list[str]]

VLAN IDs or inclusive ranges to reconcile.

None
preserve_description Union[None, 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 number of objects per bulk write.

1000
preserve_name bool

Keep existing NetBox VLAN names when True. Defaults to False to use descriptive live names. New VLANs always use live names; generated VLAN<VID> live names never replace existing NetBox names.

False
**kwargs Any

Nornir FFun host filters.

{}

Returns:

Name Type Description
Result Result

Per-device created, updated, deleted and in_sync references. Diff contains per-device VLAN actions by scope and interface field changes.

Source code in norfab\workers\netbox_worker\vlan_tasks.py
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
@Task(
    fastapi={"methods": ["POST"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=SyncVlansInput,
    output=SyncVlansResult,
    mcp={
        "annotations": {
            "title": "Sync VLANs",
            "readOnlyHint": False,
            "destructiveHint": True,
            "idempotentHint": True,
            "openWorldHint": True,
        }
    },
)
def sync_vlans(
    self,
    job: Job,
    instance: Union[None, str] = None,
    dry_run: bool = False,
    with_approval: bool = False,
    timeout: int = 600,
    devices: Union[None, list] = None,
    branch: Union[None, str] = None,
    interface_map: Union[None, str, list] = None,
    vlan_group: Union[None, str] = None,
    vlan_map: Union[None, str, list] = None,
    require_vlan_group: bool = False,
    filter_by_vlan_ids: Union[None, list[str]] = None,
    preserve_description: Union[None, bool] = None,
    batch_size: int = 1000,
    preserve_name: bool = False,
    **kwargs: Any,
) -> Result:
    """Synchronize live VLAN attributes and interface memberships with NetBox.

    VLANs are mapped by the first matching ``vlan_map`` rule. Rule criteria
    match VLAN IDs, VLAN names, device names, and each interface name;
    populated criteria are combined with AND. VLANs which match no rule use
    ``vlan_group`` when supplied. Otherwise, they use their device site
    unless ``require_vlan_group=True``.

    Name conflicts with NetBox or between proposed VLANs in the same scope
    are reported and skipped. The first proposed name is retained; skipped
    creations are also removed from interface membership targets.

    Args:
        job: NorFab job object.
        instance: NetBox instance name. Uses the default instance when omitted.
        dry_run: Return the calculated diff without writing to NetBox.
        with_approval: Ask for approval before applying the prepared diff.
        timeout: Timeout in seconds for Nornir host resolution and parsing.
        devices: Explicit NetBox and Nornir device names.
        branch: NetBox Branching plugin branch name.
        interface_map: Interface rename rules shared with interface sync.
        vlan_group: Group for VLANs not matched by ``vlan_map``.
        vlan_map: Ordered VLAN-to-group mapping rules, or an ``nf://`` YAML
            file containing them.
        require_vlan_group: Require every VLAN to resolve to a VLAN group
            instead of falling back to its device site.
        filter_by_vlan_ids: VLAN IDs or inclusive ranges to reconcile.
        preserve_description: 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: Maximum number of objects per bulk write.
        preserve_name: Keep existing NetBox VLAN names when ``True``.
            Defaults to ``False`` to use descriptive live names. New VLANs
            always use live names; generated ``VLAN<VID>`` live names never
            replace existing NetBox names.
        **kwargs: Nornir FFun host filters.

    Returns:
        Result: Per-device created, updated, deleted and in_sync references.
            Diff contains per-device VLAN actions by scope and interface field changes.
    """
    instance = instance or self.default_instance
    ret = Result(
        task=f"{self.name}:sync_vlans",
        result={},
        resources=[instance],
        dry_run=dry_run,
        diff={},
    )
    message = f"starting VLAN sync using NetBox instance '{instance}'"
    job.event(message)
    log.info(message)
    nb = self._get_pynetbox(instance, branch=branch, job=job)
    # Combine explicit devices and host filters without processing duplicates.
    selected_devices = set(devices or [])
    if kwargs:
        selected_devices.update(self.get_nornir_hosts(kwargs, timeout))
    devices = sorted(selected_devices)
    if not devices:
        message = "no devices specified"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
        ret.failed = True
        return ret
    # Prepare VID filters and mapping rules before collecting device data.
    selected_vids = set()
    for value in filter_by_vlan_ids or []:
        selected_vids.update(
            (int(vid) for vid in expand_alphanumeric_range(f"[{value}]"))
        )
    try:
        if self.is_url(vlan_map):
            vlan_map = TypeAdapter(list[VlanMapRule]).validate_python(
                yaml.safe_load(self.fetch_file(vlan_map, raise_on_fail=True)) 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 []
            )
    except Exception as exc:
        message = f"failed to load VLAN sync mapping: {exc}"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
        ret.failed = True
        return ret
    # Expand rule ranges once rather than for every VLAN match.
    interface_map = [dict(rule) for rule in interface_map or []]
    rules = []
    for rule in vlan_map or []:
        rule = dict(rule)
        expanded_vlan_ids = set()
        for value in rule.get("match_vlan_ids") or []:
            expanded_vlan_ids.update(
                (int(vid) for vid in expand_alphanumeric_range(f"[{value}]"))
            )
        rule["expanded_vlan_ids"] = expanded_vlan_ids or None
        rules.append(rule)

    # Load device context used to validate VLAN scopes.
    netbox_devices = self.bulk_filter(
        nb.dcim.devices,
        name=devices,
        fields="id,name,site,location,rack,device_type",
    )
    nb_devices = {str(device.name): device for device in netbox_devices}
    for device in devices:
        if device not in nb_devices:
            message = f"device '{device}' not found in NetBox"
            job.event(message, severity="ERROR")
            log.error(message)
            ret.errors.append(message)
    if not nb_devices:
        ret.failed = True
        return ret
    device_scopes = load_device_vlan_scopes(
        nb_devices.values(), nb, self.bulk_filter
    )
    # Collect and normalize live VLANs before loading their NetBox matches.
    message = f"collecting live VLANs from {len(nb_devices)} device(s)"
    job.event(message)
    log.info(message)
    parsed = self.client.run_job(
        "nornir",
        "parse_ttp",
        workers="all",
        timeout=timeout,
        kwargs={"get": "vlans", "FL": sorted(nb_devices)},
    )
    live_by_device = {}
    for worker, response in parsed.items():
        resources_failed = response.get("resources_failed") or []
        if resources_failed:
            ret.resources_failed = sorted(
                set(ret.resources_failed) | set(resources_failed)
            )
            message = f"{worker} failed to fetch VLAN data from devices {', '.join(sorted(resources_failed))}"
            job.event(message, severity="ERROR")
            log.error(message)
            ret.errors.append(message)
        if response.get("failed"):
            message = f"worker '{worker}' failed to collect live VLAN data"
            job.event(message, severity="ERROR")
            log.error(message)
            ret.errors.append(message)
            continue
        for device, records in response["result"].items():
            live_by_device.setdefault(device, []).extend(records)
    live_vlans = []
    interface_names_by_device = {}
    for device, records in sorted(live_by_device.items()):
        device_model = str(nb_devices[device].device_type.model)
        interface_names = {}
        # Merge duplicate parser records before choosing a scope.
        device_vlans = {}
        for record in records:
            vid = record["vid"]
            if selected_vids and vid not in selected_vids:
                continue
            for field in VLAN_MEMBERSHIP_FIELDS:
                for live_interface in record[field]:
                    if live_interface in interface_names:
                        continue
                    interface_names[live_interface] = map_interface_name(
                        live_interface, interface_map, device, device_model
                    )
            name = record["name"].strip()
            description = (record["description"] or "").strip()
            vlan = device_vlans.setdefault(
                vid,
                {
                    "device_name": device,
                    "vid": vid,
                    "name": name,
                    "description": description,
                    "tagged_interfaces": [],
                    "untagged_interfaces": [],
                },
            )
            if (
                vlan["name"].casefold() == f"vlan{vid}".casefold()
                and name.casefold() != f"vlan{vid}".casefold()
            ):
                vlan["name"] = name
            if description and (not vlan["description"]):
                vlan["description"] = description
            for field in VLAN_MEMBERSHIP_FIELDS:
                for name in record[field]:
                    if name not in vlan[field]:
                        vlan[field].append(name)
        # Match rules against the interface names used in NetBox.
        for vlan in device_vlans.values():
            mapped_interfaces = []
            for field in VLAN_MEMBERSHIP_FIELDS:
                for name in vlan[field]:
                    mapped_interfaces.append(interface_names[name])
            group_name = (
                match_vlan_map(
                    rules, vlan["vid"], vlan["name"], device, mapped_interfaces
                )
                or vlan_group
            )
            if require_vlan_group and (not group_name):
                message = f"skipping VLAN {vlan['vid']} from device '{device}': no VLAN group mapping found"
                job.event(message, severity="ERROR")
                log.error(message)
                ret.errors.append(message)
                continue
            vlan["selected_group_name"] = group_name
            live_vlans.append(vlan)
        interface_names_by_device[device] = interface_names
    message = f"normalized {len(live_vlans)} live VLAN record(s) from {len(live_by_device)} device(s)"
    job.event(message)
    log.info(message)
    # Load VLAN candidates, then all explicit and discovered groups together.
    vids = sorted({vlan["vid"] for vlan in live_vlans})
    candidates = []
    if vids:
        candidates = self.bulk_filter(
            nb.ipam.vlans, vid=vids, fields="id,vid,name,description,site,group"
        )
    configured_groups = {rule["set_vlan_group"] for rule in rules}
    if vlan_group:
        configured_groups.add(vlan_group)
    groups_by_name = {}
    if configured_groups:
        groups_by_name = {
            str(group.name): group
            for group in self.bulk_filter(
                nb.ipam.vlan_groups,
                name=sorted(configured_groups),
                fields="id,name,vid_ranges,scope_type,scope_id,scope",
            )
        }
    for name in sorted(configured_groups - groups_by_name.keys()):
        message = f"vlan group '{name}' does not exist in NetBox"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
    groups = {group.id: group for group in groups_by_name.values()}
    missing_groups = sorted(
        {vlan.group.id for vlan in candidates if vlan.group} - groups.keys()
    )
    if missing_groups:
        for group in self.bulk_filter(
            nb.ipam.vlan_groups,
            id=missing_groups,
            fields="id,name,vid_ranges,scope_type,scope_id,scope",
        ):
            groups[group.id] = group
    if not live_by_device:
        message = "no live VLAN data collected"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
        ret.failed = True
        return ret
    live_vlans = [
        vlan
        for vlan in live_vlans
        if not vlan["selected_group_name"]
        or vlan["selected_group_name"] in groups_by_name
    ]
    for vlan in live_vlans:
        group = groups_by_name.get(vlan.pop("selected_group_name"))
        vlan["selected_group_id"] = group.id if group else None

    message = f"loaded {len(candidates)} NetBox VLAN candidate(s) and {len(groups)} VLAN group(s)"
    job.event(message)
    log.info(message)
    # Resolve VLAN scopes and apply per-device preservation and shared-source rules.
    contributors = {}
    from_live = {
        device: {"vlans": {}, "interfaces": {}} for device in live_by_device
    }
    from_netbox = {
        device: {"vlans": {}, "interfaces": {}} for device in live_by_device
    }
    ret.diff = {
        device: {
            "vlans": {},
            "interfaces": {"create": [], "update": {}, "delete": [], "in_sync": []},
        }
        for device in from_live
    }
    preview = {
        device: {
            action: set() for action in ("created", "updated", "deleted", "in_sync")
        }
        for device in from_live
    }
    completed_refs = {}
    scope_payloads = {}
    vlan_records = {}
    sources = {}
    interface_targets = {}
    for resolved in resolve_live_vlans(
        live_vlans, candidates, groups, device_scopes
    ):
        observation, existing = (resolved["live"], resolved["vlan"])
        device, vid = (observation["device_name"], observation["vid"])
        if resolved["error"]:
            message = (
                f"vlan {vid} from device '{device}' skipped: {resolved['error']}"
            )
            if observation["selected_group_id"]:
                message += (
                    "; fix the VLAN group scope, VID ranges, or group mapping"
                )
            job.event(message, severity="ERROR")
            log.error(message)
            ret.errors.append(message)
            continue
        scope = resolved["scope"]
        contributors.setdefault((scope, vid), set()).add(device)
        # Keep each device's values so shared VLANs do not mix their diffs.
        desired = {
            "name": observation["name"],
            "description": observation["description"],
        }
        if existing is not None:
            current = {
                "name": str(existing.name).strip(),
                "description": str(existing.description or "").strip(),
            }
            from_netbox[device]["vlans"][vid, scope] = current
            if preserve_name or desired["name"].casefold() == f"vlan{vid}":
                desired["name"] = current["name"]
            desired["description"] = apply_description_policy(
                desired["description"], current["description"], preserve_description
            )
        from_live[device]["vlans"][vid, scope] = desired
        scope_payloads[scope] = resolved["scope_payload"]
        key = (scope, vid)
        vlan_records[key] = existing
        # Remember which device supplies each field when VLANs are shared.
        if key not in sources:
            sources[key] = {
                field: (device, observation[field])
                for field in ("name", "description")
            }
        else:
            source_device, source_name = sources[key]["name"]
            name = observation["name"]
            automatic_name = f"VLAN{vid}".casefold()
            if (
                source_name.casefold() == automatic_name
                and name.casefold() != automatic_name
            ):
                sources[key]["name"] = (device, name)
            elif (
                source_name != name
                and source_name.casefold() != automatic_name
                and name.casefold() != automatic_name
            ):
                message = f"{scope} VLAN {vid} source conflict (name): using VLAN name '{source_name}' from device '{source_device}'; conflicting device '{device}' reports VLAN name '{name}'"
                if message not in ret.errors:
                    job.event(message, severity="ERROR")
                    log.error(message)
                    ret.errors.append(message)
            source_device, description = sources[key]["description"]
            if observation["description"] and not description:
                sources[key]["description"] = (device, observation["description"])
            elif (
                description
                and observation["description"]
                and description != observation["description"]
            ):
                message = f"{scope} VLAN {vid} source conflict (description): using live description from device '{source_device}'; conflicting device '{device}' reports a different description"
                if message not in ret.errors:
                    job.event(message, severity="ERROR")
                    log.error(message)
                    ret.errors.append(message)
        vlan_reference = f"{scope}/{vid}"
        for field in VLAN_MEMBERSHIP_FIELDS:
            for live_interface in observation[field]:
                interface = interface_names_by_device[device][live_interface]
                target = interface_targets.setdefault(
                    (device, interface),
                    {"tagged_vlans": set(), "untagged_vlan": None},
                )
                if field == "tagged_interfaces":
                    target["tagged_vlans"].add(vlan_reference)
                else:
                    target["untagged_vlan"] = vlan_reference
    skipped_vlans = set()
    # Catch name conflicts before one invalid VLAN can fail a whole batch.
    proposed_names = {
        from_live[fields["name"][0]]["vlans"][vid, scope]["name"]
        for (scope, vid), fields in sources.items()
    }
    name_matches = []
    if proposed_names:
        name_matches = self.bulk_filter(
            nb.ipam.vlans,
            name=sorted(proposed_names),
            fields="id,vid,name,site,group",
        )
    names_in_netbox = {}
    for vlan in name_matches:
        scope = (
            f"group:{vlan.group.name}"
            if vlan.group
            else f"site:{vlan.site.name}" if vlan.site else "global"
        )
        names_in_netbox.setdefault((scope, str(vlan.name)), []).append(vlan)
    seen_names = {}
    for (scope, vid), fields in sources.items():
        name = from_live[fields["name"][0]]["vlans"][vid, scope]["name"]
        existing = vlan_records[scope, vid]
        conflicts = [
            vlan.vid
            for vlan in names_in_netbox.get((scope, name), ())
            if existing is None or vlan.id != existing.id
        ]
        conflict = conflicts[0] if conflicts else seen_names.get((scope, name))
        if conflict is None:
            seen_names[scope, name] = vid
            continue
        action = "update" if existing is not None else "create"
        skipped_vlans.add((scope, vid))
        if existing is not None:
            seen_names[scope, str(existing.name).strip()] = vid
        else:
            # Remove assignments to VLANs whose creation was skipped.
            reference = f"{scope}/{vid}"
            for target in interface_targets.values():
                target["tagged_vlans"].discard(reference)
                if target["untagged_vlan"] == reference:
                    target["untagged_vlan"] = None
        label = "VLAN" if conflicts else "vlan"
        message = f"{label} {vid} name '{name}' overlaps with VLAN {conflict} in scope '{scope}'; skipping VLAN {action}"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
    # Compare all device VLANs before collecting shared NetBox writes.
    vlan_diff = DeepDiff(
        {device: data["vlans"] for device, data in from_netbox.items()},
        {device: data["vlans"] for device, data in from_live.items()},
        ignore_order=True,
        view="tree",
        threshold_to_diff_deeper=0,
    )
    changed_vlans = {
        tuple(change.path(output_format="list")[:2])
        for changes in vlan_diff.values()
        for change in changes
    }
    # Report VLAN drift per device, even when devices share one NetBox VLAN.
    for device in from_live:
        ret.result[device] = {action: [] for action in preview[device]}
        before = from_netbox[device]["vlans"]
        after = from_live[device]["vlans"]
        for vid, scope in sorted(before.keys() | after.keys()):
            key = (vid, scope)
            summary = ret.diff[device]["vlans"].setdefault(
                scope, {"create": [], "update": {}, "delete": [], "in_sync": []}
            )
            if key not in before:
                summary["create"].append(vid)
            elif key not in after:
                summary["delete"].append(vid)
            elif (device, key) in changed_vlans:
                summary["update"][str(vid)] = {
                    field: {"old_value": before[key][field], "new_value": value}
                    for field, value in after[key].items()
                    if value != before[key][field]
                }
            else:
                summary["in_sync"].append(vid)
                preview[device]["in_sync"].add(f"{scope}:{vid}")

    # Deduplicate writes when several device diffs target the same VLAN.
    creates, updates = {}, {}
    for changes in vlan_diff.values():
        for change in changes:
            path = change.path(output_format="list")
            device, (vid, scope) = path[:2]
            if (vid, scope) not in from_live[device]["vlans"]:
                continue
            # Keep skipped VLAN drift visible without including it in write batches.
            if (scope, vid) in skipped_vlans:
                continue
            existing = vlan_records[scope, vid]
            if existing is None:
                creates[scope, vid] = {
                    "vid": vid,
                    **{
                        field: from_live[source]["vlans"][vid, scope][field]
                        for field, (source, _) in sources[scope, vid].items()
                    },
                    **scope_payloads[scope],
                }
            else:
                # Read only the changed field from the device selected for that field.
                field = path[2]
                source, _ = sources[scope, vid][field]
                value = from_live[source]["vlans"][vid, scope][field]
                # Another device's drift may select a value already present in NetBox.
                if value != from_netbox[device]["vlans"][vid, scope][field]:
                    updates.setdefault((scope, vid), {"id": existing.id})[
                        field
                    ] = value
    creates, updates = sorted(creates.items()), sorted(updates.items())
    # Report each shared VLAN write under every device that contributed to it.
    for action, items in (("created", creates), ("updated", updates)):
        for (scope, vid), _ in items:
            refs = [
                (device, action, f"{scope}:{vid}")
                for device in sorted(contributors[scope, vid])
            ]
            completed_refs[action, (scope, vid)] = refs
            for device, _, label in refs:
                preview[device][action].add(label)

    # Load interface assignments and preserve VLANs outside the selected filter.
    netbox_interfaces = self.bulk_filter(
        nb.dcim.interfaces,
        device_id=sorted((device.id for device in nb_devices.values())),
        fields="id,name,device,mode,tagged_vlans,untagged_vlan",
    )
    interfaces = {}
    for interface in netbox_interfaces:
        key = (str(interface.device.name), str(interface.name))
        if key in interface_targets:
            interfaces[key] = interface
    message = f"loaded {len(interfaces)} NetBox interface(s) for VLAN membership"
    job.event(message)
    log.info(message)
    for device, name in sorted(interface_targets.keys() - interfaces.keys()):
        message = f"interface '{device}:{name}' not found in NetBox"
        job.event(message, severity="ERROR")
        log.error(message)
        ret.errors.append(message)
    assigned_vlan_ids = set()
    for key in interfaces:
        interface = interfaces[key]
        assigned_vlan_ids.update((vlan.id for vlan in interface.tagged_vlans))
        if interface.untagged_vlan:
            assigned_vlan_ids.add(interface.untagged_vlan.id)
    membership_vlans = {vlan.id: vlan for vlan in candidates}
    # Include assigned VLANs outside the filter so existing memberships survive.
    missing_vlan_ids = assigned_vlan_ids - membership_vlans.keys()
    if missing_vlan_ids:
        for vlan in self.bulk_filter(
            nb.ipam.vlans,
            id=sorted(missing_vlan_ids),
            fields="id,vid,name,description,site,group",
        ):
            membership_vlans[vlan.id] = vlan
    vlan_id_by_reference = {}
    vlan_reference_by_id = {}
    for vlan in membership_vlans.values():
        if vlan.group:
            scope = f"group:{vlan.group.name}"
        elif vlan.site:
            scope = f"site:{vlan.site.name}"
        else:
            scope = "global"
        vlan_reference = f"{scope}/{vlan.vid}"
        vlan_id_by_reference[vlan_reference] = vlan.id
        vlan_reference_by_id[vlan.id] = vlan_reference
    # Compare memberships separately from VLAN names and descriptions.
    interface_states = {}
    for device, name in sorted(interface_targets):
        interface = interfaces.get((device, name))
        untagged_reference = None
        if interface and interface.untagged_vlan:
            untagged_reference = vlan_reference_by_id[interface.untagged_vlan.id]
        current = {
            "mode": interface.mode.value if interface and interface.mode else None,
            "tagged_vlans": sorted(
                (vlan_reference_by_id[vlan.id] for vlan in interface.tagged_vlans)
                if interface
                else ()
            ),
            "untagged_vlan": untagged_reference,
        }
        target = interface_targets[device, name]
        # Add live tagged VLANs while retaining existing NetBox assignments.
        tagged_vlans = set(current["tagged_vlans"])
        tagged_vlans.update(target["tagged_vlans"])
        untagged_vlan = current["untagged_vlan"]
        # Replace the native VLAN only when the device reports one.
        if target["untagged_vlan"] is not None:
            untagged_vlan = target["untagged_vlan"]
        mode = current["mode"]
        if tagged_vlans:
            mode = "tagged"
        elif untagged_vlan:
            mode = "access"
        desired = {
            "mode": mode,
            "tagged_vlans": sorted(tagged_vlans),
            "untagged_vlan": untagged_vlan,
        }
        interface_states[device, name] = (current, desired)
        for snapshot, state in ((from_netbox, current), (from_live, desired)):
            references = set(state["tagged_vlans"])
            if state["untagged_vlan"]:
                references.add(state["untagged_vlan"])
            # Include tagging and mode in each device/interface/VLAN/scope entry.
            for reference in references:
                scope, vid = reference.rsplit("/", 1)
                snapshot[device]["interfaces"][name, int(vid), scope] = {
                    "tagged": reference in state["tagged_vlans"],
                    "untagged": reference == state["untagged_vlan"],
                    "mode": state["mode"],
                }
    interface_diff = DeepDiff(
        {device: data["interfaces"] for device, data in from_netbox.items()},
        {device: data["interfaces"] for device, data in from_live.items()},
        ignore_order=True,
        view="tree",
        threshold_to_diff_deeper=0,
    )
    changed_memberships = {
        tuple(change.path(output_format="list")[:2])
        for changes in interface_diff.values()
        for change in changes
    }
    changed_interfaces = {
        (device, identity[0]) for device, identity in changed_memberships
    }
    interface_updates = {}
    for (device, name), (current, desired) in interface_states.items():
        if (device, name) not in changed_interfaces:
            ret.diff[device]["interfaces"]["in_sync"].append(name)
            continue
        # Format field changes only for interfaces selected by DeepDiff.
        ret.diff[device]["interfaces"]["update"][name] = {
            field: {"old_value": current[field], "new_value": value}
            for field, value in desired.items()
            if value != current[field]
        }
        if (device, name) in interfaces:
            interface_updates[device, name] = desired
    # Track membership actions to report when each interface write succeeds.
    for device in from_live:
        before = from_netbox[device]["interfaces"]
        after = from_live[device]["interfaces"]
        for key in sorted(before.keys() | after.keys()):
            name, vid, scope = key
            label = f"{scope}:{vid}"
            if (
                key in before
                and key in after
                and (device, key) not in changed_memberships
            ):
                if (device, (vid, scope)) not in changed_vlans:
                    preview[device]["in_sync"].add(label)
                continue
            if (device, name) in interfaces:
                # Membership changes update VLAN usage, not the VLAN record's existence.
                preview[device]["updated"].add(label)
                completed_refs.setdefault(
                    ("interfaces", (device, name)), []
                ).append((device, "updated", label))
    # Finalize the preview before approval or any NetBox writes.
    for device, actions in preview.items():
        actions["in_sync"] -= (
            actions["created"] | actions["updated"] | actions["deleted"]
        )
        ret.result[device]["in_sync"] = sorted(actions["in_sync"])
    for actions in preview.values():
        for action, values in actions.items():
            actions[action] = sorted(values)
    message = f"prepared {len(creates)} VLAN creation(s), {len(updates)} VLAN update(s), and {len(interface_updates)} interface update(s)"
    job.event(message)
    log.info(message)
    if dry_run:
        message = "dry-run requested, returning VLAN sync preview without changes"
        job.event(message)
        log.info(message)
        ret.result = preview
        return ret
    if with_approval and any(
        (
            actions[action]
            for actions in preview.values()
            for action in ("created", "updated", "deleted")
        )
    ):
        if not review_sync_task_result(job, "vlan sync", preview):
            ret.status, ret.dry_run, ret.result = ("skipped", True, preview)
            ret.messages.append("review declined; changes were not applied")
            message = "vlan sync review declined; changes were not applied"
            job.event(message)
            log.info(message)
            return ret
    # Create VLANs first so interface writes can use their new NetBox IDs.
    for stage, endpoint in (
        ("created", nb.ipam.vlans.create),
        ("updated", nb.ipam.vlans.update),
        ("interfaces", nb.dcim.interfaces.update),
    ):
        if stage == "created":
            items = creates
        elif stage == "updated":
            items = updates
        else:
            items = []
            for (device, name), desired in sorted(interface_updates.items()):
                items.append(
                    (
                        (device, name),
                        {
                            "id": interfaces[device, name].id,
                            "mode": desired["mode"],
                            "tagged_vlans": [
                                vlan_id_by_reference[ref]
                                for ref in desired["tagged_vlans"]
                            ],
                            "untagged_vlan": vlan_id_by_reference.get(
                                desired["untagged_vlan"]
                            ),
                        },
                    )
                )
        operation = {
            "created": "VLAN creation",
            "updated": "VLAN update",
            "interfaces": "interface update",
        }[stage]
        total = (len(items) + batch_size - 1) // batch_size
        # Batch writes across all devices, separately for each API operation.
        for start in range(0, len(items), batch_size):
            batch = items[start : start + batch_size]
            message = f"applying {operation} batch {start // batch_size + 1}/{total} ({len(batch)} object(s))"
            job.event(message)
            log.info(message)
            try:
                response = endpoint([payload for _, payload in batch])
            except Exception as exc:
                message = f"{message} failed: {exc}"
                ret.errors.append(message)
                ret.failed = True
                job.event(message, severity="ERROR")
                log.error(message)
                return ret
            if stage == "created":
                for ((scope, vid), _), vlan in zip(batch, response):
                    vlan_id_by_reference[f"{scope}/{vid}"] = vlan.id
            # Record completed actions only after the batch succeeds.
            for key, _ in batch:
                for device, action, label in completed_refs[stage, key]:
                    ret.result[device][action].append(label)
    for actions in ret.result.values():
        for action, values in actions.items():
            actions[action] = sorted(set(values))
    message = "vlan sync complete"
    job.event(message)
    log.info(message)
    return ret