traefik healthcheck: Probe Traefik Health
traefik healthcheck queries the Traefik ping endpoint and exits 0 if healthy or non-zero if not, making it a drop-in container health probe.
Traefik ships its own health command so a container does not need curl. It requires the ping entrypoint to be enabled, which is the most common reason it fails.
What it does
traefik healthcheck sends a request to the Traefik ping handler and translates the response into an exit code: 0 for healthy, non-zero otherwise. It reads the same static config as the server to find the ping entrypoint, so ping must be enabled for the command to work.
Common usage
# requires ping enabled in static config
traefik healthcheck
# with an explicit config file
traefik healthcheck --configFile=/etc/traefik/traefik.ymlEnable ping
# traefik.yml (static config)
ping:
entryPoint: "web"
# then in a Dockerfile
# HEALTHCHECK CMD traefik healthcheck || exit 1Options
| Flag | What it does |
|---|---|
| --configFile <file> | Static config file to read the ping settings from |
| --ping | Enable the ping endpoint (static config flag) |
| --ping.entryPoint | Which entrypoint serves the ping handler |
In CI
Use traefik healthcheck as the Docker HEALTHCHECK command so orchestration knows when Traefik is ready. In a smoke stage, gate rollout on the container reaching a healthy state. If you validate config instead, remember Traefik does not have a dedicated "validate" subcommand; a dry run is starting it and checking the health endpoint.
Common errors in CI
"ping is not enabled" or a connection refused from the command means the ping entrypoint is not configured; add the ping section. A non-zero exit while the dashboard works usually means the healthcheck is hitting the wrong entrypoint or port. On older Traefik v1, the command and config keys differ, so confirm you are on v2/v3 syntax.