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

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

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.