Equnix Metal
Loading...

VLANs on Equinix Metal

COMMAND LINE

Copy to clipboard

VLANs on Equinix Metal

Equinix Metal™ provides Layer 2 virtual networks to connect your servers and other infrastructure. Here are some things to know about our VLANs:

  • VLANs are available in all Metros and Facilities.
  • VLANs are Project-level infrastructure.
  • There is no additional cost to adding a VLAN to a Project.
  • The initial limit is 5 VLANs per project, and not all VLANs have to be in the same Metro. The limit can be increased by contacting support@equinixmetal.com.
  • A VLAN is local to a Metro. You cannot connect servers to a VLAN outside it's Metro.
  • VLANs support up to a 9000 byte maximum transmission unit (MTU) and jumbo Ethernet frames.

Creating a VLAN

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

Pick the Metro from the drop-down and give it a description. When you click Add, the VLAN is automatically provisioned.

Adding a VLAN to Your Project

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, send a POST request to the /projects/{id}/virtual-networks endpoint. The Project ID is a path parameter, and you give your VLAN a description, where it is provisioned, and an ID number (using a unique integer between 2 and 3999) 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/projects/{id}/virtual-networks" \
-d '{
    "vxlan": <integer>,
    "description": "<description>",
    "metro": "<metro_code>"
    }'

Using Your VLAN

Once you have a VLAN, you can configure any servers in the project to connect to it. The networking mode you choose for each server can vary by use-case, location, and high-availability concerns.

A summary of the different networking modes is on the Layer 2 Networking Overview page.

Details and instructions on how to convert to the different networking modes and configure your servers to connect to your VLANs are on the pages for each mode.

Assigning VLANs to Ports

You can attach VLANs to ports only after changing the network mode on the server, so documentation on how to do so is included on each of the networking mode pages, Hybrid Bonded Mode, Hybrid Unbonded Mode, and Pure Layer 2 Modes.

In general, you assign VLANs from the server's Network page in the Equinix Metal console. In the API, you assign a VLAN to a port by sending a POST to the /ports/{id}/assign endpoint.

Managing VLANs

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

VLANs listed on the Layer 2 page

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 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.

Viewing VLAN Port Assignments

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

List of VLANs attached to a Server

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

VLAN Port Assignments

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}

Bulk VLAN Operations

Equinix Metal supports VLAN assignment and unassignment operations in bulk through an asynchronous batch request process.

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

Adding multiple VLANs slide-out panel

The Equinix Metal console only supports assigning as a bulk operation. The API supports both bulk assignment and bulk unassignment.

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/{port uuid}/vlan-assignments/batches/{batch 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/{port uuid}/vlan-assignments/batches endpoint.

Removing VLANs from Ports

You can remove a VLAN from a port from the server's Network page, in the Layer 2 section. To remove a VLAN, click Remove, and when it asks for confirmation, click Yes.

Removing a VLAN

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 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".

Deleting a VLAN

From the project's IPs and Networks tab and click Layer 2. Click Delete next to the VLAN you are deleting, and click Yes to confirm.

Deleting a VLAN

Note that in order to delete a VLAN, you must first detach any devices that are attached to it, otherwise it will return an error.

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}

Note that you cannot delete a VLAN that has devices attached to it. Detach any devices first, otherwise it will return an error.

Facility-based VLANs

Prior to the introduction of Metros in April 2021, VLANs were provisioned at the facility-level, and VLANs could only connect servers in a single facility. VLANs provisioned before Metros continue to function in this manner; they continue to work as-is.

However, facility-based VLANs and metro-based VLANs are not compatible.

First, it is possible to have both facility and metro VLANs in the same project, but if you have a facility VLAN 1001, you cannot create a Metro VLAN 1001. And likewise, if you have a Metro VLAN 1002, you will not have a facility VLAN 1002.

Second, it is not possible to expand an existing facility-level VLAN into a Metro VLAN. You will need to provision an entirely new Metro-aware VLAN, and reconfigure your servers to use it.

Third, it is possible to stick with provisioning VLANs at the facility-level if your use-case warrants it, but the default experience in the console is Metro-based, and you will have to use the API. To create a VLAN, send a POST request to the /projects/{id}/virtual-networks endpoint. The Project ID is a path parameter, and you give your VLAN a description and the facility where it will be provisioned 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/projects/{id}/virtual-networks" \
-d '{
    "description": "<description>", 
    "facility": "<facility_code>"
    }'

Frequently
asked questions

Slack

Still stuck?

Join us on Slack

Get support from our team and community members.

Frequently asked questions

What 3rd party Managed Services?

Neutra trust fund narwhal, palo santo bicycle rights live-edge stumptown health goth portland selfies kinfolk woke. ssss Echo park irony artisan vaporware typewriter. Next level pinterest drinking vinegar lyft mumblecore af small batch heirloom VHS. Fixie banh mi asymmetrical trust fund.

What 3rd party Managed Services?

Neutra trust fund narwhal, palo santo bicycle rights live-edge stumptown health goth portland selfies kinfolk woke. ssss Echo park irony artisan vaporware typewriter. Next level pinterest drinking vinegar lyft mumblecore af small batch heirloom VHS. Fixie banh mi asymmetrical trust fund.

What 3rd party Managed Services?

Neutra trust fund narwhal, palo santo bicycle rights live-edge stumptown health goth portland selfies kinfolk woke. ssss Echo park irony artisan vaporware typewriter. Next level pinterest drinking vinegar lyft mumblecore af small batch heirloom VHS. Fixie banh mi asymmetrical trust fund.

Copied code to clipboard