9.16 Kubernetes Probe Handler Types

Kubernetes Probe Handler Types is the set of distinct mechanisms Kubernetes supports for actually performing the check that underlies any liveness, readiness, or startup probe, determining how the kubelet interrogates a container to decide whether it is currently succeeding or failing that probe, independent of which of the three probe categories the check is being used for.

HTTP GET Handler

Request Construction

The HTTP GET handler configures the kubelet to issue an HTTP request to a specified path and port within the container, optionally including a host, scheme, and custom httpHeaders, allowing the probe to target a specific health endpoint exposed by the application over HTTP or HTTPS.

Success and Failure Interpretation

A response with any status code from 200 through 399 is interpreted as a success, while any other status code, a connection refusal, or a timeout exceeding timeoutSeconds is interpreted as a failure, making this handler well suited to applications that already expose a web server and can cheaply add a dedicated health route.

TCP Socket Handler

Connection-Based Verification

The TCP socket handler configures the kubelet to attempt opening a TCP connection to a specified port on the container, treating a successful connection establishment as success and a refused or timed-out connection attempt as failure, without sending or interpreting any application-level data.

Applicability to Non-HTTP Services

This handler is particularly useful for services that communicate over custom binary protocols or do not expose any HTTP interface at all, since it only requires that the target port is open and accepting connections, offering a coarser but broadly applicable health signal.

Exec Handler

Command Execution Inside the Container

The exec handler configures the kubelet to run a specified command directly inside the container's namespace via the container runtime, treating an exit code of zero as success and any non-zero exit code as failure, functioning as the most flexible handler type since arbitrary logic can be encoded into the command or script being executed.

Overhead Considerations

Because each exec probe invocation requires spawning a new process inside the container, exec handlers carry more overhead than HTTP or TCP handlers, particularly at high probe frequencies or on nodes running many Pods simultaneously, a factor worth weighing against the flexibility this handler provides.

gRPC Handler

Native Health Checking Protocol Support

The gRPC handler configures the kubelet to invoke the standard gRPC Health Checking Protocol against a specified port, optionally targeting a specific service name registered within the application's gRPC health service implementation, interpreting a SERVING status response as success.

Avoiding Sidecar or Wrapper Overhead

This handler allows gRPC-based applications to expose health information through the same protocol they already use for their primary interface, avoiding the need to additionally stand up an HTTP endpoint or shell out to an exec script purely for health checking purposes.

Shared Behavior Across Handler Types

Uniform Timing and Threshold Application

Regardless of which handler type is selected, the same initialDelaySeconds, periodSeconds, timeoutSeconds, successThreshold, and failureThreshold fields govern the cadence and tolerance of the probe, meaning the choice of handler affects only how the individual check is performed, not how its results are aggregated over time.

Handler Choice Independent of Probe Category

Any of the four handler types can be used for a liveness probe, a readiness probe, or a startup probe interchangeably, since the handler determines only the mechanics of a single check, while the probe category determines what consequence follows from that check's aggregated success or failure over consecutive attempts.