Enabling Talos KubeSpan WireGuard Mesh for Secure Cross‑Node Pod Traffic

Useful answer

To encrypt pod traffic between nodes in a Talos cluster, enable the built‑in KubeSpan feature; it creates a WireGuard mesh automatically, requiring only a MachineConfig change on each node.

Mechanism

When `machine.features.kubeSpan.enabled: true` is set in a MachineConfig, Talos automatically creates a WireGuard interface on each node, distributes peer public keys through the cluster, and adds routes for all pod CIDRs. The mesh therefore encrypts all traffic that stays inside the cluster.

Worked configuration

Apply a minimal MachineConfig patch to each worker node before it joins the cluster:

# Example MachineConfig fragment
machine:
  features:
    kubeSpan:
      enabled: true

Save this as kubespan.yaml and apply it with the Talos CLI:

# Run on a machine with cluster‑admin rights
talosctl apply-config -f kubespan.yaml

After the apply finishes, the node will bring up a WireGuard interface (typically wg0) and start routing pod CIDR traffic.

Verification steps

• Check that the interface exists: ip link show wg0 or wg show. You should see a private key, a peer, and an endpoint pointing to another node’s IP address.
• Deploy a pod on node A and another pod on node B. From the pod on A, run ping . Successful replies confirm encrypted cross‑node traffic.
• Measure throughput with iperf3 between the two pods. Compare the result with KubeSpan disabled (set enabled: false and re‑apply) to gauge the UDP overhead.
• Inspect Talos logs for any errors during the WireGuard handshake: journalctl -u talos. Look for “wireguard” messages that indicate successful key exchange.

Operational limits

• KubeSpan only secures traffic that remains inside the cluster; egress to the internet is unchanged.
• All nodes must have the setting enabled; a node without it will not be part of the encrypted fabric, leaving traffic to that node unprotected.
• WireGuard adds UDP encapsulation; high‑bandwidth workloads may see reduced raw throughput compared to plain CNI‑provided traffic, especially if the underlying network has high latency.
• The feature does not replace a CNI plugin, nor does it enforce NetworkPolicy; you still need those for pod‑level security and traffic control.
• Host‑level and network firewalls must allow UDP traffic on the WireGuard port (default 51820) between every pair of nodes; otherwise the mesh will fail to form.

Common mistakes

• Enabling KubeSpan on only a subset of nodes, which creates a partial mesh and leaves some pod traffic in clear text.
• Assuming the overlay encrypts north‑south or external traffic; it does not, so you still need separate encryption for internet traffic.
• Changing the setting without re‑applying the MachineConfig, which can cause a brief interruption of the WireGuard tunnel as peers re‑negotiate and may drop existing sessions.
• Neglecting firewall rules: UDP port 51820 (or the port specified in the config) must be allowed between all nodes at the host and network level; otherwise the mesh will not establish.

Rollback

If you need to disable KubeSpan, set enabled: false in the same MachineConfig fragment and re‑apply:

machine:
  features:
    kubeSpan:
      enabled: false

Running talosctl apply-config will tear down the WireGuard interfaces on the affected nodes. Verify the interface disappears before considering the rollback complete.

Version considerations

The exact MachineConfig path (`machine.features.kubeSpan.enabled`) and the `talosctl` sub‑commands for inspecting the mesh are version‑specific. Consult the release notes for your Talos version to confirm the schema and available commands before applying changes in production. You can also run talosctl get-config to view the current MachineConfig and verify the presence of the `kubeSpan` section.