Guides / Networking
Run a gateway (operators and self-hosters)
If you run your own Etorm in solo mode, or operate gateways for the platform, this is how a Linux host becomes a gateway. Gateways are platform objects, so tenants never create them.
What the host needs
- Linux with the
ip,bridgeandwgtools, root (orCAP_NET_ADMIN,CAP_NET_RAW,CAP_SYS_ADMIN), and kernel support for WireGuard, VXLAN and Geneve. - A UDP port reachable by members (the port of the Gateway's
endpoint). - A WireGuard key pair for the gateway:
wg genkey | tee gateway.key | wg pubkey.
1. Create the Gateway object
Create it in the platform cluster, with the gateway's public key and the address members will reach. The endpoint may be a hostname or an IPv6 literal such as [2001:db8::1]:51820. If you leave out underlayCIDR, it defaults to a generated IPv6 unique-local /64.
apiVersion: network.etorm.com/v1alpha1
kind: Gateway
metadata: {name: gw1}
spec:
endpoint: gw1.example.com:51820
publicKey: <contents of gateway.pub>
2. Give the agent a read-only identity
The agent should not run with your own token. Create a service account with a role that can get, list and watch gateways, dhcpservices and dnsservices, and create a token for it (see Automate with a service account). With this identity the agent only reads the API.
If the host should also run Compute processes, the role needs to read programs, processes and vpcs as well. It also needs to update processes/status, which is where the agent reports how the processes are doing. Platform programs are loaded with read-only access to one platform bucket.
Do not give the agent standing rights on buckets/objects in your customers' projects. A stolen node token would then read all of a project's data. Object access for processes that use buckets is granted only in the project the gateway hosts, as an ordinary role that an administrator makes.
3. Run the agent
etorm gateway \ --server https://api.etorm.com --ca-file ca.pem \ --token-file agent.token --private-key-file gateway.key \ --gateway gw1 --apply
Without --apply the agent only prints what it would change, which is a good first run on a new host. --once runs a single pass, and --interval SECS sets the pause between passes (default 5). Leave the agent running, because it also serves DHCP, DNS and IPv6 router advertisements for the VPCs on this gateway.
What the agent changes on the host
- For each Compute process whose VPCs are all served by this gateway, the agent manages a raw Ethernet port on the VPC's bridge (the bridge is made promiscuous), the program running in-process, and its state in
DIR/compute. Status (node, usage, logs, next wake) is written back about every 30 seconds. - The interface
wg-etorm, with one peer per Account. - A bridge
br<vni>per VPC, andvx<vni>or one Geneve device per member. - It touches only links with those names, so other interfaces on the host are safe. If it cannot fetch the Gateway, or the Gateway stays
Pending, it changes nothing. - Check the result from the API:
kubectl get gateway gw1 -o jsonpath='{.status.phase} {.status.accountCount} accounts'.
Clean up
Stop the agent first. It only touches links named wg-etorm, br<vni> and vx<vni>, so those are the ones to remove with ip link del. Then delete the Gateway object. A Gateway that still serves VPCs cannot be deleted (409).
Next
Connect a Linux machine to a VPC, or Find out why something stays Pending.