# flannel-io/flannel architecture

> Architecture diagram of the GitHub repository flannel-io/flannel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flannel-io/flannel
- Repository: https://github.com/flannel-io/flannel

## Overview

Flannel is a per-host Kubernetes network agent: it obtains a node subnet lease and network configuration from Kubernetes or etcd, then configures a selected backend to transport traffic between hosts. The principal runtime path also installs host traffic rules and reports readiness. Backend implementations include overlay tunnels, routing, and cloud-specific options; the README documents these capabilities, while the excerpts show only selected implementation details, so some backend relationships are documented rather than traced through sampled callers.

Main entry points: [`main.go`](https://github.com/flannel-io/flannel/blob/master/main.go) (flanneld agent), [`pkg/backend/common.go`](https://github.com/flannel-io/flannel/blob/master/pkg/backend/common.go) (Backend API), [`pkg/subnet/etcd/local_manager.go`](https://github.com/flannel-io/flannel/blob/master/pkg/subnet/etcd/local_manager.go) (etcd lease manager), [`pkg/trafficmngr/trafficmngr.go`](https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/trafficmngr.go) (Traffic manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_flanneld["flanneld agent<br/>[main.go]"]
  node_backendmgr["Backend manager<br/>[manager.go]"]
  node_interface_pick["Interface selection<br/>[match.go]"]
end

subgraph group_leases["Subnet management"]
  node_lease_model["Lease model<br/>[lease.go]"]
  node_subnet_api["Subnet manager API<br/>[subnet.go]"]
  node_kube_store[("Kubernetes store<br/>[kube.go]")]
  node_etcd_store[("etcd registry<br/>[registry.go]")]
  node_etcd_lease["etcd lease manager<br/>[local_manager.go]"]
end

subgraph group_transport["Network backends"]
  node_backend_api["Backend API<br/>[common.go]"]
  node_vxlan["VXLAN transport<br/>[vxlan_network.go]"]
  node_wireguard["WireGuard transport"]
  node_hostgw["Host-gateway routes<br/>[hostgw_windows.go]"]
  node_ipip["IP-in-IP transport<br/>[ipip.go]"]
  node_ipsec["IPsec transport<br/>[ipsec.go]"]
  node_cloud_backend["Cloud backends<br/>[tencentvpc.go]"]
end

subgraph group_hostnet["Host networking"]
  node_traffic_api["Traffic manager<br/>[trafficmngr.go]"]
  node_iptables["iptables rules<br/>[iptables.go]"]
  node_nftables["nftables rules<br/>[nftables.go]"]
end

node_operator(("Cluster operator"))

node_operator -->|"starts"| node_flanneld
node_flanneld -->|"selects interface"| node_interface_pick
node_flanneld -->|"creates manager"| node_kube_store
node_flanneld -->|"creates manager"| node_etcd_lease
node_etcd_lease -->|"uses registry"| node_etcd_store
node_etcd_lease -->|"allocates leases"| node_lease_model
node_kube_store -->|"provides leases"| node_lease_model
node_backendmgr -->|"receives manager"| node_subnet_api
node_backendmgr -->|"constructs backend"| node_backend_api
node_flanneld -->|"registers network"| node_backend_api
node_backend_api -.->|"selects transport"| node_vxlan
node_backend_api -.->|"selects transport"| node_wireguard
node_backend_api -.->|"selects transport"| node_hostgw
node_backend_api -.->|"selects transport"| node_ipip
node_backend_api -.->|"selects transport"| node_ipsec
node_backend_api -.->|"selects integration"| node_cloud_backend
node_flanneld -->|"configures forwarding"| node_traffic_api
node_flanneld -->|"chooses rules"| node_iptables
node_flanneld -->|"chooses rules"| node_nftables
node_traffic_api -->|"implements rules"| node_iptables
node_traffic_api -.->|"implements rules"| node_nftables

click node_flanneld "https://github.com/flannel-io/flannel/blob/master/main.go"
click node_backendmgr "https://github.com/flannel-io/flannel/blob/master/pkg/backend/manager.go"
click node_lease_model "https://github.com/flannel-io/flannel/blob/master/pkg/lease/lease.go"
click node_subnet_api "https://github.com/flannel-io/flannel/blob/master/pkg/subnet/subnet.go"
click node_kube_store "https://github.com/flannel-io/flannel/blob/master/pkg/subnet/kube/kube.go"
click node_etcd_store "https://github.com/flannel-io/flannel/blob/master/pkg/subnet/etcd/registry.go"
click node_etcd_lease "https://github.com/flannel-io/flannel/blob/master/pkg/subnet/etcd/local_manager.go"
click node_interface_pick "https://github.com/flannel-io/flannel/blob/master/pkg/ipmatch/match.go"
click node_backend_api "https://github.com/flannel-io/flannel/blob/master/pkg/backend/common.go"
click node_vxlan "https://github.com/flannel-io/flannel/blob/master/pkg/backend/vxlan/vxlan_network.go"
click node_wireguard "https://github.com/flannel-io/flannel/blob/master/pkg/backend/wireguard/wireguard_network.go"
click node_hostgw "https://github.com/flannel-io/flannel/blob/master/pkg/backend/hostgw/hostgw_windows.go"
click node_ipip "https://github.com/flannel-io/flannel/blob/master/pkg/backend/ipip/ipip.go"
click node_ipsec "https://github.com/flannel-io/flannel/blob/master/pkg/backend/ipsec/ipsec.go"
click node_cloud_backend "https://github.com/flannel-io/flannel/blob/master/pkg/backend/tencentvpc/tencentvpc.go"
click node_traffic_api "https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/trafficmngr.go"
click node_iptables "https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/iptables/iptables.go"
click node_nftables "https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/nftables/nftables.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flanneld,node_backendmgr,node_interface_pick toneBlue
class node_lease_model,node_subnet_api,node_kube_store,node_etcd_store,node_etcd_lease toneAmber
class node_backend_api,node_vxlan,node_wireguard,node_hostgw,node_ipip,node_ipsec,node_cloud_backend toneMint
class node_traffic_api,node_iptables,node_nftables toneRose
class node_operator toneIndigo
```

## Components

### Agent runtime

- [flanneld agent](https://github.com/flannel-io/flannel/blob/master/main.go): `main.go`
- [Backend manager](https://github.com/flannel-io/flannel/blob/master/pkg/backend/manager.go): `pkg/backend/manager.go`
- [Interface selection](https://github.com/flannel-io/flannel/blob/master/pkg/ipmatch/match.go): `pkg/ipmatch/match.go`

### Subnet management

- [Lease model](https://github.com/flannel-io/flannel/blob/master/pkg/lease/lease.go): `pkg/lease/lease.go`
- [Subnet manager API](https://github.com/flannel-io/flannel/blob/master/pkg/subnet/subnet.go): `pkg/subnet/subnet.go`
- [Kubernetes store](https://github.com/flannel-io/flannel/blob/master/pkg/subnet/kube/kube.go): `pkg/subnet/kube/kube.go`
- [etcd registry](https://github.com/flannel-io/flannel/blob/master/pkg/subnet/etcd/registry.go): `pkg/subnet/etcd/registry.go`
- [etcd lease manager](https://github.com/flannel-io/flannel/blob/master/pkg/subnet/etcd/local_manager.go): `pkg/subnet/etcd/local_manager.go`

### Network backends

- [Backend API](https://github.com/flannel-io/flannel/blob/master/pkg/backend/common.go): `pkg/backend/common.go`
- [VXLAN transport](https://github.com/flannel-io/flannel/blob/master/pkg/backend/vxlan/vxlan_network.go): `pkg/backend/vxlan/vxlan_network.go`
- [WireGuard transport](https://github.com/flannel-io/flannel/blob/master/pkg/backend/wireguard/wireguard_network.go): `pkg/backend/wireguard/wireguard_network.go`
- [Host-gateway routes](https://github.com/flannel-io/flannel/blob/master/pkg/backend/hostgw/hostgw_windows.go): `pkg/backend/hostgw/hostgw_windows.go`
- [IP-in-IP transport](https://github.com/flannel-io/flannel/blob/master/pkg/backend/ipip/ipip.go): `pkg/backend/ipip/ipip.go`
- [IPsec transport](https://github.com/flannel-io/flannel/blob/master/pkg/backend/ipsec/ipsec.go): `pkg/backend/ipsec/ipsec.go`
- [Cloud backends](https://github.com/flannel-io/flannel/blob/master/pkg/backend/tencentvpc/tencentvpc.go): `pkg/backend/tencentvpc/tencentvpc.go`

### Host networking

- [Traffic manager](https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/trafficmngr.go): `pkg/trafficmngr/trafficmngr.go`
- [iptables rules](https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/iptables/iptables.go): `pkg/trafficmngr/iptables/iptables.go`
- [nftables rules](https://github.com/flannel-io/flannel/blob/master/pkg/trafficmngr/nftables/nftables.go): `pkg/trafficmngr/nftables/nftables.go`

### Other components

- **Cluster operator**

## Connections

- Cluster operator → flanneld agent: starts (evidence: `README.md`)
- flanneld agent → Interface selection: selects interface (evidence: `main.go`)
- flanneld agent → Kubernetes store: creates manager (evidence: `main.go`)
- flanneld agent → etcd lease manager: creates manager (evidence: `main.go`)
- etcd lease manager → etcd registry: uses registry (evidence: `pkg/subnet/etcd/local_manager.go`)
- etcd lease manager → Lease model: allocates leases (evidence: `pkg/subnet/etcd/local_manager.go`)
- Kubernetes store → Lease model: provides leases (evidence: `pkg/subnet/kube/kube.go`)
- Backend manager → Subnet manager API: receives manager (evidence: `pkg/backend/manager.go`)
- Backend manager → Backend API: constructs backend (evidence: `pkg/backend/manager.go`)
- flanneld agent → Backend API: registers network (evidence: `main.go`)
- Backend API → VXLAN transport: selects transport (evidence: `README.md`)
- Backend API → WireGuard transport: selects transport (evidence: `README.md`)
- Backend API → Host-gateway routes: selects transport (evidence: `README.md`)
- Backend API → IP-in-IP transport: selects transport (evidence: `README.md`)
- Backend API → IPsec transport: selects transport (evidence: `README.md`)
- Backend API → Cloud backends: selects integration (evidence: `README.md`)
- flanneld agent → Traffic manager: configures forwarding (evidence: `main.go`)
- flanneld agent → iptables rules: chooses rules (evidence: `main.go`)
- flanneld agent → nftables rules: chooses rules (evidence: `main.go`)
- Traffic manager → iptables rules: implements rules (evidence: `pkg/trafficmngr/iptables/iptables.go`)
- Traffic manager → nftables rules: implements rules (evidence: `pkg/trafficmngr/trafficmngr.go`)
