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

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.