Skip to main content

Health checks for a Cloider app

A health check is a path of your app, such as /healthz, that Cloider requests on every replica to know whether it can serve. With one set, a new version only goes live once it passes, a replica that starts failing stops receiving requests, and one that keeps failing is restarted. This page explains what the check does, its settings, how to write a good health endpoint, and what you see when it fails. A cron job has no health check: each run is judged by its exit code.

At a glance​

Without a path (the default)With a path
ChecksThat something accepts connections on the app's portA GET on the path, passing on a 2xx or 3xx answer
A new version goes liveOnce every replica accepts connectionsOnce every replica passes
A failing replicaIsn't restarted while its port stays openStops receiving requests after 2 failures in a row, and is restarted after the Failure threshold
SettingsNoneInterval, Timeout, Failure threshold, Grace period
Managed withDashboard, cloider app update, REST API, the update_app_settings MCP tool

The health check is in the Advanced settings section of the Create new app form and of the app's Settings tab. It costs nothing.

How does a health check work?​

Every Interval seconds, Cloider sends each replica a GET request on the Health check path, over plain HTTP on the app's port. An answer from 200 to 399 within the Timeout passes; anything else, no answer, or a refused connection fails.

  • While a replica starts, it has the Grace period to pass its first check, and failures within it are expected. A replica that hasn't passed by the end of it is restarted.
  • Once it passes, it receives requests.
  • After 2 failures in a row (or 1, with a Failure threshold of 1), it stops receiving requests. The other replicas keep serving. It gets requests again as soon as it passes once more.
  • After Failure threshold failures in a row, it is restarted, and starts again with a new grace period.

A new version replaces the old one only once every new replica passes and stays up for 15 seconds. If it doesn't within 5 minutes, the deploy fails and the previous version keeps serving. See Builds and deployments.

Health check settings​

SettingRangeDefaultWhat it does
Health check pathUp to 200 characters, starting with /EmptyThe path checked. A query string is allowed (/healthz?full=1), spaces aren't. Empty checks only the port
Interval1 to 300 seconds10How often each replica is checked
Timeout1 to 60 seconds, at most the interval5How long a check waits for an answer
Failure threshold1 to 306Failed checks in a row before a replica is restarted
Grace period0 to 300 seconds300How long a starting replica has to pass its first check. 0 counts failures from the start

With the defaults, a replica that stops answering is out of traffic after about 20 seconds and restarted after about a minute. The timings only apply with a path, so the dashboard shows them once you type one.

Set a health check​

Saving a health check redeploys the version the app is running, without a rebuild. The new replicas must pass the new check to go live, so a path your app doesn't answer fails the redeploy and leaves the old replicas serving.

  1. Open the app and go to the Settings tab.
  2. Open Advanced settings, below the start command, and scroll to Health check path.
  3. Type the path, for example /healthz. Interval, Timeout, Failure threshold and Grace period appear with their defaults; change them if you need to.
  4. Click Save changes. The toast says Your app is redeploying with its new settings.
The health check fields of the blog app's Settings tab: Health check path /healthz, Interval 10 seconds, Timeout 5 seconds, Failure threshold 6 and Grace period 300 seconds
The health check, in the Advanced settings section of the Settings tab.

The Summary on the Overview tab shows it on its Health check row, for example /healthz, every 10s, restarted after 6 failures in a row, or Listening on port 3000 without a path.

To remove the health check, clear the path and save.

Write a good health endpoint​

The check's request goes straight to each replica, not through your domain, so it measures that replica alone. A good health endpoint:

  • Answers fast and cheaply, well within the Timeout, without logging in or rendering a page.
  • Answers 200 once the app can serve, and an error while it can't, for example before it has loaded its configuration or while it is shutting down.
  • Thinks twice before checking other services. A check that also queries the database takes every replica out of traffic when the database is unreachable, and restarts them all, which doesn't bring the database back. Check only what a restart can fix, or give such a check its own path that you monitor yourself.
server.js (Express)
app.get("/healthz", (req, res) => res.status(200).send("ok"));
app.py (Flask)
@app.get("/healthz")
def healthz():
return "ok", 200

