VLAN Groups¶

VLAN groups can be used to organize VLANs within Nautobot. Each group may optionally be assigned to a specific location, but a group cannot belong to multiple locations.

Groups can also be used to enforce uniqueness: Each VLAN within a group must have a unique ID and name. VLANs which are not assigned to a group may have overlapping names and IDs (including VLANs which belong to a common location). For example, you can create two VLANs with ID 123, but they cannot both be assigned to the same group.

VLAN Group Ranges¶

Added in version 2.3.6

VLAN Groups contain a mandatory range field with a default value of 1-4094 (permitting all VLANs). This field may be used to constrain the valid member VLANs of the group. VLANs can only be associated with a given VLAN Group if their VLAN identifiers ("VIDs") fall within the specified range. Range value accepts commas and dashes, with examples as follows:

1
1-5
1-5,10
1-5,10-15
1-5,10-15,16,17,18,19,20

Values between dashes will also be expanded into a list of VLANs.

Creating new VLANs in a VLANGroup programatically¶

Added in version 2.3.6

VLAN Groups offer an API endpoint to list available VIDs and create new VLANs programmatically:

/api/ipam/vlan-groups/<vlan_group_id>/available-vlans/

A GET request to this API endpoint will return a list of all available (unassigned) VIDs available in the given VLANGroup.

A POST request to the same API endpoint will create VLAN record(s) in the given VLANGroup. Note that you must specify the name and status of each VLAN to be created as a part of this request, but the vlan_group and vid may be omitted as they can be automatically assigned by this API. See below.

Creating VLANGroup example¶

To create a new VLANGroup with a range field of: 5-10 (permit VLANs 5, 6, 7, 8, 9, 10), issue following POST request:

curl -X POST -H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; version=2.0; indent=4" \
http://nautobot/api/ipam/vlan-groups/ \
--data '[{"name": "Enterprise VLANs", "range": "5-10"}]'

VLANGroup was created as follows:

[
    {
        "id": "c16d5d1d-40d6-4902-b89d-6294e60cb4bf",
        "object_type": "ipam.vlangroup",
        "display": "Enterprise VLANs",
        "url": "http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/",
        "natural_slug": "enterprise-vlans_c16d",
        "name": "Enterprise VLANs",
        "description": "",
        "range": "5-10",
        "location": null,
        "created": "2024-09-25T09:27:16.343655Z",
        "last_updated": "2024-09-25T09:27:16.343670Z",
        "notes_url": "http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/notes/",
        "custom_fields": {},
        "computed_fields": {},
        "relationships": {}
    }
]

Listing available VLANs example¶

Then, to list all available VLAN IDs within the just-created VLANGroup, issue a GET request:

curl -X GET -H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; version=2.0; indent=4" \
http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/available-vlans/

{
    "count": 6,
    "next": null,
    "previous": null,
    "results": [
        5,
        6,
        7,
        8,
        9,
        10
    ]
}

Creating new VLANs example¶

The /api/ipam/vlan-groups/<vlan_group_id>/available-vlans/ API endpoint accepts POST requests to create a new VLAN record, similar to the /api/ipam/vlans/ API endpoint. However, there are some characteristic differences in the behavior of /available-vlans/ with regard to its input and output:

Accepts a single dictionary as input to create 1 VLAN, in which case it returns a single dictionary describing the created VLAN
Accepts a list of dictionaries as input to create one or more VLANs, in which case it returns a list of VLAN objects
The fields name and status of are mandatory inputs for each VLAN to be created
The field vid is optional and might be specified to override auto-allocation for a given VLAN
- Will not accept a request with the same vid value specified multiple times
Will not accept a vlan_group attribute different than that already specified in the request's URL
Other VLAN model fields are permitted and optional
As with the /vlans/ endpoint, specifying locations in the POST request is not presently supported; you can make a subsequent call(s) to the /api/ipam/vlan-location-assignments/ endpoint to update the many-to-many association between the created VLAN(s) and desired Location(s)

To create two new VLANs, a data payload has to be specified. In the case of the first VLAN, its VLAN ID will be automatically determined based on VLANGroups availability, in the case of the second VLAN we explicitly request vid 8:

curl -X POST -H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json; version=2.0; indent=4" \
http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/available-vlans/ \
--data '[
{"name": "First VLAN", "status": "1e560c4d-07ef-4d49-af6e-c85aa1f295d3"},
{"name": "Second VLAN", "vid": 8, "status": "1e560c4d-07ef-4d49-af6e-c85aa1f295d3"}
]'

VLANs created:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "58bd2a10-33f7-45e2-93d2-f56be25dfe8c",
            "object_type": "ipam.vlan",
            "display": "First VLAN (5)",
            "url": "http://nautobot/api/ipam/vlans/58bd2a10-33f7-45e2-93d2-f56be25dfe8c/",
            "natural_slug": "58bd2a10-33f7-45e2-93d2-f56be25dfe8c_58bd",
            "vid": 5,
            "name": "First VLAN",
            "description": "",
            "vlan_group": {
                "id": "c16d5d1d-40d6-4902-b89d-6294e60cb4bf",
                "object_type": "ipam.vlangroup",
                "url": "http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/"
            },
            "status": {
                "id": "1e560c4d-07ef-4d49-af6e-c85aa1f295d3",
                "object_type": "extras.status",
                "url": "http://nautobot/api/extras/statuses/1e560c4d-07ef-4d49-af6e-c85aa1f295d3/"
            },
            "role": null,
            "tenant": null,
            "locations": [],
            "created": "2024-09-25T09:36:07.587950Z",
            "last_updated": "2024-09-25T09:36:07.587963Z",
            "tags": [],
            "notes_url": "http://nautobot/api/ipam/vlans/58bd2a10-33f7-45e2-93d2-f56be25dfe8c/notes/",
            "custom_fields": {},
            "computed_fields": {},
            "relationships": {}
        },
        {
            "id": "9b7c6b03-9140-4b00-940f-5dbcde173de1",
            "object_type": "ipam.vlan",
            "display": "Second VLAN (8)",
            "url": "http://nautobot/api/ipam/vlans/9b7c6b03-9140-4b00-940f-5dbcde173de1/",
            "natural_slug": "9b7c6b03-9140-4b00-940f-5dbcde173de1_9b7c",
            "vid": 8,
            "name": "Second VLAN",
            "description": "",
            "vlan_group": {
                "id": "c16d5d1d-40d6-4902-b89d-6294e60cb4bf",
                "object_type": "ipam.vlangroup",
                "url": "http://nautobot/api/ipam/vlan-groups/c16d5d1d-40d6-4902-b89d-6294e60cb4bf/"
            },
            "status": {
                "id": "1e560c4d-07ef-4d49-af6e-c85aa1f295d3",
                "object_type": "extras.status",
                "url": "http://nautobot/api/extras/statuses/1e560c4d-07ef-4d49-af6e-c85aa1f295d3/"
            },
            "role": null,
            "tenant": null,
            "locations": [],
            "created": "2024-09-25T09:36:07.634563Z",
            "last_updated": "2024-09-25T09:36:07.634578Z",
            "tags": [],
            "notes_url": "http://nautobot/api/ipam/vlans/9b7c6b03-9140-4b00-940f-5dbcde173de1/notes/",
            "custom_fields": {},
            "computed_fields": {},
            "relationships": {}
        }
    ]
}