fix: add proxy health checks from app.json readiness
The caddy, haproxy, openresty, and traefik docs stated that requests are only routed to containers passing healthchecks, but these proxies route to a new container as soon as it starts. The first `web` readiness healthcheck in `app.json` is now also turned into health checks and retries for caddy and openresty, as it already was for traefik, so requests are routed away from containers that are not yet ready, and the docs now describe how each proxy actually behaves.
This commit is contained in:
15 files changed
+694
-39
No files matched your search
@@ -32,7 +32,53 @@ The Caddy plugin has specific rules for routing requests:
|
||||
- If no `http:80` mapping is found, the first `http` port mapping is used for http requests.
|
||||
- If no `https:443` mapping is found, the first `https` port mapping is used for https requests.
|
||||
- If no `https` mapping is found, the container port from `http:80` will be used for https requests.
|
||||
- Requests are routed as soon as the container is running and passing healthchecks.
|
||||
- Requests are routed as soon as the container is running, before Dokku's healthchecks have passed. See the [healthchecks](#healthchecks) section for how Caddy avoids routing to containers that are not yet ready.
|
||||
|
||||
### Healthchecks
|
||||
|
||||
When an app has a readiness healthcheck defined in its `app.json` file with a `path` property, Dokku automatically generates Caddy healthcheck and retry labels. These configure Caddy to periodically check each container, stop routing traffic to containers that fail the check, and retry requests that fail to connect against another container.
|
||||
|
||||
The following `app.json` healthcheck properties are mapped to Caddy labels:
|
||||
|
||||
| app.json Property | Caddy Label | Description |
|
||||
|-------------------|-------------|-------------|
|
||||
| `path` | `caddy.reverse_proxy.health_uri` | The HTTP path to check (required) |
|
||||
| `port` | `caddy.reverse_proxy.health_port` | The port to check |
|
||||
| `timeout` | `caddy.reverse_proxy.health_timeout` | Timeout in seconds (formatted as `Xs`, defaults to `5s`) |
|
||||
| `wait` | `caddy.reverse_proxy.health_interval` | Interval between checks in seconds (formatted as `Xs`, defaults to `5s`) |
|
||||
|
||||
Additionally, the following labels are generated:
|
||||
|
||||
| Caddy Label | Value | Description |
|
||||
|-------------|-------|-------------|
|
||||
| `caddy.reverse_proxy.health_headers.Host` | the first app domain | The `Host` header sent with the healthcheck, matching the header Dokku sends during deploy checks |
|
||||
| `caddy.reverse_proxy.lb_try_duration` | `5s` | How long a request that fails to connect is retried against other containers |
|
||||
| `caddy.reverse_proxy.lb_try_interval` | `250ms` | How long to wait between retries |
|
||||
|
||||
Example `app.json` configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"healthchecks": {
|
||||
"web": [
|
||||
{
|
||||
"name": "web readiness check",
|
||||
"path": "/health",
|
||||
"timeout": 5,
|
||||
"type": "readiness",
|
||||
"wait": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Caddy considers a new container healthy until its first check fails. The first check runs as soon as Caddy picks up the new container, and requests that reach the container before then and fail to connect are retried against the still-running old container.
|
||||
|
||||
The `scheme` property is not mapped, as Caddy uses the same transport for healthchecks as for proxied requests. Any of the generated labels may be overridden via the `caddy:labels:add` command.
|
||||
|
||||
> [!NOTE]
|
||||
> Only the first readiness healthcheck with a `path` property is used. Apps without one are routed as soon as the container is running. See the [zero downtime deploys documentation](/docs/deployment/zero-downtime-deploys.md#healthchecks-and-label-based-proxies) for more information.
|
||||
|
||||
### Switching to Caddy
|
||||
|
||||
|
||||
Reference in new issue
Block a user