Health checks in the Apollo Router

Health checks are often used by load balancers to determine whether a server is available and ready to start serving traffic.

The Apollo Router supports 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:

1
health_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:

1
health_check:
2
  listen: 127.0.0.1:8090
3
  enabled: true
4
  path: /healthz

We can also disable the health check endpoint:

1
health_check:
2
  enabled: false

Testing with curl

The following example demonstrates using the curl command to send a basic health check query to an Apollo 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

3
2023-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) }

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:

1
health_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:

1
HEALTHCHECK CMD curl --fail \
2
  "http://127.0.0.1:8088/health" || exit 1

We don't define these in our example Dockerfiles, because they aren't commonly used. You can add them to your own images as needed.