health

health

Healthchecks for distroless containers: file marker + HTTP probe

A standalone Go library for Docker healthchecks in containers that lack a shell. Two modes:

• File marker — for containers whose main process is your own Go binary. The running process touches/removes a marker file; the probe process (re-invoked binary) stats it. Handles degraded mode (read-only filesystem) gracefully.
• HTTP probe — for containers wrapping a third-party server (Caddy, an upstream daemon) that cannot cooperate with a marker but already exposes an HTTP endpoint whose reachability is the health signal. Ships as its own nested module, github.com/cplieger/health/probe, with probe/cmd/probe as the ready-made static binary to bake into the image.

When you own the main process, prefer the file marker: Set(bool) expresses application state a network GET cannot. Standard library only (test dependency: pgregory.net/rapid).

The two modules version and release independently (vX.Y.Z tags for the marker library, probe/vX.Y.Z for the probe), so a marker-side release never forces a probe release or vice versa.

Install

Go: go get github.com/cplieger/health@latest

HTTP probe module: go get github.com/cplieger/health/probe@latest

Usage

Main process

package main

import "github.com/cplieger/health"

func main() {
    m := health.NewMarker(health.DefaultPath)
    defer m.Cleanup()

    // Mark healthy once ready
    m.Set(true)

    // ... run application ...
}

Health subcommand (probe process)

if len(os.Args) > 1 && os.Args[1] == "health" {
    health.RunProbe(health.DefaultPath)
}

External triggers and file ownership: the marker belongs to whoever created it. If a separate docker exec process updates it (a job scheduler invoking your binary's run/sync subcommand), run that exec as the same UID as the container's main process, e.g. user = 568:568 in an Ofelia job-exec block. A mismatched exec user fails the marker write with permission denied, and only the health signal is lost — silently under Set. A subcommand whose exit code an external scheduler alerts on can make that loss loud instead: call SetChecked and propagate the returned error into the exit code, so the scheduler's job fails rather than losing the heartbeat invisibly.

Freshness deadline (opt-in)

By default the probe checks existence only, and staleness stays owned by Docker's --interval. That check has a blind spot: once Set(true) has run, a deadlocked process keeps passing every probe. An app whose resident loop already calls Set(true) once per work cycle can arm a deadline, turning those calls into heartbeats — a marker older than the deadline probes unhealthy and Docker restarts the container:

if len(os.Args) > 1 && os.Args[1] == "health" {
    health.RunProbe(health.DefaultPath, health.WithMaxAge(3*interval))
}

Every Set(true) refreshes the marker's mtime, so the writing side needs no changes. Pick a max-age comfortably above one cycle interval plus the worst normal cycle duration (3× the interval is a sane default).

Arm it only where the resident process runs its own bounded work cycle at a known cadence, so a stale marker means a wedged loop that a restart fixes. Do NOT arm it for externally-triggered apps (a separate docker exec writes the marker): an idle resident between triggers is healthy, and restarting it cannot fix a trigger that stopped firing. Healthy() and Handler stay existence-based regardless.

HTTP probe (wrapped third-party servers)

For images whose main process is not your code — so nothing can touch a marker — bake the standalone probe binary into the image and point it at the endpoint(s) that define liveness:

FROM golang:1.26-alpine AS probe
RUN CGO_ENABLED=0 GOBIN=/out go install github.com/cplieger/health/probe/cmd/probe@latest

FROM gcr.io/distroless/static-debian12
COPY --from=probe /out/probe /probe
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD ["/probe", "http://127.0.0.1:2019/config/"]

Multiple URLs probe multiple surfaces in one run (all must answer 2xx within one shared -timeout budget, default 5s):

CMD ["/probe", "http://127.0.0.1:80/health", "http://127.0.0.1:2019/config/"]

Exit codes: 0 all healthy, 1 any probe failed (each failure written to stderr, visible in docker inspect), 2 usage error. From Go, the same logic is probe.URL(ctx, url) / probe.Check(w, timeout, urls...) / probe.Run(timeout, urls...) from the github.com/cplieger/health/probe module.

Optional HTTP handler (K8s HTTP probes)

For containers that also expose an HTTP endpoint, the library provides an optional Handler that emits JSON status — compatible with K8s HTTP liveness probes and mirroring the response shape of hellofresh/health-go:

import "github.com/cplieger/health"

m := health.NewMarker(health.DefaultPath)
http.Handle("/healthz", health.Handler(m))

Response (200 OK):

{"status":"OK","timestamp":"2025-01-01T00:00:00Z"}

Response (503 Service Unavailable):

{"status":"Unavailable","timestamp":"2025-01-01T00:00:00Z"}

Degraded mode caveat: when the marker directory is unwritable (e.g. read_only: true with no /tmp tmpfs), Handler reports 503, intentionally diverging from the health subcommand probe (ProbeCheck), which reports healthy to avoid a Docker restart loop. Do not wire Handler as the sole liveness probe on a service that may run read-only without a /tmp tmpfs, or it will restart-loop a container that is actually alive.

API

• DefaultPath — default marker path (/tmp/.healthy)
• Signal — interface with Healthy() bool
• Marker — main type; implements Signal
• NewMarker(path string) *Marker — constructor (probes dir writability)
• (*Marker).Set(ok bool) — touch or remove marker (failures logged and swallowed)
• (*Marker).SetChecked(ok bool) error — Set with the filesystem outcome reported; nil in degraded mode (the marker channel is deliberately inert there, so callers don't turn a compose misconfiguration into an alert loop)
• (*Marker).Cleanup() — remove marker on shutdown
• (*Marker).Healthy() bool — stat-based liveness check
• Status — JSON response struct emitted by Handler (fields: Status, Timestamp)
• Handler(s Signal) http.Handler — optional JSON health endpoint
• RunProbe(path string, opts ...ProbeOption) — probe process entry (calls os.Exit)
• ProbeCheck(path string, opts ...ProbeOption) int — testable probe logic (0=healthy, 1=unhealthy)
• ProbeOption / WithMaxAge(d time.Duration) — opt-in freshness deadline for the probe side (marker older than d is unhealthy; non-positive d disables)

In the github.com/cplieger/health/probe module:

• probe.DefaultTimeout — default shared budget for one HTTP probe run (5s)
• probe.URL(ctx context.Context, url string) error — single HTTP liveness GET; nil on a 2xx final response
• probe.Check(w io.Writer, timeout time.Duration, urls ...string) int — testable multi-URL probe (0=all healthy, 1 otherwise; probes all URLs, one failure line each; zero URLs is unhealthy)
• probe.Run(timeout time.Duration, urls ...string) — probe process entry (calls os.Exit); probe/cmd/probe is the ready-made binary around it

Unsupported by design

The following features are deliberately excluded. This library complements HTTP-based health libraries (e.g. hellofresh/health-go, alexliesenfeld/health) rather than competing with them — those are server-side check frameworks, while this library's HTTP probe is a client-side liveness GET for the HEALTHCHECK side of the same connection.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude Opus and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

GPL-3.0 — see LICENSE.