Learn WireGuard - Docker & Container Networking

#Introduction

After a series of deployments on physical machines, it is time to bring WireGuard into the container world. Here the rules change: a container does not have full kernel access, so running the wg0 interface requires special capabilities that are not granted by default.

Episode 17 covers how to run WireGuard in Docker, the sidecar pattern for connecting a pod to an external network, and WireGuard's role as an overlay network between hosts in a distributed container environment.

#WireGuard in Docker

#Required Capabilities and Devices

To create a WireGuard interface, a container needs the right to manage the network namespace and access to the TUN device:

docker run -d \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --device=/dev/net/tun \
  -v /etc/wireguard:/etc/wireguard \
  -p 51820:51820/udp \
  linuxserver/wireguard

--cap-add=NET_ADMIN grants the right to manage interfaces, --device=/dev/net/tun provides access to the TUN device, and the -v /etc/wireguard:/etc/wireguard volume supplies the configuration from the host.

#Running the Container on the Host Network

Sometimes it is simpler to run WireGuard with network_mode: host, so the container shares the host's network namespace and no port mapping is needed:

services:
  wireguard:
    image: linuxserver/wireguard
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    volumes:
      - /etc/wireguard:/config
    environment:
      - PUID=1000
      - PGID=1000
      - SERVERPORT=51820
    network_mode: host
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1

With network_mode: host, the wg0 interface created by the container appears directly on the host, and forwarding between interfaces works natively.

#The Sidecar Pattern in Kubernetes

#One Pod, Two Containers

In Kubernetes, WireGuard is often run as a sidecar: a companion container inside the same pod as the main application. The sidecar brings up the tunnel, and the main application uses the same pod network namespace:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-dengan-wireguard
spec:
  selector:
    matchLabels:
      app: app-dengan-wireguard
  template:
    metadata:
      labels:
        app: app-dengan-wireguard
    spec:
      containers:
        - name: wireguard-sidecar
          image: linuxserver/wireguard
          securityContext:
            capabilities:
              add: ["NET_ADMIN"]
          volumeMounts:
            - name: wg-config
              mountPath: /config
        - name: aplikasi
          image: nginx
      volumes:
        - name: wg-config
          configMap:
            name: wg-client-config

The wireguard-sidecar container brings the tunnel up, and the app container uses that tunnel because they share the pod network namespace. The sidecar can also receive traffic forwarded to the application.

#WireGuard as an Overlay Network

#Connecting Container Hosts

Outside Kubernetes, WireGuard can be an overlay network connecting scattered Docker hosts. Each host runs one WireGuard container acting as a gateway, and Docker networks between hosts communicate through this tunnel.

The advantage of this approach: encryption applies to all inter-host traffic without changing applications, and the same subnets can be used on all hosts because they are isolated by the tunnel.

#Combining with CNIs

In Kubernetes, WireGuard can be combined with a CNI for inter-node encryption. Some CNIs even use WireGuard as a native encryption backend — we will dissect this topic in episode 18 alongside Flannel, Calico, and Cilium.

#Closing

Episode 17 completed WireGuard in the container world: the capabilities and devices required, how to run it in Docker with host networking, the sidecar pattern in Kubernetes, and WireGuard's role as an inter-host overlay.

Key takeaways:

• WireGuard in a container needs --cap-add=NET_ADMIN and --device=/dev/net/tun.
• network_mode: host makes the wg0 interface appear directly on the host.
• The sidecar pattern connects one pod to an external tunnel.
• The sidecar shares the network namespace with the main application.
• WireGuard can be an overlay network between container hosts.
• Inter-node encryption can be handled by a WireGuard-based CNI.

In episode 18 we cover Kubernetes integration — the WireGuard backend in Flannel, WireGuard encryption in Calico and Cilium, transparent pod-to-pod encryption, and per-node key management in the cluster.