Creating a Private Network with VLANs Using Linode's API

What is a VLAN?

Linode VLANs (Virtual Local Area Networks) are a completely free solution available to Linode Services used for enabling private networking in the cloud. Here are a few key features of VLANs:

• Privacy and security. Linodes on the same account and in the same region can be added to a VLAN, allowing for private and secure communications between those Linodes. The public internet can also be disabled on a Linode to provide even more security.

  Note

  VLANs are separate from Private IP Addresses. Private IPs are accessible to all Linodes in that same data center and can only be further restricted by firewall rules or additional internal configuration.

• Performance. A VLAN is configured as a Layer 2 networking device on a Linode and provides low latency for latency-sensitive applications.

• No additional charges. VLANs are available at no cost and network transfer over a VLAN does not count towards monthly transfer quotas.

Refer to the Common Use Cases for Linode LAN guide to view diagrams demonstrating example scenarios using the network interface configurations described above.

In this Guide

This guide shows you how to use Linode’s API to create and attach a VLAN to a Linode.

You can attach a Linode to a VLAN in three different ways using the Linode API:

• As part of the configuration of a new Linode using the Linode Create ( POST /linodes/instances) endpoint.
• By creating a new configuration profile for a Linode using the Configuration Profile Create ( POST /linode/instances/{linodeId}/configs) endpoint.
• By editing an existing configuration profile of a Linode 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.

Note

When you attach a Linode to a VLAN and reboot the Linode, 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 Linode 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 Linode’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:

Note

If no interfaces array is submitted with a request, the Linode 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 Linode. If no network interface is configured as public, the Linode 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 Linode to communicate over the ipam_address if one is specified.

Caution

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. Linodes 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 Linodes, using the VLANs List ( GET /network/vlans) endpoint.

Note

No label is specified for public purpose interfaces. You can simply omit the property, or enter an empty string or null.

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 Linode. When attaching a vlan purpose interface to a Linode, 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 Linodes connected to the same VLAN:

• Linode 1: 10.0.0.1/24
• Linode 2: 10.0.0.2/24

Just like public and private IP addresses, IPAM addresses for a VLAN are automatically configured on a Linode through Network Helper. If Network Helper is disabled or if no ipam_address is provided, the Linode 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 Linode’s internal network configuration files must be manually adjusted with the desired settings.

Note

No ipam_address is specified for public purpose interfaces. You can simply omit the property, enter an empty string, or enter null.

Note

IPAM addresses for a Linode must be unique among its interfaces.

Example Interfaces Array

To illustrate each of the above configurations, the following interfaces array configures a Linode’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 Linode

To attach a VLAN to a new Linode, 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 Linode 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

Note

An image must be specified to set interfaces when creating a new Linode.

Attaching a VLAN to an Existing Linode

You can attach a VLAN to an existing Linode by either creating a new configuration profile or updating an existing configuration profile for the Linode. In either case, the Linode must be rebooted to allow Network Helper to automatically adjust the necessary network configuration files on the Linode.

The Linode’s ID is required to utilize these methods. Use the Linodes List ( GET /linode/instances) endpoint to retrieve the IDs of each of your Linodes. To view the Disk IDs of a Linode, use the Disks List ( GET /linode/instances/{linodeId}/disks) endpoint.

Creating a Configuration Profile

1. To attach a VLAN to an existing Linode using a new configuration profile, send a request to the Configuration Profile Create ( POST /instances/{linodeId}/configs) 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 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.

2. Reboot your Linode 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

1. To attach a VLAN to an existing Linode 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
   

2. Using the Linode’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 a vlan purpose interface with the VLAN’s label and the desired ipam_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
   

   Note

   When updating a Configuration Profile’s interfaces array, the previous interface configurations are overwritten. Any interfaces you wish to keep attached to a Linode must be redefined when updating its Configuration Profile.

3. Reboot your Linode 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
   

Limitations

• VLANs are region-specific. Once created, a VLAN can only be attached to other Linodes within the same data center.

• An account can have up to 10 VLANs per region.

• A Linode can belong to a maximum of 3 VLANs. Since there are 3 configurable network interfaces on each Linode, up to 3 VLANs can be attached. If one of those network interfaces is configured for the public internet, there are 2 remaining network interfaces for use with VLANs.

• VLANs cannot be manually renamed by the user. If a VLAN’s label must be changed, a new VLAN can be created and all required Linodes can be attached to that new VLAN.

• VLANs cannot be manually deleted by the user. There is no need to manually delete a VLAN. If a VLAN is no longer needed, simply detach it from all Linodes. After this, it will automatically be deleted within a short timeframe.

• Network Helper is required for automatic configuration. If Network Helper has been disabled, the Linode will not automatically be able to communicate over the VLAN’s private network. In this case, advanced users can manually adjust their Linode’s internal network configuration files with the appropriate settings for their VLAN. See Manually configuring a VLAN on a Linode for instructions.

• The Public Internet must always use the eth0 network interface. While VLANs themselves can function without issue on the eth0 interface, the public internet on Linode will not be networked correctly on other interfaces.