Tenkai
Sign inStart for free
Skip to guide
Help center

Run servers anywhere with the cluster network

Mix Hetzner Cloud, DigitalOcean, Scaleway, Infomaniak Public Cloud and your own hardware in one cluster, linked by an encrypted WireGuard mesh.

The nodes of a cluster do not have to run at the same provider: one can run at Hetzner Cloud, another at DigitalOcean and a third in your home. Tenkai links them with the cluster network, a private network that WireGuard encrypts, because a provider's private network only links its own servers.

How Tenkai builds the cluster network

Each node gets a mesh address in 10.210.0.0/16, and opens an encrypted tunnel on UDP port 51820 to each other node, at its cluster network endpoint: the address it enrolled from, unless you gave it another one. The private key of a node never leaves it.

All traffic between nodes, including the networks of your environments in 10.211.0.0/16, runs over the cluster network.

What the firewall opens

Each node accepts UDP port 51820 only from the other nodes of its cluster. The ports of the runtime and of the cluster registry only answer on the cluster network.

If your provider has a firewall of its own, such as a cloud firewall or a security group, it must allow UDP port 51820 between the nodes. Otherwise setup stops and says that the edge node does not answer through the cluster network.

Add a server at home

You can enroll a server that runs in your home: a mini PC, a tower or an old laptop. It must run Debian or Ubuntu, and you must be able to log in to it as root. It also needs:

  • A public IPv4 address that does not change. The other nodes send their WireGuard traffic to it, and Tenkai connects to it over SSH there unless you give it another SSH address. Servers that share a private network do not each need one: see Link servers that share a private network.
  • Ports that the internet can reach. On your home router, forward the SSH port and UDP port 51820 to the server.
  • The architecture of the cluster. A Raspberry Pi is an ARM machine. It cannot join a cluster of x86 servers, such as the servers that Tenkai creates at Hetzner Cloud, DigitalOcean, Scaleway or Infomaniak Public Cloud. Make an ARM cluster for it.
  • No route to 10.210.0.0/16 or 10.211.0.0/16, for example from your home network or a VPN. Otherwise setup stops and lists the routes in conflict.

Two nodes both behind NAT, without a forwarded port, cannot link to each other unless they share a private network. A server behind a connection that shares one public address between many customers (CGNAT), as many mobile and fiber connections do, cannot join a cluster.

Run your home server as a worker node. A manager node needs a fast and stable link to the other managers, and the edge node receives all the public traffic of the cluster.

Servers behind one router all enroll from the address of the router, which Tenkai uses as their SSH address, public address and cluster network endpoint. An owner or admin corrects each one on the server page, with the pen beside it:

  • SSH address: the address and the port where Tenkai reaches the SSH server of this machine, such as a port that your router forwards to it. See Reach a server through a bastion or another port.
  • Public address: the IPv4 address where the internet reaches ports 80 and 443. Only the edge node needs it. Tenkai points the default routes of the cluster to it. Point the A records of your custom domains to it yourself.
  • Cluster network endpoint: the IPv4 address where the other nodes reach UDP port 51820. On one private network, give each server its own private address, such as 192.168.1.12.

The first setup of such a server fails unless port 22 of the router leads to it. Give the server its SSH address and its cluster network endpoint, then select Retry setup.

Set the cluster network endpoint before a second node joins the cluster: once two nodes are linked, or while a server of the cluster is being set up, Tenkai refuses the change.

A node has one endpoint for all the other nodes. Do not mix servers on a private network with a server outside it in one cluster: the server outside cannot reach a private address.

Limits

  • Distance adds latency. A replica can run on any node that accepts workloads, so a replica in Amsterdam may query a database in Falkenstein and wait for each round trip. Keep nodes in nearby regions.