kube-proxy

The kube-proxy is the per-node component that programs the data-plane rules implementing Kubernetes Services. It does not handle traffic in user space (after a brief userspace mode in 2014); instead it watches Service and EndpointSlice objects and translates them into kernel-level forwarding rules — iptables, nftables, IPVS, or Windows kernel mode.

Directory layout

cmd/kube-proxy/
├── proxy.go                              # main(), 5 lines
└── app/
    ├── server.go                         # NewProxyCommand, run loop
    ├── options/                          # KubeProxyConfiguration flags
    └── ...

pkg/proxy/
├── apis/                                 # KubeProxyConfiguration types
├── config/                               # Service + EndpointSlice config event sources
├── conntrack/                            # Conntrack flush helpers (post-Service-update)
├── endpoint.go                           # Endpoint abstraction shared by all backends
├── endpointschangetracker.go             # Diffing between EndpointSlice updates
├── endpointslicecache.go                 # EndpointSlice → Endpoints conversion
├── healthcheck/                          # Service-level healthchecks for ExternalTrafficPolicy=Local
├── iptables/                             # iptables backend
├── ipvs/                                 # IPVS backend
├── nftables/                             # nftables backend (modern successor to iptables)
├── kubemark/                             # Fake proxy for scale tests
├── metaproxier/                          # Meta-backend that picks a backend per service
├── metrics/
├── node.go                               # Node Topology + Topology hints
├── runner/                               # Async runner for batched syncs
├── servicechangetracker.go               # Diffing between Service updates
├── serviceport.go                        # ServicePort abstraction
├── topology.go                           # Topology-aware routing helper
├── types.go
├── util/                                 # Shared helpers (ipset, network, async runner, …)
└── winkernel/                            # Windows VFP/HCS implementation

Boot

cmd/kube-proxy/app/server.go:

1. Parses flags into KubeProxyConfiguration.
2. Detects host iptables / nftables / IPVS support and selects a backend (--proxy-mode=iptables|ipvs|nftables|kernelspace). Default on Linux is iptables; nftables is replacing it.
3. Configures the chosen backend (e.g. for nftables, opens an nft netlink connection).
4. Creates informers for Service, EndpointSlice, and Node (topology hints).
5. Starts the proxier's main loop.

How a Service VIP is implemented

graph LR
    APIs[kube-apiserver] -->|Service<br/>EndpointSlice<br/>watch| Proxy[kube-proxy]
    Proxy -->|service map<br/>endpoint map| Sync[BackendSync]
    Sync -->|iptables-restore| iptables[iptables ruleset]
    Sync -->|nft -f| nftables[nft ruleset]
    Sync -->|ipvsadm + ipset| ipvs[IPVS table]
    Sync -->|VFP / HCS| winkernel[Windows kernel]
    Pod[Pod] -->|connect to ClusterIP| Kernel[Node kernel netfilter]
    Kernel --> iptables
    Kernel --> nftables
    Kernel --> ipvs

Each backend is an implementation of pkg/proxy.Provider with a Sync() method. The same shared change-trackers (servicechangetracker.go, endpointschangetracker.go) compute the diff; the backend is responsible for translating the diff into rules.

iptables backend

pkg/proxy/iptables/proxier.go. Generates a single iptables-restore script with KUBE-SERVICES, KUBE-EXTERNAL-SERVICES, KUBE-NODEPORTS, KUBE-MARK-MASQ, and per-service / per-endpoint chains. Atomic application via iptables-restore --noflush.

nftables backend

pkg/proxy/nftables/proxier.go. Builds an nftables ruleset using sigs.k8s.io/knftables. nftables has been the long-term successor to iptables in the Linux kernel; the in-tree backend reached GA recently and is the recommended default for new clusters.

IPVS backend

pkg/proxy/ipvs/proxier.go. Programs IPVS virtual services (one per Service) and real servers (one per Endpoint), using ipsets to handle Source IP filtering and NodePort ranges. Better scaling than iptables for very large endpoint counts.

winkernel backend

pkg/proxy/winkernel/proxier.go. Talks to the Windows Host Compute Service / Virtual Filtering Platform to program L3/L4 rules.

EndpointSlice mirroring

The legacy Endpoints resource is no longer the source of truth in modern clusters; kube-proxy watches EndpointSlice only. pkg/proxy/endpointslicecache.go reassembles slice fragments into the per-service endpoint set. Topology-aware routing (pkg/proxy/topology.go) consults EndpointSlice.Endpoints[].Hints.ForZones and the proxier's own zone/region annotations to prefer same-zone endpoints.

Conntrack hygiene

When endpoints change for an existing connection's destination, conntrack entries can pin traffic to a now-defunct endpoint. pkg/proxy/conntrack/ flushes UDP conntrack entries for changed services so traffic re-DNATs to a live endpoint.

Health checks

pkg/proxy/healthcheck/ implements the per-Service healthcheck endpoint that load balancers consult for externalTrafficPolicy: Local. The kube-proxy listens on a per-Service port that returns 200 if at least one local endpoint exists for the Service.

Key source files

File	Purpose
cmd/kube-proxy/app/server.go	Cobra command, backend selection
pkg/proxy/iptables/proxier.go	iptables backend
pkg/proxy/nftables/proxier.go	nftables backend
pkg/proxy/ipvs/proxier.go	IPVS backend
pkg/proxy/winkernel/proxier.go	Windows backend
pkg/proxy/servicechangetracker.go	Service diff
pkg/proxy/endpointschangetracker.go	EndpointSlice diff
pkg/proxy/topology.go	Topology-aware routing
pkg/proxy/healthcheck/proxier_health.go	Per-Service healthcheck

Integration points

• kube-apiserver — for Service and EndpointSlice watches.
• Linux kernel — iptables / nftables / IPVS.
• Windows kernel — VFP / HCS.
• CNI plugin — kube-proxy doesn't talk to CNI; the network plugin owns pod connectivity, kube-proxy owns Service VIPs.
• External load balancers — for Service type LoadBalancer, the cloud-controller-manager creates the LB; kube-proxy programs the node-local DNAT.

Entry points for modification

• New backend: implement pkg/proxy.Provider, register it in cmd/kube-proxy/app/server.go's backend selector.
• New Service feature (e.g. a new internalTrafficPolicy mode): wire it through pkg/proxy/servicechangetracker.go and update each backend's translator.
• New healthcheck shape: pkg/proxy/healthcheck/.