VLANs on Equinix Metal¶

You manage VLANs on the project's Layer 2 VLAN page. To provision a VLAN, click + Add VLAN.

• The only required field is Location. Pick the Metro where the VLAN is going to live from the drop-down.
• You can give your VLAN a friendly, human description in the Description field.
• The optional VNID field can be filled with integer between 2 and 3999 to serve as the VLAN ID. If omitted, the VLAN ID is auto-assigned incrementally by metro, starting at 1000.

Clicking Add provisions the VLAN. Once it's done provisioning, the new VLAN will be listed on the Layer 2 page. The assigned VLAN ID displayed here will be used when you attach servers to the VLAN.

To create a VLAN in the CLI, use the metal virtual-network create command.

metal virtual-network create -p <project_id> -m <metro_code> -vxlan <vlan>

Options:

• -p (required) - Your Project ID.
• -m (required) - The metro where you are creating the VLAN.
• --vxlan (optional) - Specify an integer between 2 and 3999 to serve as the VLAN ID. If omitted, the VLAN ID is auto-assigned incrementally by metro, starting at 1000.
• --description (optional) - A field for a friendly description of the VLAN.

To create a VLAN, send a POST request to the /projects/{id}/virtual-networks endpoint. Specify the project ID for VLAN in the path.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/virtual-networks" \
-d '{
    "vxlan": <integer>,
    "description": "<string>",
    "metro": "<string>"
    }'

Body Parameters:

• "metro" (required) - The two-letter metro code for where the VLAN is located.
• "vxlan" (optional) - An integer between 2 and 3999 to serve as the VLAN ID. If omitted, the VLAN ID is auto-assigned incrementally by metro, starting at 1000.
• "description" (optional) - A friendly, human description of the VLAN, if desired.

You manage VLANs on the project's Layer 2 VLAN page Each VLAN in the Project is listed with its ID, description, location, number of connections, and the option to Delete it.

If the VLAN is in use, you are able to see how many devices are connected to the VLAN in the Devices column, and clicking on the number will bring up a list of those devices.

To list all the VLANs in a project, use the metal virtual-network get command.

metal virtual-network get -p <project_id>

To list the VLANs in a Project, send a GET request to the /projects/{id}/virtual-networks endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/projects/{id}/virtual-networks

To get the details of a specific VLAN, send a GET request to the /virtual-networks/{id} endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/virtual-networks/{id}

If the VLAN is in use, the response to the GET contains a list of devices the VLAN is connected to in the "instances" field.

From the Server's Network tab, you can see which VLANs the server is attached to.

And in the Layer 2 section, you can see which ports the VLANs are assigned to.

You can view VLANs assigned to a port with the metal port get command, and using the --output command to specify getting the JSON response.

metal port get --port-id <port_id> --output json

To retrive a list of VLANs assigned to a port, send a GET request to the /ports/{id}/vlan-assignments/ endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/ports/{id}/vlan-assignments/

To retrieve an individual VLAN assignment's details, send a GET request to the /ports/{id}/vlan-assignments/{id} endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/ports/{id}/vlan-assignments/{id}

To assign multiple VLANs to a port, navigate to a server's Network tab, in the Layer 2 section. When you click Add New VLAN, you have the option to select multiple VLANs to add to the port.

If you are assining multiple VLANs to a port, you specify each VLAN in the the metal port vlan command.

metal port vlan --port-id <bond0_id> --assign <vlan> --assign <vlan>

If you are removing multiple VLANs, specify each VLAN you are removing.

metal port vlan --port-id <bond0_id> --unassign <vlan> --unassign <vlan>

To bulk assign or unassign VLANs to a port, send a POST request to the /ports/{id}/vlan-assignments/batches endpoint with array of VLAN assignments (or unassignments) in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN> " \
"https://api.equinix.com/metal/v1/ports/{id}/vlan-assignments/batches" \
-d '{
    "vlan_assignments": [
        {
            "vlan": "string",
            "state": "string"
        },
        {
            "vlan": "string",
            "state": "string"
        },
    ]
}'

To assign a VLAN to the port, set the "state" parameter to "assigned". To unassign a VLAN from a port, set the "state" parameter to "unassigned". You can both assign a set of VLANs and unassign another set of VLANs in the same request.

Since the process is an asynchronous batch process, it might not complete right away. To check the status of a VLAN Assignment batch's details, send a GET request to the /ports/{id}/vlan-assignments/batches/{id} endpoint. The response will return the state of each assignment or unassignment in the batch. The states are "queued", "in_progress", "completed", and "failed".

If you have made multiple batch requests to a port, you can retrieve a list of VLAN Assignment batches for that specific port by sending a GET request to the /ports/{id}/vlan-assignments/batches endpoint.

You can remove a VLAN from a port from the server's Network tab, in the Layer 2 section. Select the VLAN and click Remove.

Note, neither removing the VLAN from the port, nor clicking Delete as confirmation deletes the VLAN, it only removes it from the port.

In the CLI, remove a VLAN from a port with the metal port vlan command.

metal ports vlan --port-id <bond0_id> --unassign <vlan>

If you are removing multiple VLANs, specify each VLAN you are removing.

metal port vlan --port-id <bond0_id> --unassign <vlan> --unassign <vlan>

In the API, you remove a VLAN from a port by sending a POST to the /ports/{id}/unassign endpoint.

You have to specify the port ID the VLAN is going to be attached to in the path, and it needs to be the UUID for that port as returned by the /devices/{id} endpoint.

The ID of the VLAN is sent in the body of the request, and it can be either the VLAN's UUID as returned by the /projects/{id}/virtual-networks endpoint or the vxlan ID that is in the console.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN> " \
"https://api.equinix.com/metal/v1/ports/{id}/assign" \
-d '{
    "vnid": "c4032b18-5494-451b-a779-a7d3c536bfd7"
    }'

It is also possible to unassign VLANs to a port in bulk, as part of an asynchronous batch process. Send a POST request to the /ports/{id}/vlan-assignments/batches endpoint an array of VLAN assignments in the body of the request.

-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN> " \
"https://api.equinix.com/metal/v1/ports/{id}/vlan-assignments/batches" \
-d '{
    "vlan_assignments": [
        {
            "vlan": "string",
            "state": "unassigned"
        },
        {
            "vlan": "string",
            "state": "unassigned"
        },
    ]
}'

The VLAN can be identified by either the VLAN's UUID or the VLAN ID that is in the console. Since you are unassigning the VLAN from the ports, the "state" field should be "unassigned".

Open the Layer 2 VLAN page. Select the VLAN you want to delete and click Delete. If you wish to confirm multiple VLANs, select each VLAN you want to delete and click Delete.

To delete a VLAN, use the metal virtual-network delete command.

metal virtual-network delete --id <vlan_id>

To delete a VLAN, send a DELETE request to the /virtual-networks/{id} endpoint.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' https://api.equinix.com/metal/v1/virtual-networks/{id}