Cloudflared Docker: getting the health status to work

This guide explains how to use the Docker container of cloudflare/cloudflared:latest with a functioning healthcheck via the metrics & ready endpoints.

The Cloudflared docker image can help you bring secure connectivity to other parts of your Docker setup.

1. Why include a healthcheck for Cloudflare Tunnel?

By default, cloudflared launches a Prometheus /metrics server accessible (within the container) on 0.0.0.0:PORT.

However, there is no built‑in healthcheck command in the official Docker image.

The /ready endpoint can be used to verify if the tunnel is ready.

2. Docker Compose configuration example

# Cloudflare Tunnel Service
cloudflare-tunnel:
  image: cloudflare/cloudflared:latest
  container_name: logcentral-cloudflare-tunnel
  restart: unless-stopped
  environment:
    - CLOUDFLARE_TUNNEL_TOKEN=${CLOUDFLARE_TUNNEL_TOKEN}
  command: >
    tunnel --metrics 127.0.0.1:60123 --no-autoupdate 
    run --token ${CLOUDFLARE_TUNNEL_TOKEN}
  healthcheck:
    test: ["CMD", "cloudflared", "tunnel", "--metrics", "127.0.0.1:60123", "ready"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 10s
  labels:
    - "traefik.enable=false"

➡️ Explanations:

• --metrics 127.0.0.1:60123 forces the metrics endpoint to be available on localhost (see more info here).
• The healthcheck command uses cloudflared tunnel --metrics 127.0.0.1:60123 ready to query the readiness endpoint directly.
• The interval, timeout, retries, and start_period parameters control how Docker waits and retries the health check.

That is what we use for certain services of our syslog platform LogCentral.

This post is also available in fr_FR.