Skip to content

Flannel

Summary

Flannel is a small layer 3 network fabric (CNI) for Kubernetes. A single flanneld agent per node takes a pod subnet from the Kubernetes API (or etcd) and carries traffic between nodes over VXLAN (default), host-gw routes or WireGuard. It is the embedded default CNI in K3s and the networking half of Canal. flanneld does not enforce NetworkPolicy itself. You add policy with the chart's kube-network-policies option, K3s's embedded kube-router controller, Canal or Cilium chaining. Latest release: v0.28.9 (2026-08-07). The project is actively maintained by SUSE engineers under Apache-2.0.

Overview

Flannel does one thing: it gives each node a subnet out of a cluster CIDR and moves packets between those subnets. It does not handle services (kube-proxy does), observability, BGP or L7. That narrow scope is why it is the usual "just works" choice for dev, edge and small clusters. It is also why production clusters that need segmentation pair it with a policy engine or pick Calico or Cilium instead. See Explanation for internals and Reference for all config keys, flags and ports.

Key Facts

Attribute Detail
Latest Version v0.28.9 (2026-08-07); 0.28 line since v0.28.0 (2026-01-06)
Release cadence Patch releases every few weeks in 2026; only the latest release gets security fixes
Repository github.com/flannel-io/flannel
Stars ~9k+ (recorded by 2026-08)
Language Go (Go 1.26 toolchain)
License Apache-2.0
Governance Independent flannel-io org; 4 maintainers, all SUSE. Not a CNCF project (follows the CNCF Code of Conduct). Originally created by CoreOS.
Install Release manifest kube-flannel.yml, Helm chart flannel/flannel, or bundled (K3s, RKE2 via Canal)
Images ghcr.io/flannel-io/flannel, ghcr.io/flannel-io/flannel-cni-plugin
Default backend / port VXLAN, UDP 8472 (VNI 1)
Platforms Linux (amd64, arm, arm64, ppc64le, s390x, riscv64), Windows workers (vxlan, host-gw)

Evaluation

Pros Cons
Simplest CNI to install and operate; one DaemonSet, one ConfigMap flanneld has no NetworkPolicy; you need an add-on controller
Default and embedded in K3s; networking layer of Canal VXLAN overlay adds 50 bytes of overhead and some latency
WireGuard backend for encryption between nodes No L7 visibility, flow logs or service map
host-gw and DirectRouting avoid encapsulation on flat L2 No BGP, no multi-cluster, no eBPF dataplane or kube-proxy replacement
Small footprint (manifest requests 100m CPU / 50Mi) One subnet per node; limited IPAM flexibility
Stable, long-lived design; dual-stack, IPv6-only and nftables (experimental) Support policy: latest release only

Good fit: K3s and edge clusters, labs and CI clusters, small production clusters on trusted networks, and Canal deployments that want Calico policy with Flannel's simple overlay.

Poor fit: multi-tenant clusters that need fine-grained policy and flow visibility, very large clusters, L7 policy, BGP integration with the physical network, or eBPF acceleration. Use Cilium or Calico instead.

Architecture

This compact view shows the per-node pieces and how they talk to the control plane. The full diagrams are in Explanation.

flowchart LR
    API["kube-apiserver<br/>(Node podCIDR + flannel annotations)"]
    subgraph N1["Node 1"]
        F1["flanneld"] --> E1["subnet.env"]
        E1 --> C1["flannel CNI -> bridge cni0"]
        F1 --> T1["flannel.1 VTEP"]
    end
    subgraph N2["Node 2"]
        F2["flanneld"] --> T2["flannel.1 VTEP"]
    end
    F1 <-->|"watch / annotate"| API
    F2 <-->|"watch / annotate"| API
    T1 <-->|"VXLAN UDP 8472"| T2

Backends at a Glance

Backend Status Encryption Overhead Notes
vxlan Recommended (default) No 50 B Works on any IP network; DirectRouting for same-subnet peers
host-gw Recommended No 0 Needs L2 adjacency; usually not usable in cloud VPCs
wireguard Recommended Yes 80 B K3s value is wireguard-native; UDP 51820/51821
udp Debugging only (not formally deprecated) No 28 B Userspace TUN proxy; linux/amd64 only; slowest
ipip, ipsec, alloc, extension, tencent-vpc Experimental ipsec only varies See Reference > Backend Matrix

Network Policy Options

Kubernetes accepts NetworkPolicy objects on a vanilla Flannel cluster but nothing enforces them. Four ways to get enforcement:

  1. Flannel Helm chart netpol.enabled=true runs the Kubernetes SIG Network kube-network-policies controller (since v0.25.5).
  2. K3s has kube-router's netpol controller embedded by default.
  3. Canal: Calico policy with Flannel networking. It is RKE2's default CNI.
  4. Cilium CNI chaining on top of Flannel.

