Guides / Networking
Connect a Linux machine to a VPC
Follow these steps to take a Linux machine from a fresh key pair to a working ping inside a VPC.
The machine opens a WireGuard tunnel to a gateway and carries a VXLAN or Geneve device inside it, so it sees the VPC as an Ethernet segment. You make the key on the machine, and Etorm only ever sees the public half.
This needs a gateway. A VPC created without a gatewayRef joins the platform's hub when one exists. Without a hub it is a control-plane-only segment. Check with kubectl get vpc lan -o jsonpath='{.spec.gatewayRef}'.
1. Make a key pair on the machine
The private key stays in member.key on this machine.
umask 077 wg genkey | tee member.key | wg pubkey > member.pub cat member.pub
2. Create the Account with the public key
apiVersion: network.etorm.com/v1alpha1
kind: Account
metadata: {name: laptop}
spec:
vpcRef: {name: lan}
publicKey: <contents of member.pub>
A public key can belong to only one Account per gateway. A second Account with the same key is Failed with reason DuplicatePublicKey.
3. Read the generated configuration
The Account's status carries a wg-quick file and the ip commands that create the L2 device. The file has the placeholder <PRIVATE_KEY> where your key goes. Save both and fill in the key locally.
kubectl ... get account laptop -o jsonpath='{.status.config.wireguard}' > wg-etorm.conf
kubectl ... get account laptop -o jsonpath='{.status.config.script}' > l2.sh
sed -i "s|<PRIVATE_KEY>|$(cat member.key)|" wg-etorm.conf
cat l2.sh # read it before you run it
4. Bring the tunnel and the device up
sudo wg-quick up ./wg-etorm.conf # the interface is named after the file: wg-etorm sudo sh l2.sh # creates etm<vni> with your overlay address
In a VPC with DHCP, leave out the ip addr add line of the script and run a DHCP client on the new device instead (for example udhcpc -i etm<vni>). In an IPv6-only VPC the address comes from the prefix and your MAC, so nothing else is needed.
5. Check that traffic flows
You should see a recent handshake, replies to the ping and an address on the new device.
wg show wg-etorm # a recent handshake ping -c3 <another member or the VPC service address> ip -br addr show
6. See the machine in the console
Open the VPC in the console. Its page ends with Network, which lists the connected devices (connected, idle or never, endpoint, last handshake, bytes in and out). Below that is the ARP and NDP table the gateway sees, with the account behind each MAC address.
Every device is a Device object that the gateway writes about every 30 seconds. You can list them with kubectl get devices, or open Device in the explorer. A device that just joined shows up within half a minute.
This is the gateway's view. Its neighbors are the hosts that talked to the gateway or through it, not each member's own table. On a member, ip -6 neigh and ip neigh show that host's own.
MTU, key rotation and firewalls
- The overlay MTU is lower than the physical one, at most 1350 on an IPv6 underlay. The real value is in
status.mtu. - To rotate the key, generate a new pair and update
spec.publicKey. Then bring the tunnel up again with the new configuration. - The gateway accepts tunnel traffic only from authenticated peers. WireGuard needs UDP on the gateway's endpoint port, so open it in any firewall between the machine and the gateway.
Clean up
sudo wg-quick down ./wg-etorm.conf # on the machine; the L2 device goes with the tunnel kubectl ... delete account laptop # frees the public key and the address
Next
Manage DNS records for names inside the VPC, or run your own gateway.