Understanding Flannel’s VXLAN and host‑gw Modes for Kubernetes Networking

Flannel is a simple container network solution for Kubernetes that places all Pods in a single virtual L2 subnet. It supports multiple backend forwarding methods; this article explains two of them: VXLAN and host‑gw.

VXLAN Overview

VXLAN (Virtual Extensible LAN) is a network virtualization technology that encapsulates Ethernet frames in UDP packets, allowing a virtual L2 network to be built over an L3 infrastructure. The packet format is shown below.

VXLAN uses VTEP (VXLAN Tunnel Endpoint) to encapsulate and decapsulate traffic. The VTEP can be a physical switch or a virtual device on a server. In Flannel, the VTEP role is performed by the virtual interface flannel.1.

VXLAN Mode

When Flannel is installed with default settings, each node receives a /24 subnet and two virtual interfaces are created: cni0 (a bridge similar to docker0) and flannel.1 (a VXLAN device acting as VTEP). The cni0 bridge connects all Pods on the node, while flannel.1 handles VXLAN encapsulation for inter‑node traffic.

Linux kernel support for VXLAN started in version 3.7 and became complete by 3.12.

Intra‑node Communication

Pods on the same node communicate via the cni0 bridge without VXLAN encapsulation.

Cross‑node Communication

For traffic between different nodes, the process is:

Pod A sends an ICMP packet, which is passed to flannel.1, encapsulated into a VXLAN UDP packet, and transmitted over the physical interface.

The receiving node’s flannel.1 decapsulates the packet and forwards the original L2 frame to the destination Pod via cni0.

Flannel determines which IPs should be handled by flannel.1 based on routing information stored in etcd. Routes for non‑local subnets point to flannel.1, while local subnets use cni0.

# ip r
... (routing table output) ...
10.244.0.0/24 dev cni0 proto kernel scope link src 10.244.0.1
10.244.1.0/24 via 10.244.1.0 dev flannel.1 onlink

flannel.1 Packet Encapsulation Process

Encapsulation involves wrapping the original L2 Ethernet frame inside a UDP packet. The inner frame requires source/destination IP and MAC addresses, which are derived from the routing and ARP tables. The ARP entries are pre‑populated by flanneld and marked permanent.

# ip n | grep flannel.1
10.244.1.0 dev flannel.1 lladdr ba:74:f9:db:69:c1 PERMANENT

With this information, flannel.1 constructs the outer VXLAN UDP packet, filling in the VTEP IP addresses obtained from the FDB (Forwarding Database).

The final VXLAN UDP packet is sent out through the physical interface.

host‑gw Mode

When nodes reside on the same L2 network, the host‑gw backend can be used, eliminating VXLAN encapsulation. Switching to host‑gw involves changing the ConfigMap kube-flannel-cfg to set "Backend": {"Type":"host-gw"} and restarting the flannel pods.

net-conf.json: |
  {
    "Network": "10.244.0.0/16",
    "Backend": {
      "Type": "host-gw"
    }
  }

In host‑gw mode, flanneld configures static routes so that each node’s Pod subnet points to the other node’s IP, as shown below.

Because no encapsulation is required, host‑gw offers the best performance, though it is typically unsuitable for public cloud environments and is mainly used in private deployments.

References

What is VXLAN

Deep dive into CNI

bridge man page

ip‑route man page

ip‑neighbour man page

Flannel VXLAN mode analysis