waiter Commands

Sequence diagrams for each waiter subcommand — the C4 dynamics level of the waiter architecture. Participants are waiter's internal packages: cmd/ (Cobra commands), strategy/ (blue-green, canary, rolling, restart), plugin/ (PATH discovery and subprocess execution), state/ (per-service JSON state files in ~/.local/share/waiter/), and health/ (status polling) — plus the externals they talk to: engine plugin subprocesses (waiter-podman, waiter-docker, waiter-quadlet, waiter-systemd), proxy plugin subprocesses (waiter-proxy-haproxy, waiter-proxy-kamal), the filesystem, and stdin.

waiter deploy

Deploys a service from a container entity (-f file or - for stdin, required) using --strategy blue-green (default), canary, rolling, or restart. Engine and proxy plugins are named via --engine/--proxy (auto-prefixed waiter-) or auto-detected from PATH — auto-detection fails if zero or more than one plugin of that type is installed. Slots use fixed ports: blue 8081, green 8082, canary 8083. Unreadable input exits 2; all other failures exit 1. A failed health check stops the new container and leaves the old one serving. The -o/--output flag is accepted but ignored — the result is always indented JSON (a known gap). Rolling is currently single-instance and behaves like blue-green except the new slot registers directly at full weight; restart stops the old container before deploying, so a failed restart deployment leaves the service down.

waiter promote

Promotes an in-progress canary to full traffic: shifts the canary to weight 256, drains and removes the old slot (--drain-timeout, default 30s), stops the old container, and re-registers the canary under the free blue/green slot name. Only the initial shift-to-canary is error-checked — every later plugin call is best-effort. The saved state's strategy is overwritten to blue-green regardless of how the service was originally deployed. Exits 1 if the service has no state or no canary in progress.

waiter abort

Cancels an in-progress canary: removes <service>-canary from the proxy, stops the canary container (both best-effort — plugin failures are ignored), and clears the canary slot from the state file. Prints a confirmation on stderr and the updated state as JSON on stdout. Exits 1 if the service has no state or no canary in progress.

waiter rollback

Restores the previous deployment slot: starts the previous container, waits for it to become healthy (--health-timeout, default 60s), registers it with the proxy at full weight, then drains and stops the current slot (--drain-timeout, default 30s) and swaps Current/Previous in the state file. Start, health check, and proxy register are error-checked and exit 1 on failure — with no attempt to undo a partial rollback; the teardown of the old current slot is best-effort. Requires a recorded Previous slot.

waiter status

Reads deployment state only — no plugins are invoked, so it reports what waiter last recorded, not live container status (use reconcile for that). With a service argument it prints that service's state as JSON; without, it lists every *.json in the state directory (unparsable files are silently skipped). An empty state directory prints "No managed services found." on stderr and exits 0; an unknown named service exits 1.

waiter reconcile

Compares recorded state against reality: asks the engine plugin for the current container's status and the proxy plugin for backend health, and reports ok, drifted, or fixed per service (one service, or all when run bare). --fix only repairs container drift by starting the container — proxy drift is reported but never fixed, and in the "container exists but not running" branch the status is marked fixed without re-verifying health. In all-services mode a failing service becomes a status: "error" entry in the JSON array and the command still exits 0.

waiter plugins

Scans every PATH directory for executable waiter-* binaries, then runs <plugin> info -o json on each to collect type (engine or proxy), engine, version, and description — accepting both flat JSON and HERY-enveloped responses. Output is a table by default, or JSON/YAML via -o, optionally wrapped in a HERY envelope with --hery; a plugin whose info call fails still appears, with ? fields. No plugins installed prints a notice on stderr and exits 0.