NetBox Create VLAN Group Task

task API name: create_vlan_group

The create_vlan_group task creates or updates one VLAN group scoped to a NetBox site. The design engine uses it before allocating VLANs for a site.

Inputs

Parameter	Required	Default	Description
name	Yes	—	VLAN group name
site	Yes	—	Existing site used as the group scope
vid_ranges	Yes	—	Inclusive VLAN ID ranges, such as [[10, 99]]
instance	No	Worker default	NetBox instance to target
dry_run	No	False	Return the proposed action without writing
branch	No	None	NetBox Branching plugin branch name

Example

result = client.run_job(
    "netbox",
    "create_vlan_group",
    workers="any",
    kwargs={
        "name": "SITE-001 VLANS",
        "site": "SITE-001",
        "vid_ranges": [[10, 99]],
    },
)

In a design:

{% set vlan_group = netbox.create_vlan_group(name=context.site ~ " VLANS", site=context.site, vid_ranges=[[10, 99]]) %}

The site must exist before the task runs.

Python API Reference

Create or update a VLAN group scoped to one NetBox site.

Groups are matched by name, not by site. An existing group is patched with the supplied site and VID ranges. A dry run reports the planned action without writing to NetBox.

Parameters:

Name	Type	Description	Default
job	Job	Current NorFab job for events and branch provisioning.	required
name	str	VLAN group name used to find an existing group.	required
site	str	Name of the site that scopes the group; it must exist.	required
vid_ranges	list	Allowed VLAN ID ranges in the NetBox API format.	required
instance	Union[None, str]	NetBox instance name, or the worker default when omitted.	None
dry_run	bool	Report the planned create or update without writing.	False
branch	Union[None, str]	Optional NetBox Branching plugin branch name.	None

Returns:

Name	Type	Description
Result	Result	Group name, site, and ranges with a created or updated status.

Raises:

Type	Description
ValueError	The named site does not exist.

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

@Task(
    fastapi={"methods": ["POST"], "schema": NetboxFastApiArgs.model_json_schema()},
    input=CreateVlanGroupInput,
    output=CreateVlanGroupResult,
)
def create_vlan_group(
    self,
    job: Job,
    name: str,
    site: str,
    vid_ranges: list,
    instance: Union[None, str] = None,
    dry_run: bool = False,
    branch: Union[None, str] = None,
) -> Result:
    """Create or update a VLAN group scoped to one NetBox site.

    Groups are matched by name, not by site. An existing group is patched
    with the supplied site and VID ranges. A dry run reports the planned
    action without writing to NetBox.

    Args:
        job: Current NorFab job for events and branch provisioning.
        name: VLAN group name used to find an existing group.
        site: Name of the site that scopes the group; it must exist.
        vid_ranges: Allowed VLAN ID ranges in the NetBox API format.
        instance: NetBox instance name, or the worker default when omitted.
        dry_run: Report the planned create or update without writing.
        branch: Optional NetBox Branching plugin branch name.

    Returns:
        Result: Group name, site, and ranges with a created or updated status.

    Raises:
        ValueError: The named site does not exist.
    """
    instance = instance or self.default_instance
    ret = Result(
        task=f"{self.name}:create_vlan_group",
        result={"name": name, "site": site, "vid_ranges": vid_ranges},
        resources=[instance],
        dry_run=dry_run,
    )
    nb = self._get_pynetbox(instance, branch=branch, job=job)
    nb_site = nb.dcim.sites.get(name=site)
    if not nb_site:
        raise ValueError(f"Site '{site}' not found in NetBox")
    group = nb.ipam.vlan_groups.get(name=name)
    payload = {
        "name": name,
        "slug": slugify(name),
        "scope_type": "dcim.site",
        "scope_id": nb_site.id,
        "vid_ranges": vid_ranges,
    }
    if dry_run:
        ret.status = "updated" if group else "created"
    elif group:
        group.update(payload)
        ret.status = "updated"
    else:
        nb.ipam.vlan_groups.create(payload)
        ret.status = "created"
    job.event(f"{ret.status} VLAN group '{name}'")
    return ret