Health Checks
Determining the router's status
Health checks are often used by load balancers to determine whether a server is available and ready to start serving traffic.
GraphOS Router and Apollo Router Core support a basic HTTP-level health check. This is enabled by default and is served on port 8088
at the URL path /health
. This returns a 200
status code if the HTTP server is successfully serving.
You can change this by setting health_check
:
1health_check:
2 listen: 127.0.0.1:8088
3 enabled: true
4 path: /health # Optional, default: /health
Each option is configurable. For example, we can set our health check endpoint to 127.0.0.1:8090/healthz
:
1health_check:
2 listen: 127.0.0.1:8090
3 enabled: true
4 path: /healthz
We can also disable the health check endpoint:
1health_check:
2 enabled: false
Testing with curl
The following example demonstrates using the curl
command to send a basic health check query to a router instance running at 127.0.0.1:4000
:
1$ curl -v "http://127.0.0.1:8088/health"
2* Trying 127.0.0.1:8088...
3* Connected to 127.0.0.1 (127.0.0.1) port 8088 (#0)
4> GET /health HTTP/1.1
5> Host: 127.0.0.1:8088
6> User-Agent: curl/7.79.1
7> Accept: */*
8>
9* Mark bundle as not supporting multiuse
10< HTTP/1.1 200 OK
11< vary: origin
12< content-type: application/json
13< content-length: 15
14< date: Wed, 21 Sep 2022 17:10:45 GMT
15<
16* Connection #0 to host 127.0.0.1 left intact
17{"status":"UP"}
Logging
If you start the router with trace logging enabled, you will see a log from the router for each health check:
1--log apollo_router=trace
2
32023-01-23T17:42:04.640501Z apollo-router/src/axum_factory/axum_http_server_factory.rs:100 TRACE apollo_router::axum_factory::axum_http_server_factory: health check health=Health { status: Up } request=Request { method: GET, uri: /health, version: HTTP/1.1, headers: {"host": "127.0.0.1:8088", "user-agent": "curl/7.85.0", "accept": "*/*"}, body: Body(Empty) }
4
This may be helpful with confirming that health-checks are working correctly.
Using in a containers environment
The health check listens to 127.0.0.1 by default, which won't allow connections issued from a network. While this is a safe default, other containers won't be able to perform health checks, which will prevent the router pod from switching to a healthy state.
You can change this by setting health_check
:
1health_check:
2 listen: 0.0.0.0:8088
3 enabled: true
Using with Kubernetes
In Kubernetes, you can configure health checks by setting readinessProbe
and livenessProbe
on the containers
object of the resource definition:
1 # ... snipped for partial example ...
2 containers:
3 - name: router
4 # ... snipped for partial example ...
5 livenessProbe:
6 httpGet:
7 path: "/health"
8 port: 8088
9 readinessProbe:
10 httpGet:
11 path: "/health"
12 port: 8088
13 # ... snipped for partial example ...
See a more complete example in our Kubernetes documentation .
Using with Docker
Docker has a HEALTHCHECK
instruction that tells Docker how to test whether a container is still working. These are defined in the Dockerfile
when building your container:
1HEALTHCHECK CMD curl --fail \
2 "http://127.0.0.1:8088/health" || exit 1
We don't define these in our example Dockerfile
s, because they aren't commonly used. You can add them to your own images as needed.