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.

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 Linux with iproute2, where the public network's port 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

A private network is not limited to one datacenter. A server in another datacenter joins the same network through steps 3 to 6, with the same {spnId} and VLAN tag, and gets an address of its own in the private range, such as 10.20.0.3/24.

A web cluster is the workload that suits this layout. Web servers in two datacenters both serve public traffic, and over the private network they share sessions, a cache, uploaded files and deploys, and call each other's internal APIs. Splitting visitors between the two sites is your own setup, with DNS or load balancers you run. The private network does not encrypt what it carries between the datacenters; give the session store, cache and internal APIs TLS, or run WireGuard or IPsec between the servers.

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. The API refuses to delete a network that still has servers on it, so unassign every server first.

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.

Deploys and reinstalls still work on a server with no public network. It does lose 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.