Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Operations › Health Checks

Health Checks

SharedStatus: SUPPORTED for process probes. Not a Kubernetes product integration.Audience: deployment engineer, incident operator

Purpose

Determine whether the Manager process is alive and whether it is ready to serve (listeners admitted, PostgreSQL health check passed).

This is the operator procedure. Endpoint JSON is in API health and Manager health.

Prerequisites

  • Manager process or zwall-manager.service installed
  • Network path to the listen address (example YAML server.port / server.api_port 8443; zwallctl default 8080 is a known mismatch — use the real listener)

Required permissions: unauthenticated HTTP GET for /health/live and /health/ready. Admin JWT for /metrics and zwallctl check (sanity-check API).

Procedure — process probes

Prefer live and ready separately.

curl -fsS https://MANAGER_HOST:8443/health/live
curl -fsS https://MANAGER_HOST:8443/health/ready

Self-signed lab certificates need curl -k only in non-production. Production should use a trust store.

Liveness 200: {"status":"alive","timestamp":<unix seconds>}.
Liveness 503: {"status":"draining","timestamp":...} when updater runtime mode is draining or updating (updater is not a production upgrade path; still interpret 503 as “do not send traffic”).

Readiness 200: status is ready, database is ok, checks empty or omitted.
Readiness 503: status is not_ready. checks may include:

  • manager: listener_admission_incomplete
  • database: not_configured
  • database: timeout
  • database: plus the health-check error
  • cluster: timeout if cluster is enabled (cluster is not a public HA product)

Timeout is health.readiness_timeout (code default 5s when set).

GET /health and GET /api/v1/health are compatibility aliases. Prefer live/ready.

Procedure — CLI 

zwallctl ping --manager-url https://MANAGER_HOST:8443
zwallctl check --manager-url https://MANAGER_HOST:8443

ping GETs /api/v1/health. check [check-name] GETs /api/v1/system/sanity-check or /api/v1/system/sanity-check/{name} (admin).

zwallctl default URL is http://localhost:8080. If ping fails with connection refused, you are likely hitting the port mismatch, not a dead Manager.

Procedure — systemd 

systemctl is-active zwall-manager
systemctl is-active zwall-agent
systemctl is-active zwall-hosting-ebpf-loader
systemctl is-active zwall-hosting-agent

Hosting v2 unit name is zwall-hosting-agent-v2.service when that unit is what the release shipped. Use the installed name.

is-active is not readiness. A running Manager with PostgreSQL down is live and not ready.

Expected result

Scroll sideways to see the full table. Use the arrow keys when focused.

CheckHealthy
live200 alive
ready200 ready, database ok
systemdactive
pingsuccess to the real URL

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

ResultMeaningNext
connection refusedwrong port, unit down, listen not boundManager unavailable
TLS handshake failcert/key mismatch, tls.enabledTLS
live 200, ready 503process up, DB or listener not admittedjournal + PostgreSQL
live 503 drainingupdater draindo not treat as healthy; updater is not the production upgrade path

Security considerations

Live/ready are unauthenticated by design for a local load balancer. Do not expose them on the public Internet without an independent ACL. /metrics is admin-gated when enabled.

Limitations

  • Not a Kubernetes shipping integration. Probe-style paths are HTTP only.
  • Blocking-authority extra JSON keys are additive; do not invent a second public contract.
  • Community does not implement GetEBPFHealth.