2 stable releases
1.0.1 | May 21, 2022 |
---|---|
1.0.0 | May 20, 2022 |
#15 in #tls-server
14KB
106 lines
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
Option | Description |
---|---|
--tls |
use TLS (default: false) |
--tls-ca-cert |
path to file containing CA certificates (to override system root CAs) |
--tls-server-name |
override the hostname used to verify the server certificate |
Other Available Flags
Option | Description |
---|---|
--connect-timeout |
timeout in milliseconds for establishing connection |
--rpc-timeout |
timeout in milliseconds for health check rpc |
--user-agent |
user-agent header value of health check requests (default: grpc_health_probe_rs) |
--service |
service name to check (default: "") - empty string is convention for server health |
Exit codes
It is not recommended to rely on specific exit statuses. Any failure will be a non-zero exit code.
Exit Code | Description |
---|---|
0 | success: rpc response is SERVING . |
1 | failure: invalid command-line arguments |
2 | failure: connection failed or timed out |
3 | failure: rpc failed or timed out |
4 | failure: rpc successful, but the response is not SERVING |
Dependencies
~14–25MB
~447K SLoC