Apps that only answer known hosts​

The check's Host header is the replica's own address, not your domain. A framework that refuses unknown hosts answers it with an error, and the check fails:

  • Django answers 400 (DisallowedHost) when the host isn't in ALLOWED_HOSTS. Answer the health check path in a middleware placed before django.middleware.common.CommonMiddleware, so the host is never checked for it.
  • Rails answers 403 (blocked host) when config.hosts is set. Exclude the path from host authorization: config.host_authorization = { exclude: ->(request) { request.path == "/up" } }, with /up as the health check path.

Health check requests reach your app like any other request, so a framework that logs every request logs them too. Skip logging for the health check path to keep your logs readable.

What happens when the health check fails?​

During a deploy, the new version doesn't go live and the previous one keeps serving. The build fails with a message saying why, which the Builds tab and cloider app builds show:

MessageMeaning
The health check at /healthz failed: it answered with HTTP 500.The app answered, with an error status
The health check at /healthz failed: nothing was listening on the port.Nothing accepts connections on the app's port. Check the port on the Settings tab
The health check at /healthz failed: it did not answer in time.No answer within the Timeout
The health check at /healthz failed: it closed the connection without answering.The connection was closed before an answer
The health check at /healthz did not pass within the grace period, so the app was restarted: ...The app took longer than the Grace period to start passing. Raise it, or make the app start faster
The health check at /healthz kept failing, so the app was restarted: ...It passed, then failed Failure threshold times in a row

The build's logs end with the app's own output, which usually says why. See Troubleshooting.

While the app runs, a failing replica is taken out of traffic and, if it keeps failing, restarted, while the other replicas serve. The Replica picker on the Logs tab and cloider app replicas show it as not ready, with Failing its health check, it answered with HTTP 503 and the like, or Restarted for failing its health check after a restart. See See an app's replicas.

If every replica fails at once, the app has nothing to serve: requests to it fail until one passes again. Running at least 2 replicas protects against one replica failing, not against a bug or an outage they all share.

Troubleshooting​

MessageCause and fix
Health check path must start with / and be a URL path, without spacesStart the path with / and leave out spaces; encode them as %20
Health check path must be at most 200 charactersUse a shorter path
Timeout must not be longer than the intervalLower the timeout or raise the interval
Interval must be between 1 and 300 secondsAnd the matching ranges for Timeout (1 to 60), Failure threshold (1 to 30) and Grace period (0 to 300)
The deploy fails with it answered with HTTP 404The app doesn't serve that path. Add the route, or fix the path
The deploy fails with it answered with HTTP 400 or 403The app refuses the check's host. See Apps that only answer known hosts
The deploy fails with it answered with HTTP 401The path needs a login. Serve the health check without one
Replicas restart every few minutesThe endpoint is too slow or depends on a service that fails. Make it cheaper, raise the Timeout or the Failure threshold
a cron job has no health check, each run is checked by its exit code (CLI)Cron jobs have no health check

Next steps​

Frequently asked questions

How do I add a health check to a Cloider app?

Type a path such as /healthz in Health check path, in the Advanced settings section of the app's Settings tab, and save. From the CLI, run cloider app update <app> --health-check-path /healthz. The app is redeployed with the check.

What counts as a passing health check?

An HTTP answer from 200 to 399 to a GET on the path, within the timeout (5 seconds by default). Any other status, a refused connection or no answer fails.

What happens when my app fails its health check?

During a deploy, the new version does not go live and the previous one keeps serving. While the app runs, a replica that fails 2 checks in a row stops receiving requests, and one that fails the failure threshold (6 by default) in a row is restarted.

What does Cloider check without a health check path?

Only that something accepts connections on the app's port. A new version goes live once it does, but a replica that stops answering requests while its port stays open is not restarted. Set a path to have it checked over HTTP.

Why does my Django app fail its health check with 400?

The check's Host header is the replica's own address, which is not in ALLOWED_HOSTS, so Django answers 400. Answer the health check path in a middleware placed before CommonMiddleware.

Does the health check go through my domain?

No. It goes straight to each replica on the app's port over plain HTTP, so it checks every replica separately and does not count as traffic to your domain.