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 one site-scoped VLAN group.

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 one site-scoped VLAN group."""
    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