Learn Flannel - Core Concepts & Main Architecture

#Introduction

In episode 1 you learned what Flannel is and why it was born. Now we move into the most important part to understand before operating it: the internal architecture.

Episode 2 dissects how Flannel works behind the scenes. We will follow the flow from kubelet calling CNI, flanneld taking a subnet lease, to the formation of the VXLAN interface. After this episode, you will be able to read the Flannel configuration in your own cluster and know what each part is responsible for.

#How It Works Behind the Scenes

#The Flow: Lease, Backend, and CNI

Flannel's workflow revolves around a single daemon named flanneld that runs on every node. When a node first joins, flanneld requests a subnet lease from the datastore. This lease gives the node exclusive rights over one block of IPs, for example 10.244.1.0/24.

After getting the lease, flanneld builds the network interface according to the chosen backend: the flannel.1 VXLAN interface for the vxlan backend, or direct routes for the host-gw backend. Finally, when kubelet creates a new Pod, the flannel CNI plugin reads the results of flanneld's work and creates the Pod interface within that node's subnet.

kubelet calls CNI -> flannel takes a subnet lease -> creates interface -> bridge cni0

#Datastore: Kubernetes API vs etcd

The subnet lease must be stored somewhere all nodes can access. Flannel supports two datastores: the Kubernetes API and etcd. Kubernetes API mode is the default in modern installations via the --kube-subnet-mgr flag. Leases are stored as Lease objects in the kube-system namespace.

etcd mode is used for non-Kubernetes setups or legacy versions. Because the majority of users use the Kubernetes API, this entire series focuses on that mode, but the subnet lease concept is identical.

#Flannel's Main Components

#flanneld

flanneld is the main daemon. Its job: read the configuration, take a lease, build the backend, and keep routes synchronized. It also writes the /run/flannel/subnet.env file that the CNI plugin reads. Without flanneld, no Pod network is formed.

#Subnet Manager

The subnet manager is the module that communicates with the datastore. It is the one that requests leases, renews them, and listens for changes from other nodes. In kube mode, the subnet manager communicates with the API server using the ServiceAccount provided by Flannel.

#Backend

The backend is the module that determines how packets are forwarded between nodes. The main options: vxlan for UDP encapsulation, host-gw for direct routing, and wireguard and ipsec for encryption. Every node uses the same backend, defined once in net-conf.json.

#The flannel CNI Plugin

The flannel CNI plugin is the bridge between kubelet and flanneld. It reads /run/flannel/subnet.env and the configuration file /etc/cni/net.d/10-flannel.conflist, then delegates bridge and veth creation to the bridge plugin from containernetworking/plugins.

#Net-conf: The Source of Configuration

#net-conf.json

All of Flannel's major decisions live in a single file: net-conf.json. This file is stored in the kube-flannel-cfg ConfigMap and mounted to /etc/kube-flannel in every flanneld Pod.

apiVersion: v1
kind: ConfigMap
metadata:
  name: kube-flannel-cfg
  namespace: kube-flannel
data:
  net-conf.json: |
    {
      "Network": "10.244.0.0/16",
      "Backend": {
        "Type": "vxlan"
      }
    }

The Network field is the large pool from which every node takes a subnet, and Backend determines the packet forwarding mechanism. In episodes 4 and 5 we will discuss the backend options in detail.

kubectl get cm -n kube-flannel kube-flannel-cfg -o yaml
cat /run/flannel/subnet.env

The kubectl get cm -n kube-flannel kube-flannel-cfg command shows the same configuration, while cat /run/flannel/subnet.env shows the runtime result: FLANNEL_NETWORK, FLANNEL_SUBNET, and FLANNEL_MTU already computed by flanneld.

#Exploring the Runtime

#Verifying the Workflow on a Node

To see proof that this architecture works, you can inspect flanneld's concrete results on a node. The flannel.1 interface indicates the vxlan backend is formed, routes with the 10.244.x.0/24 prefix indicate leases from other nodes have been synchronized, and the subnet.env file indicates the CNI plugin has what it needs to create new Pods.

ip -d link show flannel.1
ip route | grep flannel

If ip route | grep flannel shows several 10.244.x.0/24 routes, that means all nodes already know each other's subnets. This simple architecture is the key to why Flannel is easy to debug and maintain.

#Why This Architecture Matters

Understanding the architecture isn't just theory. During troubleshooting in episode 19, you will dissect the layers one by one: whether the lease exists, whether the backend is formed, whether the CNI plugin works. All of that can only be done if you understand the architecture map we drew in this episode.

#Why This Is the Foundation of All Episodes

Every problem you encounter in the following episodes can be traced back to one of these architecture components. Connectivity problems: check the backend. IP address problems: check the lease. Interface problems: check the CNI plugin. The whole series is built on the map you draw in this episode.

#Conclusion

Episode 2 gave you the complete map of Flannel's architecture: the flow from kubelet to the CNI plugin, the roles of flanneld and the subnet manager, the backend options, and net-conf.json as the single source of configuration.

Key takeaways:

• flanneld runs on every node and is responsible for taking a subnet lease.
• Leases are stored in the datastore, i.e. the Kubernetes API in modern mode.
• The backend determines how packets are forwarded: vxlan, host-gw, wireguard, or ipsec.
• The flannel CNI plugin connects kubelet with flanneld via subnet.env.
• net-conf.json stores Network and Backend, mounted from the kube-flannel-cfg ConfigMap.
• The proof of the architecture is visible in the flannel.1 interface and the 10.244.x.0/24 routes.

In the next episode, episode 3, we will practice directly: setup and installation — installing Flannel through the official kube-flannel.yml manifest and the flannel/flannel Helm chart, then verifying the DaemonSet, the interface, and connectivity between nodes. This is the first moment you operate Flannel on a real cluster.