Networks

Introduction

A network is a private address space your services share. Serverlets attached to the same network get a private IP address inside it and can reach each other directly — by IP or by name — without going through the public internet. A network works like a VPC: nothing in it is exposed unless you put a proxy in front.

A network lives in one region and spans every server in it. Two serverlets on different servers, or on different machines in your own private region, still see each other as if they were on one local network.

Creating a network

From the Networks page, click Create and fill in:

IPv4 and IPv6 are both on by default, and at least one of them has to stay enabled. Leave the subnets on Auto unless you need a specific range — Futrou picks one that doesn’t collide with any other network in the region or with the server’s own interfaces.

Subnet rules

Custom subnets must come from private address space:

• IPv4: 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16
• IPv6: fd00::/8

Public, loopback, link-local, multicast and carrier-grade NAT ranges are refused. A subnet can hold at most 4096 addresses (a /20), must not overlap another network in the region, and can’t overlap an address range already used on the server (for example a Docker network).

Once a network exists, you can switch a subnet to Auto or Disabled, but entering a different custom range is reserved for Futrou staff — create a new network if you need one.

Attaching serverlets

A serverlet joins networks through its Networks setting, which takes network names or IDs. A serverlet can be in several networks at once and gets an address in each of them.

A serverlet with no network selected automatically gets a private network of its own, created and removed with it. Networks you create yourself are never deleted automatically.

A proxy can also be limited to one network, so it only forwards traffic to serverlet instances whose addresses lie inside it.

Reaching other services by name

Inside a network, a serverlet is reachable by its name, the way services are in Docker Compose. A serverlet called db is available at the hostname db from any other serverlet in the same network:

psql -h db -U app

The name resolves to every healthy instance of that serverlet, in a different order on each lookup, so connections are spread across instances. Each serverlet is also reachable as serverlet-<id>. Unhealthy and stopped instances are left out of the answer.

If a serverlet belongs to several networks, a name is looked up in each of them in turn. Names are only visible inside the network — they are never resolvable from the internet. IPv4 only for now.

Across servers

When a network has serverlets on more than one server, Futrou connects the servers with encrypted WireGuard tunnels. Each server owns a slice of the network’s subnet and hands out addresses from it, so addresses never collide, and traffic to another server’s slice is routed through the tunnel automatically.

Every network uses its own random secret, mixed into the tunnel handshake, in addition to a per-server key pair that never leaves the server. Only servers that belong to the network can join it, and the secret is never shown in the dashboard or API.

A few things to know:

• Cross-server connectivity is IPv4. IPv6 addresses work only between serverlets on the same server.
• Servers with a public address connect to every other server directly. Servers behind NAT only dial out, so they need no open inbound port, and reach other private servers through a public one. At least one public server is needed for that.
• The tunnel keeps carrying traffic while Nasua is upgraded, so upgrades don’t interrupt connections between services.

Internal networks

Turning on Internal cuts the network off from the internet: serverlets can talk to each other but can’t make outgoing connections, and names that aren’t part of the network are not resolved. Use it for databases, queues and other services that should only ever talk to your own code.

Docker can’t change this flag on a running network, so flipping Internal restarts the serverlets in it.

Devices

A network’s page lists its devices — the running serverlet instances currently attached to it, newest first. For each one you see its hostname (<serverlet name>-<instance number>), IPv4 and IPv6 addresses, MAC address and when it connected.

Metrics and logs

The network’s page shows traffic over time — received and sent bytes, packets, errors and drops, with average and peak bits per second — across 30 seconds, 1 hour, 24 hours, 7 days and 30 days, summed over all servers. Idle networks record nothing.

The network log records its creation, changes, and servers joining or leaving the network. See Logs for the rest of what Futrou keeps.

Changing and deleting a network

Renaming a network is instant. Changing a subnet or the Internal flag recreates the network’s bridge on every server, which stops the serverlets attached to it and starts replacements with addresses from the new definition — expect a short interruption. Disabling an address family doesn’t restart anything, and re-enabling the same subnet later is free.

A network can’t be deleted while a serverlet or proxy still uses it; detach it first. Deleting a network removes its tunnels and metrics.

Using the CLI

futrou network create --name backend
futrou network create --name db --ipv4 10.100.0.0/24 --internal
futrou network ls
futrou network devices <id>
futrou network metrics <id>
futrou network update <id> --internal
futrou network rm <id>

Networks can also be declared in futrou.json / futrou.yaml and attached to serverlets there; see CLI.

Permissions

Viewing a network requires at least the Viewer role. Creating one requires permission to create networks in the project, and changing or deleting one requires permission to manage it. See Roles for what each role can do.