Kubernetes Probe Handler Types

Kubernetes Probe Handler Types are the distinct check mechanisms a startup, liveness, or readiness probe can use to determine container health: exec, tcpSocket, httpGet, and grpc. Each handler type defines a different way of asking the container "are you functioning correctly," suited to different kinds of applications and protocols, and the choice of handler is independent of which probe category (startup, liveness, readiness) it is attached to.

exec Handler

Command Execution Inside the Container

The exec handler runs a specified command inside the container's own namespace and treats a zero exit code as success, any non-zero code as failure. This handler is the most flexible, since the command can perform arbitrary custom logic, but it also carries the highest per-check overhead because it forks a new process for every probe attempt.

livenessProbe:
  exec:
    command:
      - cat
      - /tmp/healthy
  periodSeconds: 10

Common Use Cases

exec is favored for applications without a network listener suitable for health checks, such as batch processors, or for checks that need to inspect internal file-based state, like a lock file or a written sentinel value.

tcpSocket Handler

Connection-Only Verification

The tcpSocket handler attempts to open a TCP connection to a specified port on the container and treats a successful connection as success, regardless of what, if anything, the application sends back. It does not verify application-level correctness, only that something is listening.

readinessProbe:
  tcpSocket:
    port: 5432
  periodSeconds: 5

Appropriate Scope

This handler suits protocols without a convenient HTTP surface, such as raw TCP services or databases, where confirming the listener is up is a meaningful, if shallow, health signal.

httpGet Handler

HTTP-Level Health Semantics

The httpGet handler issues an HTTP GET request to a configurable path, port, and optionally scheme (HTTP or HTTPS), custom httpHeaders, and host. Any response with a status code between 200 and 399 inclusive is treated as success; anything else, or a connection failure, counts as a failed attempt.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    httpHeaders:
      - name: X-Probe-Source
        value: kubelet
  periodSeconds: 10

Why It Is the Most Common Choice

Because most modern services already expose HTTP endpoints, httpGet allows a dedicated health-check route to encode arbitrary application-specific logic, database connectivity, cache state, dependency reachability, while remaining lightweight compared to exec.

grpc Handler

Native gRPC Health Checking

The grpc handler calls a gRPC service implementing the standard gRPC health checking protocol on a specified port, optionally targeting a specific service name for applications that expose health status per internal service rather than for the whole process.

readinessProbe:
  grpc:
    port: 9090
    service: "orders.OrderService"
  periodSeconds: 5

When to Prefer It

Applications already built around gRPC benefit from this handler because it avoids running a separate HTTP listener solely for health checks and integrates with the same health-reporting convention used by gRPC-aware service meshes and load balancers.

Choosing Between Handler Types

Selecting the correct handler for a container's actual protocol surface avoids both false negatives (a TCP check on a service that accepts connections but hangs) and unnecessary overhead (an exec check where a simple HTTP endpoint would suffice).