4.12 Kubernetes kube-proxy Runtime Handling

Kubernetes kube-proxy Runtime Handling is the internal lifecycle and execution behavior of the kube-proxy process itself as it runs on a node, covering how it starts, watches control plane state, selects a backend proxy mode, reconciles kernel networking rules, and exposes health and metrics endpoints for observability. It concerns the operational mechanics of kube-proxy as a long-running node process, distinct from the networking rules it ultimately produces.

Deployment and Process Model

Running as a DaemonSet

kube-proxy is typically deployed as a DaemonSet, ensuring exactly one instance runs on every node in the cluster, though it can also be run as a standalone systemd-managed process in some cluster distributions. As a DaemonSet pod, it inherits standard kubelet-managed lifecycle behavior, including restart policies and resource limits.

Privileged Access Requirements

Because kube-proxy manipulates kernel-level networking state such as iptables rules or IPVS virtual servers, it requires elevated privileges, typically running with host networking enabled and specific Linux capabilities such as NET_ADMIN, allowing it to modify the node's networking stack directly.

Configuration Loading

On startup, kube-proxy reads a configuration file, commonly supplied through a ConfigMap mounted into its pod, specifying its proxy mode, cluster CIDR, bind address, and various tuning parameters such as sync period and conntrack settings.

Watching Control Plane State

Informer-Based Synchronization

kube-proxy establishes watch connections to the API server for Service and EndpointSlice objects, using client-go informers that maintain a local, continuously updated cache of relevant objects, avoiding the need to poll the API server repeatedly.

Event-Driven Reconciliation Triggers

Changes to Services or EndpointSlices trigger kube-proxy's internal proxier to recompute the desired networking rule state. Rather than reacting to every single event individually, kube-proxy batches changes within a short window and applies them together, reducing the frequency of expensive rule-programming operations.

Periodic Full Resync

In addition to event-driven updates, kube-proxy performs a periodic full resynchronization of its rules against the actual state of the underlying networking subsystem, configured by a sync period parameter, correcting for any drift caused by external modifications or missed events.

Proxy Mode Selection and Backends

iptables Proxier

In iptables mode, kube-proxy's proxier component translates Service and endpoint state into a set of iptables chains and rules, using techniques such as random probability matching within a chain to achieve load balancing across multiple backend pods without needing a separate load balancing process.

IPVS Proxier

In IPVS mode, kube-proxy's proxier programs virtual servers and real servers directly into the Linux kernel's IPVS subsystem, using ipvsadm-equivalent netlink calls, and additionally sets up a limited number of iptables rules for functionality IPVS does not natively cover, such as masquerading.

nftables Proxier

Newer kube-proxy versions support an nftables-based proxier, which expresses the same Service routing logic using the nftables framework, offering more efficient rule set updates than legacy iptables due to nftables' atomic rule set replacement model.

Mode Selection Logic

The active proxy mode is determined by configuration, falling back to a default mode if the requested mode's kernel dependencies are unavailable on the node, with kube-proxy performing capability checks at startup, such as verifying IPVS kernel modules are loaded before committing to IPVS mode.

Health and Observability Endpoints

Healthz Endpoint

kube-proxy exposes an HTTP health check endpoint that the kubelet or external health monitoring can query to determine whether the proxy process is alive and has completed at least one successful sync cycle, which is used for liveness probing of the kube-proxy pod itself.

Metrics Endpoint

A separate metrics endpoint exposes Prometheus-formatted metrics describing sync latencies, rule counts, and per-mode specific statistics, giving operators visibility into how efficiently kube-proxy is applying rule changes on a given node.

Service Health Server for externalTrafficPolicy

For Services configured with externalTrafficPolicy: Local, kube-proxy runs an additional per-Service health check server, allowing external load balancers to query whether a given node currently hosts any healthy backend pods for that Service, informing external traffic distribution decisions.

Connection Tracking Management

conntrack Table Interaction

kube-proxy interacts with the kernel's connection tracking table both to support NAT-based Service routing and to actively clean up stale entries, particularly when a backend pod is removed, preventing clients from having connections routed to an endpoint that no longer exists.

conntrack Tuning Parameters

Configuration options control conntrack table size limits and timeout values that kube-proxy applies to the node's sysctl settings at startup, helping the node handle high volumes of concurrent Service connections without exhausting the connection tracking table.

Graceful Termination Behavior

Endpoint Draining Coordination

When a pod backing a Service enters a terminating state, kube-proxy, informed by EndpointSlice conditions reflecting terminating and serving status, can continue routing existing connections to the draining pod for Services configured to support connection draining, while excluding it from new connection routing.

Rule Cleanup on Shutdown

When kube-proxy itself is terminated, whether through node drain or an upgrade, it does not automatically remove the networking rules it has installed, since those rules must continue functioning for existing traffic; cleanup is instead handled by the next kube-proxy instance's resynchronization logic or explicit cleanup tooling.