Create a private network with VLANs using the Linode API
This guide shows you how to use Linode's API to create and attach a VLAN to a Compute Instance.
You can attach a Compute Instance to a VLAN in three different ways using the Linode API:
- As part of the configuration of a new Compute Instance using the Linode Create (POST /linodes/instances) endpoint.
- By creating a new configuration profile for a Compute Instance using the Configuration Profile Create (POST /linode/instances/{linodeId}/configs) endpoint.
- By editing an existing configuration profile of a Compute Instance using the Configuration Profile Update (/linode/instances/{linodeId}/configs/{configId}) endpoint.
The steps in this guide can be adopted to create and use VLANs for your specific use case.
When you attach a Compute Instance to a VLAN and reboot the Compute Instance, Network Helper generates network configurations for the specified network interfaces if it is enabled. You can enable Network Helper by default using the Account Settings Update (PUT /account/settings) endpoint. The Compute Instance must be rebooted for any changes within its network interfaces to take effect.
Configuring VLANs with the interfaces array
VLANs are managed by the interfaces
array of a Compute Instance's configuration profile. The interfaces
array consists of up to three network interface objects which correspond to the eth0, eth1, and eth2 interfaces according to their position in the array as follows:
Array Order | Array Index | Interface | Example Interface Object |
---|---|---|---|
First | 0 | eth0 | {"purpose":"public"} |
Second | 1 | eth1 | {"purpose":"vlan", "label":"vlan-1", "ipam_address":"10.0.0.1/24"} |
Third | 2 | eth2 | {"purpose":"vlan", "label":"vlan-2", "ipam_address":"10.0.0.2/24"} |
If no
interfaces
array is submitted with a request, the Compute Instance is automatically configured with its assigned public and private IPv4 addresses only.
Configuring the purpose of an interface
The purpose
of a network interface is required and used to determine whether an interface provides access to either the public internet or a VLAN:
-
public
: Configures a network interface for the public internet and enables the public (and private) IP address(es) for that Compute Instance. If no network interface is configured aspublic
, the Compute Instance will not be able to access the internet or other Linodes within the data center's main private network. -
vlan
: Configures a network interface for the labeled VLAN and enables the Compute Instance to communicate over theipam_address
if one is specified.
The Public Internet must always be set to use the network interface
eth0
.
Configuring the label of an interface
When configuring a vlan
purpose network interface, a VLAN can be selected by specifying its label
. Compute Instances that are attached to the same VLAN can privately communicate with each other over their respective vlan
purpose interfaces.
If the label
doesn't correspond with an existing VLAN, a new VLAN is created. VLANs that already exist on an account can be viewed, along with their region and attached Compute Instances, using the VLANs List (GET /network/vlans) endpoint.
No
label
is specified forpublic
purpose interfaces. You can simply omit the property, or enter an empty string ornull
.
Configuring the IPAM address of an interface
IPAM (IP Address Management) is the system that allows users to assign and manage IP addresses for each VLAN configured on a Compute Instance. When attaching a vlan
purpose interface to a Compute Instance, the ipam_address
can be specified in address/netmask format. This should be a unique IP address that doesn't already exist within the VLAN or on the public internet. It is common to use an address within the 10.0.0.0/8 range (10.0.0.0 – 10.255.255.255). For example, here are typical IPAM addresses for two Compute Instances connected to the same VLAN:
- Compute Instance 1:
10.0.0.1/24
- Compute Instance 2:
10.0.0.2/24
Just like public and private IP addresses, IPAM addresses for a VLAN are automatically configured on a Compute Instance through Network Helper. If Network Helper is disabled or if no ipam_address
is provided, the Compute Instance will not automatically be able to communicate over the VLAN. In some cases, advanced users may disable Network Helper or refrain from providing an ipam_address
. When doing so, the Compute Instance's internal network configuration files must be manually adjusted with the desired settings.
No
ipam_address
is specified forpublic
purpose interfaces. You can simply omit the property, enter an empty string, or enternull
.
IPAM addresses for a Compute Instance must be unique among its interfaces.
Example interfaces array
To illustrate each of the above configurations, the following interfaces
array configures a Compute Instance's assigned public (and private) IP address(es) configured on eth0, the IPAM address 10.0.0.1/24
for the VLAN labeled vlan-1
configured on eth1, and the IPAM address 10.0.0.2/24
for the VLAN labeled vlan-2
configured on eth2:
"interfaces": [
{
"purpose": "public"
},
{
"purpose": "vlan",
"label": "vlan-1",
"ipam_address": "10.0.0.1/24"
},
{
"purpose": "vlan",
"label": "vlan-2",
"ipam_address": "10.0.0.2/24"
}
]
Attaching a VLAN to a new Compute Instance
To attach a VLAN to a new Compute Instance, send a request to the Linode Create (POST /linodes/instances) endpoint containing an interfaces
array that includes a vlan
purpose interface with the VLAN's label
and the desired ipam_address
.
The following request creates a 1GB Compute Instance utilizing the example interfaces
array from above:
curl -k -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "g6-nanode-1",
"region": "us-southeast",
"image": "linode/debian10",
"root_pass": "pl34s3us34s3cur3p4ssw0rd",
"interfaces": [
{
"purpose": "public"
},
{
"purpose": "vlan",
"label": "vlan-1",
"ipam_address": "10.0.0.1/24"
},
{
"purpose": "vlan",
"label": "vlan-2",
"ipam_address": "10.0.0.2/24"
}
]
}' \
https://api.linode.com/v4/linode/instances
An
image
must be specified to set interfaces when creating a new Compute Instance.
Attaching a VLAN to an existing Compute Instance
You can attach a VLAN to an existing Compute Instance by either creating a new configuration profile or updating an existing configuration profile for the Compute Instance. In either case, the Compute Instance must be rebooted to allow Network Helper to automatically adjust the necessary network configuration files on the Compute Instance.
The Compute Instance's ID is required to use these methods. Use the Linodes List (GET /linode/instances) endpoint to retrieve the IDs of each of your Compute Instances. To view the Disk IDs of a Compute Instance, use the Disks List (GET /linode/instances/{linodeId}/disks) endpoint.
Creating a configuration profile
-
To attach a VLAN to an existing Compute Instance using a new configuration profile, send a request to the Configuration Profile Create (POST /instances/{linodeId}/configs) endpoint containing an
interfaces
array that includes avlan
purpose interface with the VLAN'slabel
and the desiredipam_address
.The following request creates a configuration profile utilizing the example
interfaces
array from above:curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ "label": "Example VLAN Config", "devices": { "sda": { "disk_id": 111, "volume_id": null }, "sdb": { "disk_id": 222, "volume_id": null } }, "interfaces": [ { "purpose": "public" }, { "purpose": "vlan", "label": "vlan-1", "ipam_address": "10.0.0.1/24" }, { "purpose": "vlan", "label": "vlan-2", "ipam_address": "10.0.0.2/24" } ] }' \ https://api.linode.com/v4/linode/instances/123/configs
Note the new Configuration Profile's ID from the response.
-
Reboot your Compute Instance with the new Configuration Profile's ID using the Linode Reboot (POST /linode/instances/{linodeId}/reboot) endpoint.
curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ "config_id": 23456 }' \ https://api.linode.com/v4/linode/instances/123/reboot
Updating a configuration profile
-
To attach a VLAN to an existing Compute Instance using an existing configuration profile, first retrieve the Configuration Profile's ID using the Configuration Profiles List (GET /linode/instances/{linodeId}/configs) endpoint.
curl -H "Authorization: Bearer $TOKEN" \ https://api.linode.com/v4/linode/instances/123/configs
-
Using the Compute Instance's current Configuration Profile ID, send a request to the Configuration Profile Update (PUT /linode/instances/{linodeId}/configs/{configId}) endpoint containing an
interfaces
array that includes avlan
purpose interface with the VLAN'slabel
and the desiredipam_address
.The following request updates a configuration profile utilizing the example
interfaces
array from above:curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X PUT -d '{ "interfaces": [ { "purpose": "public" }, { "purpose": "vlan", "label": "vlan-1", "ipam_address": "10.0.0.1/24" }, { "purpose": "vlan", "label": "vlan-2", "ipam_address": "10.0.0.2/24" } ] }' \ https://api.linode.com/v4/linode/instances/123/configs/23456
When updating a Configuration Profile's
interfaces
array, the previous interface configurations are overwritten. Any interfaces you wish to keep attached to a Compute Instance must be redefined when updating its Configuration Profile. -
Reboot your Compute Instance with the new Configuration Profile's ID using the Linode Reboot (POST /linode/instances/{linodeId}/reboot) endpoint.
curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ "config_id": 23456 }' \ https://api.linode.com/v4/linode/instances/123/reboot
Updated about 1 month ago