Setting up virtual networks

Two deployed servers go onto a private network of their own, so each request that takes a {serviceId} runs once per server.

1. Choose a VLAN tag

Every network needs a localVlanId from 11 to 4094 that is not already in use. Get VLAN availability lists the tags taken and names the next free one as data.nextFreeVlanId:

curl --request GET \
  --url https://api.serverside.com/v1/networking/spn/vlan-availability \
  --header 'X-API-KEY: <api-key>'

2. Create the network

Create virtual network with the tag from step 1 as localVlanId:

curl --request POST \
  --url https://api.serverside.com/v1/networking/spn \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "backend",
  "type": "PRIVATE",
  "localVlanId": 100
}
'

The response's data.id is the network's id, the {spnId} of the later steps. A private network gets no subnet and no gateway from us. The servers on it use a private range you choose; this guide uses 10.20.0.0/24. Frames you tag inside it with 802.1Q VLAN ids of your own reach the other servers with their tags intact.

3. Pick each server's segment

A server joins a network on a segment, one of its logical interfaces. Get network capabilities lists the physical ports under data.availableInterfaces, each with its interfaceName, macAddress, the segmentId it belongs to and isConfigured for a port already in use, along with the bonding groups the hardware offers.

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/networking/capabilities \
  --header 'X-API-KEY: <api-key>'

Two layouts work:

• Tagged, on the existing segment. The segment that carries the public network untagged also carries the private one tagged with its localVlanId. No second cable is used.
• Native, on a second port. A free port becomes its own segment through Create logical interface, which takes the interfaceIds to put in it (one port, or several to bond), and the private network arrives there untagged.

4. Attach the servers

Assign service to virtual network once per server. For the tagged layout, segmentId is the segment of the server's first port with isConfigured set, and isNative is false:

curl --request POST \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/services/assign \
  --header 'X-API-KEY: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceId": "<service-id>",
  "segmentId": "<segment-id>",
  "isNative": false
}
'

A 202 means the change is on its way to the network equipment. Sending the request again with the same Idempotency-Key answers 202 with the original change; without a key, the same assignment sent once it is in place answers 204 and changes nothing.

5. Wait for the change

Two places report progress. Get service status carries networkChange, with a status of APPLYING or FAILED, the time it started (since) and a failureCategory when it failed. List service virtual networks shows each attachment's own status: ATTACHING, then ATTACHED or ATTACH_FAILED.

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/spns \
  --header 'X-API-KEY: <api-key>'

6. Configure the operating system

A tagged network needs a VLAN interface on the server, on top of the interface that carries the segment. Get bare metal service names it: each entry in interfaces is one segment, and its name is the interface a deployment writes on the host, either the port's own name or bond0, bond1 and so on for a bond, whose bondMode reads LACP. After a change to the server's segments, interfaces shows the layout the next deployment will write, and the host keeps its old interfaces until it is reinstalled.

On Linux with iproute2, where the segment's name is eno1 and the shell variable VLAN holds the network's tag:

ip link add link eno1 name eno1.$VLAN type vlan id $VLAN
ip addr add 10.20.0.1/24 dev eno1.$VLAN
ip link set eno1.$VLAN up

Give the second server 10.20.0.2/24, and the two reach each other over the private network. These commands do not survive a reboot; put the same settings in the distribution's network configuration (netplan on Ubuntu, /etc/network/interfaces on Debian, NetworkManager on RHEL-family systems) to keep them.

Private networks carry jumbo frames at an MTU of 9000, and every server on the network needs the same value on its private interface:

ip link set eno1 mtu 9000
ip link set eno1.$VLAN mtu 9000

Linux will not set a VLAN interface's MTU above that of the port it sits on, which is why the parent port eno1 goes to 9000 first. In the tagged layout that port also carries the public network untagged, and the higher MTU applies to it as well; a private network on a port of its own keeps the two apart.

Servers in different datacenters

Extending a private network between datacenters is coming soon. Until it ships, every server on a private network is in the same datacenter.

When it ships, a web cluster is the workload that suits it: web servers in two datacenters both serve public traffic and share sessions, a cache and uploaded files over the private network. Database clusters and Proxmox clusters belong on a private network inside one datacenter. Each waits on its other nodes: Patroni on etcd before the leader key changes, Galera and MySQL Group Replication before a write commits, Corosync before the cluster agrees which members are up. Inside one datacenter, every node gets its answer from the others quickly.

Taking a server off the network

Unassign service from virtual network takes the same serviceId and segmentId and reports progress the same way, through DETACHING to a detached state or DETACH_FAILED. List virtual network services shows who is still attached.

Delete virtual network removes the network once no server is attached to it and it holds no IP prefixes; see Errors for the refusals.

Removing a server's public network

A database or application server can drop its public network and stay reachable over the private network only. The public network detaches through the same Unassign service from virtual network call, run on the public network with the server's serviceId and the segmentId that carries it; List service virtual networks shows the public network among the server's attachments. Only the API can do this, since the cloud console removes private attachments and nothing else. Log in over the private address first, because SSH to the public address stops answering once it is detached.

Detaching the public network returns its addresses to the pool, and the server cannot be reinstalled without one: a deployment needs a primary IPv4 address on the native network and is otherwise refused with 422 PRIMARY_IPV4_REQUIRED. Attach a public network as the native network again, with an IPv4 address assigned, before the next deployment. The server also loses its own route to the internet, and we run no NAT gateway, so package updates and outbound calls have to pass through one of your servers that keeps a public address, set up as a NAT router or proxy on the private network.

Errors