Kubernetes kube-proxy Service Handling

Kubernetes kube-proxy Service Handling refers to the specific responsibilities and internal operation of the kube-proxy component itself, the node-level agent that translates Service and EndpointSlice objects into actual packet-forwarding rules, making it the component that turns a declarative Service definition into functioning network behavior on every node.

Core Responsibility

Watching Services and EndpointSlices

kube-proxy runs as a process (commonly as a DaemonSet pod) on every node and continuously watches the Kubernetes API for Service and EndpointSlice changes, maintaining a local, per-node view of every Service's virtual IP and current set of ready backend endpoints.

kubectl get pods -n kube-system -l k8s-app=kube-proxy -o wide

Programming Local Packet Forwarding

Upon detecting a change, kube-proxy reprograms the node's packet forwarding rules so that traffic destined for a Service's ClusterIP (or NodePort) is redirected to one of the currently ready backend pod addresses, entirely at the networking layer, without any per-connection involvement from kube-proxy itself once the rules are installed.

Proxy Modes

iptables Mode

In iptables mode, kube-proxy installs a set of NAT chains per Service, using iptables' native probabilistic matching to distribute connections randomly but roughly evenly across backend pods; this mode is simple and widely supported but scales linearly with the number of Services and endpoints, since packet matching against a long chain becomes more expensive as the chain grows.

iptables -t nat -L KUBE-SERVICES -n | head -20

IPVS Mode

In IPVS mode, kube-proxy instead uses the Linux kernel's IP Virtual Server subsystem, which maintains proper hash-table-based lookup structures and supports multiple load-balancing algorithms (round-robin, least connection, source hashing), offering better performance characteristics at high Service and endpoint counts compared to the linear rule evaluation in iptables mode.

ipvsadm -L -n | head -20

Selecting a Mode

The proxy mode is a cluster-wide kube-proxy configuration setting, not a per-Service choice, meaning the decision between iptables and IPVS is made once at the infrastructure level based on expected cluster scale, with IPVS generally preferred for clusters expecting a large number of Services.

apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"

Reaction to Endpoint Changes

Reprogramming Latency

Because kube-proxy on every node must independently observe and react to EndpointSlice changes, there is a brief propagation delay between a pod becoming ready or unready and every node's local rules being updated to reflect that change, which is why graceful shutdown patterns (such as a short preStop delay) exist to bridge this window rather than assuming instantaneous propagation.

Full Resync vs. Incremental Updates

kube-proxy applies incremental updates to its local rules as individual endpoints change, but also periodically performs a full resync against the complete current state, correcting for any missed events or drift that might have occurred, trading a small amount of periodic overhead for consistency guarantees.

Handling of externalTrafficPolicy

Cluster-Wide Forwarding

Under the default Cluster policy, kube-proxy on any node forwards NodePort or LoadBalancer traffic to any ready backend anywhere in the cluster, which requires an additional SNAT step to ensure return traffic routes correctly, and this rewriting is what causes the original client source IP to be lost by the time it reaches the backend pod.

Local-Only Forwarding

Under the Local policy, kube-proxy only installs forwarding rules pointing at backends running on the same node, dropping the connection if none exist locally rather than forwarding it elsewhere, which avoids the SNAT step and preserves the original client source IP, at the cost of requiring external traffic to already be routed to a node with a local backend.

spec:
  externalTrafficPolicy: Local

Session Affinity Handling

ClientIP-Based Rule Ordering

When sessionAffinity: ClientIP is configured, kube-proxy installs an additional rule layer ahead of its normal load-balancing rules that matches on source IP and pins matching connections to a previously selected backend for the configured timeout window, implemented differently depending on whether iptables or IPVS mode is active, but achieving the same observable pinning behavior in both.

Operational Visibility

Diagnosing kube-proxy Issues

Because kube-proxy operates below the level visible to kubectl get service or kubectl get endpoints, diagnosing a routing failure that persists despite correct Service and EndpointSlice state typically requires inspecting kube-proxy's own logs and the actual installed rules on the affected node, rather than assuming the issue lies in the higher-level object definitions.

kubectl logs -n kube-system -l k8s-app=kube-proxy --tail=100