Kubernetes kube-proxy Runtime Handling

Kubernetes kube-proxy Runtime Handling is the ongoing, node-local process by which kube-proxy observes changes to Service and endpoint state in the cluster and continuously translates that state into the actual packet-forwarding rules that implement Kubernetes Service networking on a given node. It is the runtime behavior of kube-proxy specifically — how it watches, reconciles, and programs its dataplane — as distinct from Service networking concepts in the abstract, and it explains why Service traffic behaves the way it does at any given moment on any given node.

kube-proxy as a Per-Node Controller

Deployment Model

kube-proxy runs as a Pod on every node in the cluster, typically managed by a DaemonSet, and each instance operates independently, responsible only for programming the dataplane rules on the node it runs on; there is no cross-node coordination required at runtime because every node's kube-proxy independently converges on the same desired state derived from the same cluster-wide Service and EndpointSlice objects.

Watch-Based Input

kube-proxy establishes watches against the API server for Service and EndpointSlice resources (and, in namespaced-scope configurations, restricts these watches accordingly), receiving incremental updates whenever a Service is created, modified, or deleted, or whenever the set of healthy Pod endpoints backing a Service changes.

The Reconciliation Cycle

Building an Internal Service Map

As updates arrive, kube-proxy maintains an in-memory representation mapping each Service's ClusterIP, ports, and session affinity configuration to its current list of ready endpoints, and it is this internal state, not the raw API objects themselves, that directly drives dataplane rule generation.

Debounced Rule Programming

Rather than reprogramming the dataplane on every single incoming update, kube-proxy batches changes over a short interval before triggering a sync, which reduces the overhead of dataplane updates during periods of rapid endpoint churn, such as a large rolling deployment, at the cost of a small, bounded delay before new endpoints become reachable.

Dataplane Modes

iptables Mode

In iptables mode, kube-proxy generates chains of iptables rules that match packets destined for a Service's ClusterIP or NodePort and probabilistically distribute them across the Service's endpoint Pods using iptables' statistic module, rewriting the destination address via DNAT; this mode's rule set grows roughly linearly with the number of Services and endpoints, which can become a performance factor in very large clusters.

IPVS Mode

In IPVS mode, kube-proxy instead programs the kernel's IP Virtual Server subsystem, creating a virtual server for each Service IP and real servers for each endpoint, which supports more scheduling algorithms than iptables' simple randomization and scales more predictably with large numbers of Services, since IPVS lookups do not require traversing a linear rule chain.

eBPF-Based Replacement Dataplanes

Some CNI implementations provide an eBPF-based dataplane that replaces kube-proxy's rule programming entirely, implementing equivalent Service load-balancing logic directly in eBPF programs attached to network hooks; when such a replacement is in use, kube-proxy itself is typically disabled on the node, though the conceptual responsibility it would otherwise carry out is preserved by the replacement component.

Handling Specific Traffic Scenarios

Session Affinity

When a Service specifies ClientIP session affinity, kube-proxy's rules are generated to consistently route repeated connections from the same client IP to the same backend Pod for a configured timeout window, implemented differently depending on dataplane mode but conceptually layered on top of the same endpoint selection logic.

externalTrafficPolicy Effects on Rule Generation

The externalTrafficPolicy field on a Service directly changes how kube-proxy generates rules for NodePort and LoadBalancer traffic: with Cluster policy, kube-proxy programs rules that may forward traffic to any endpoint cluster-wide, potentially requiring a second hop and obscuring the original client IP through SNAT, while Local policy restricts forwarding to only endpoints on the receiving node, preserving client IP but requiring that node to actually have a healthy endpoint or the request is dropped.

Health Checking for Local Traffic Policy

When Local traffic policy is in effect, kube-proxy also runs a lightweight HTTP health check endpoint that external load balancers can query to determine whether a given node currently has any healthy local endpoints for a Service, allowing the load balancer to stop sending traffic to nodes that would otherwise drop it.

Failure and Consistency Considerations

Eventually Consistent Convergence

Because kube-proxy's rule programming is driven by watch events and batched syncs, there is always a brief window between an endpoint becoming unhealthy and every node's dataplane rules reflecting that change, meaning Service traffic handling is eventually consistent rather than instantaneous across the cluster.

Rule Programming Failures

If kube-proxy fails to apply its generated rules — due to a kernel module being unavailable, insufficient privileges, or a conflicting external rule manager on the node — Service traffic to or through that node can silently fail or behave inconsistently, which is why kube-proxy exposes metrics and logs specifically around sync duration and rule application errors for operators to monitor.