Recipes are in How-to Guides > Enforce NetworkPolicy.

Recent Developments

When Change
2026-08 (v0.28.9) /healthz and /readyz probes added to manifest and chart; etcd watch compaction recovery; dependency CVE fixes
2026-07 (v0.28.6-v0.28.8) install-conf command for CNI config install; atomic subnet.env writes
2026-04 (v0.28.3) GOVERNANCE.md, ADOPTERS.md, ROADMAP.md formalised (vendor-neutral governance statement)
2026-03 (v0.28.2) CVE-2026-32241 (High): command injection through Node annotations with the experimental extension backend. Fixed in v0.28.2.
2024-07 (v0.25.5) NetworkPolicy via kube-network-policies in the Helm chart
2024-04 (v0.25.0) Experimental nftables mode (EnableNFTables)

Roadmap focus: stability and CVE patching, moving from iptables to nftables, dual-stack improvements, Windows, and a public benchmark suite (ROADMAP.md).

Ecosystem and Compatibility

  • K3s embeds Flannel (no DaemonSet). Default backend is vxlan and cluster CIDR is 10.42.0.0/16. Flags are --flannel-backend, --flannel-iface, --flannel-ipv6-masq and --flannel-external-ip.
  • RKE2 ships Canal by default and can run standalone Flannel, including on Windows nodes.
  • kubeadm needs --pod-network-cidr=10.244.0.0/16 (or a matching custom CIDR) and the br_netfilter module.
  • Kubernetes versions: the current manifest targets v1.17+. flanneld itself tracks upstream Kubernetes client libraries.
  • Outside Kubernetes: Flannel still runs with etcd as the datastore (for example on Docker hosts).

Alternatives and Migration

Requirement Flannel Better option
Kubernetes NetworkPolicy Via add-on controller Calico or Cilium (native)
Microsegmentation, tiers, global policy No Calico (GlobalNetworkPolicy, tiers) or Cilium (CiliumNetworkPolicy)
L7 policy (HTTP/gRPC/DNS) No Cilium
Encryption WireGuard backend Calico or Cilium WireGuard, with policy on top
Flow observability No Cilium Hubble
eBPF dataplane, kube-proxy replacement No Cilium, Calico eBPF
BGP to the physical network No Calico, Cilium
Compliance-grade segmentation (PCI, HIPAA) Not on its own Calico or Cilium with audit logging

Upgrade paths, from least to most disruptive:

  1. Keep Flannel and add a policy controller (kube-network-policies or Canal).
  2. Replace Flannel with Calico.
  3. Replace Flannel with Cilium.

Steps are in How-to Guides > Migrate from Flannel to Cilium or Calico. The side-by-side comparison is in CNI Comparison.

Topic Map

  • How-to Guides: install (manifest, Helm, kubeadm, K3s), choose a backend, encryption, dual-stack, nftables and NetworkPolicy, upgrade, migrate away, troubleshoot.
  • Reference: net-conf.json keys, backend matrix, flanneld flags, annotations, files and ports, K3s flags, Helm values, releases, hardening checklist.
  • Explanation: flanneld, subnet managers, the CNI plugin, backend internals, iptables vs nftables, dual-stack, why there is no policy engine.

Sources

Questions

Open

  • K3s nftables: does embedded Flannel in K3s expose EnableNFTables, and when? Tracked in k3s-io/k3s#12849. As of 2026-09-27 K3s master still hard-codes Flannel's iptables traffic manager (pkg/agent/flannel/flannel.go).
  • When will upstream publish its planned backend benchmark suite, so Reference > Performance Estimates can carry measured numbers?
  • When will EnableNFTables leave EXPERIMENTAL status and become the default?

Answered

  • Does Flannel support NetworkPolicy? Not in flanneld itself. Since v0.25.5 the Helm chart can deploy kube-network-policies (netpol.enabled=true). K3s ships kube-router's netpol controller, and Canal or Cilium chaining are alternatives (netpol.md).
  • When were the aws-vpc, gce and ali-vpc backends removed? In v0.20.0 (tagged 2022-10-17), via PR #1625 ("Remove obsolete cloud backends"). See Explanation.
  • Is the UDP backend deprecated? Not formally. Upstream lists it for "debugging only or for very old kernels", and it only builds for linux/amd64 (backends.md).
  • What is the migration path from Flannel to Cilium on K3s? K3s embeds Flannel, so you do not delete a DaemonSet. Start servers with --flannel-backend=none --disable-network-policy, install Cilium, remove flannel.1/cni0 on each node, restart workloads, then run cilium connectivity test. Full steps are in How-to Guides.