grpc-health-probe-rs

rust implementation of the grpc-health-probe. It allows you to query health of gRPC services that expose their status through the gRPC Health Checking Protocol.

This command-line utility makes a RPC to /grpc.health.v1.Health/Check. If it responds with a SERVING status, the grpc_health_probe will exit with success, otherwise it will exit with a non-zero exit code (documented below).

This port does not provide a way to skip TLS verification and there are limited options for configuring TLS.

Installation

From binary

You can directly download the grpc_health_probe executable.

Install from crates.io

cargo install grpc_health_probe

Build Manually

Clone the repo and run:

cargo install --path .

Alternatively, run:

cargo build --release

then put the resulting target/release/grpc_health_probe executable on your PATH.

Examples

$ grpc_health_probe --addr=https://localhost:5000
status: Serving

$ grpc_health_probe --addr=https://localhost:9999 --connect-timeout=250 --rpc-timeout=100
error: health rpc failed: Timeout expired

Example: gRPC health checking on Kubernetes

You can bundle the grpc_health_probe binary in your container image and define liveness and/or readiness checks for your gRPC server pods using exec probes.

spec:
  containers:
  - name: server
    image: "[YOUR-DOCKER-IMAGE]"
    ports:
    - containerPort: 5000
    readinessProbe:
      exec:
        command: [
          "/bin/grpc_health_probe",
          "--addr=https://0.0.0.0:5000",
          "--service=queries.v1.QueriesAPI",
          "--tls",
          "--tls-server-name=deployment.namespace.svc.cluster.local"
        ]
      initialDelaySeconds: 5
    livenessProbe:
      exec:
        command: [
          "/bin/grpc_health_probe",
          "--addr=https://0.0.0.0:5000",
          "--service=queries.v1.QueriesAPI",
          "--tls",
          "--tls-server-name=deployment.namespace.svc.cluster.local"
        ]
      initialDelaySeconds: 10

Health Checking TLS Servers

Other Available Flags

Exit codes

It is not recommended to rely on specific exit statuses. Any failure will be a non-zero exit code.