Private networks (VPCs)
Servers you attach to a VPC talk to each other over a private address range that never touches the public internet — database traffic, clustering, internal APIs, and anything else you'd rather keep off the wire.
What a VPC gives you
VPCs live under Networking → VPCs. Each VPC is a software-defined private network with:
- A name you choose (for example,
prod-backend). - A private range (CIDR) — the block of addresses servers on the network use, like
10.10.0.0/24. - A region — the one region private networks are offered in today (see below).
- A status — a VPC shows Active once it's ready to use.
Once a VPC is active, you attach servers to it. Attached servers reach one another by their private addresses, with no public routing in between.
A VPC connects servers on one host
Today a private network lives on a single host, so only servers running on that same host can join it. A server on any other host — even in the same region — can't be attached: the request is refused before anything happens to the server, so it isn't rebooted or changed. The Servers panel marks those servers on another host so you can see which ones are eligible before you pick.
You can tell which host a server is on from the last part of its full name — two servers ending
-apollo share a host (see Servers). Where a new server lands is decided when it's
deployed, so a server in the right region isn't guaranteed to be on the network's host. Connecting
servers across hosts isn't available yet.
Create a VPC
Click New VPC and fill in the short form.
Name it
Give the network a name that says what it's for, like prod-backend. It only needs to be meaningful
to you.
Set the private range (CIDR)
Choose the address block servers on this network will use — the default is 10.10.0.0/24. Every server
you attach gets a private address from this range. Enter it in CIDR form with a mask between /16 and
/30, such as 10.10.0.0/24.
Check the region
Private networks are currently offered in one region — the one where the network's host sits — and
the form shows it. Only servers on that host can join (see the warning above). Asking for any other
region through the API is refused with vpc_region_unavailable, because a network there could never
have a server join it. If no region is available, the form says private networks aren't available right
now.
Create
Confirm, and the VPC is provisioned: we wait until the network is actually up on its host before showing it as Active, so this can take a few seconds. If provisioning fails, nothing is kept and you see an error — just try again.
You can hold up to 5 private networks.
Attach and detach servers
Open a VPC's Servers panel to manage what's connected. The Choose a server… dropdown lists your servers; the ones that can't join are greyed out with the reason next to the name:
| Shown as | Why it can't join |
|---|---|
| on another host | It runs on a different host from this network. A VPC is single-host today. |
| different region | It's in another region from the network. |
| still provisioning | It hasn't finished being created yet. |
| failed to provision | Its creation failed. |
| network not ready | The VPC itself is still being set up, or is being deleted. |
A server that's already on the network isn't listed again. The API gives the same answer: attaching a
server on another host returns 409 with the code vpc_host_mismatch, and nothing is changed on the
server. Your app can ask first with GET /vpcs/{id}/candidates, which returns each of your servers with
eligible, a reason and a message.
Right before attaching, we also check that the network is really up on the server's host. If it isn't, the
attach is refused with 409 vpc_network_missing and the server isn't touched — try again in a moment,
and contact support if it keeps happening.
Choose a server
In the VPC's Servers panel, pick a server from the Choose a server… dropdown.
Attach & reboot
Click Attach & reboot. We add a private NIC to the server and reboot it so the new interface comes up. The server shows Attaching… until its network slot is ready.
To remove a server, click Detach & reboot next to it in the same panel. Detaching removes it from the private network and frees its private address. Like attaching, this removes the private NIC by power-cycling the server, so expect the same brief interruption while it reboots.
Attaching reboots the server
Attaching a server adds a network interface and reboots it. Plan attachments for a moment when a quick restart is fine, and expect a brief interruption while the server comes back up.
If the server can't come back up with the new interface, the attach is undone: the private NIC is removed, a server that was running is started again, and it drops out of the network's list — that's how you can tell the attach didn't take. If it keeps happening, contact support.
If the server can't be started again after that, it stays stopped: start it from its page, and contact support if it won't start. A server that stays on Attaching… for more than a few minutes didn't finish cleanly — we keep it on the list rather than lose track of a private NIC that may be on it. Click Detach & reboot to clean it up (this removes the NIC if it's there), then attach it again if you still want it. A server can also show Attaching… after a reinstall, restore or start that found the network wasn't up on its host and left it without the private interface — see Firewalls, reinstalls and restores.
Private IPs are assigned for you
You don't pick per-server addresses. When you attach a server, we assign it a private IP automatically from
the VPC's range (IPAM) and show it next to the server in the Servers panel. Detach a server and that address
is released back to the range. The first two addresses in the range and the broadcast address at the end are
never handed out, so a /24 gives you hosts .2 through .254.
If the range has no free address left, the attach is refused rather than rebooting a server onto a NIC with no address. A VPC's range is fixed once created, so pick a larger CIDR up front if you plan to grow past it.
Firewalls, reinstalls and restores
- Firewall. A server's firewall also filters its private interface. With the firewall on, other servers on the VPC only reach it on the ports your rules allow. To let them talk freely, add an inbound Accept rule with the VPC's range as the Source.
- Reinstall. The server stays on its private networks, with the same private IP, before the fresh system first boots. In the rare case that can't be done right then, the server boots without its private interface rather than failing the reinstall, and it's added a moment later (the server restarts once) or, at the latest, the next time you start it. If the fresh system won't boot with its private interface, it's taken off and the server is booted once more without it; it comes back the next time you start the server. Only if that second boot can't be made either does the reinstall fail.
- Restoring a snapshot. The server's network is matched to the VPCs it's on now. A network it left after the snapshot isn't brought back, and one it joined after the snapshot stays.
- A network that isn't up on the server's host. Reinstalls, restores and every start re-check each private network on the server's own host before connecting it, because a server can't boot on a network its host doesn't have. A private interface the server doesn't have yet (a reinstall's fresh system, say) isn't added while the network isn't up there. A stopped server that already has a private interface on a network its host doesn't have at all (a restored snapshot can carry one) has that interface taken off before it starts, so it can boot. Either way the server runs without that network and shows Attaching… in the network's list, and it's connected again on a later start once the network is back. But if the host has the network and just doesn't report it up right then (for example while it's being reconfigured), a private interface the server already has is left in place — and if the network really is down, the server may not start. Try again in a few minutes; if it still won't start, detach it from the network or contact support.
While a server is being reinstalled, it can't be detached from a VPC. Wait until it's running again.
Automatic private addressing
Every attached server gets a private IP from the VPC's CIDR block automatically. Use these private addresses when you wire up services that should stay internal.
Delete a VPC
You can delete a VPC once it has no servers attached — the delete control stays disabled while any server is still on the network, so detach them all first. Deleting asks you to type the network's name to confirm.
Deleting removes the network
Deleting a VPC tears down its private network and can't be undone. Detach every server first, then delete. The attached servers keep running; they just lose their private interface on this network.
If the teardown fails — or we can't confirm the network is gone everywhere it might be — we keep the VPC rather than lose track of a network that's still out there: it stays in your list with a Teardown failed chip, refuses new attachments, and you can run the delete again.