Skip to main content

Caddy + Gatus - Chequear salud de los endpoints tras Authentik

Introducción

Apunte sobre cómo crear snippets en Caddy para fabricar endpoints de salud /healthz protegidos con un token. Esto permite que Gatus monitorice backends reales aunque las aplicaciones no tengan /healthz ni /status propio. La idea es que Caddy genere un check “virtual” hacia un path que sabemos que responde 200 si el servicio está vivo, pero manteniendo el endpoint oculto tras un header secreto.

Objetivo

  • Crear endpoints /healthz uniformes para cualquier servicio.
  • Que devuelvan 200 si el backend responde y 5xx si está caído.
  • Que Gatus pueda consultarlos mediante X-Health-Token.
  • Saltarse Authentik solo para los checks, sin romper la autenticación normal.

Snippets creados

# Healthz con path configurable (cuando hay que mapear a otra ruta sana)
(healthz_path) {
	@health {
		path /healthz
		header X-Health-Token gatus-SECRET-TOKEN
	}
	handle @health {
		rewrite * {args[1]}        # /healthz → path real del backend (/, /login, /admin...)
		reverse_proxy {args[0]} {
			import ip_headers
		}
	}
}

# Healthz directo (cuando basta con apuntar al root u otro path estable)
(healthz) {
	@health {
		path /healthz
		header X-Health-Token gatus-SECRET-TOKEN
	}
	handle @health {
		reverse_proxy {args[0]} {
			import ip_headers
		}
	}
}

El token (gatus-SECRET-TOKEN) se anota en el Caddyfile. Así Caddy solo responde 200 si el backend funciona, y exige la cabecera para no exponerlo.

Ejemplo práctico

Para un servicio sin health propio:

subdominio.dominio.tld {
	import tls_estricto
	import seguridad_basica
	import log_json_global

	# healthz externo → proxyea al backend /
	import healthz_path http://192.168.1.35:8300 /

	route {
		import authentik
		reverse_proxy http://192.168.1.35:8300 {
			import ip_headers
		}
	}
}

Con esto:

curl -i https://subdominio.dominio.tld/healthz \
  -H 'X-Health-Token: gatus-SECRET-TOKEN'

Si el backend está vivo → 200 OK. Si está caído → 502/5xx.

Integración con Gatus

En config.yaml se define el endpoint con el header:

endpoints:
  - name: Subdominio (/healthz)
    group: SubHerramientas
    url: https://subdominio.dominio.tld/healthz
    headers:
      X-Health-Token: "gatus-SECRET-TOKEN"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 2000ms"
      - "[CERTIFICATE_EXPIRATION] > 168h"

Así, Gatus monitoriza el backend real a través del /healthz fabricado en Caddy.

Beneficios

  • ✅ Checks reales: si el contenedor muere, Caddy devuelve 502 y Gatus lo detecta.
  • ✅ Compatibilidad con Authentik: los usuarios pasan por login, los checks no.
  • ✅ Endpoint oculto: solo accesible con X-Health-Token.
  • ✅ Flexibilidad: eliges qué ruta interna usar como prueba de vida.

Notas finales

  • Usa rutas que siempre den 200 sin login ni redirecciones (/, /login, /admin…).
  • Nunca expongas /healthz sin token.
  • Si el backend necesita cabecera Host, añade header_up Host {upstream_hostport} en el reverse_proxy.

Referencias o enlaces de interés

Back to top