Deployments

Canary & progressive rollouts

Route a traffic share to the new version, verify it against the stable baseline, then promote.

What a rollout is

A rollout deploys the new version alongside the stable one instead of replacing it: the stable version keeps serving while the new version (the canary) receives a share of live traffic through the proxy's weighted routing. Every step of the plan is verified before the next share is applied, and the final 100% step is the promotion.

Terminal

# One-shot canary: 5% of traffic for the verification window, then promotephelix rebuild myapp --canary 5 # Same thing, resolved from phelix.yaml (deploy.strategy: canary)phelix rebuild myapp # Multi-step progressive rollout from phelix.yamlphelix rebuild myapp --strategy progressive

Rollout output

→ step 1/4: routing 5% of traffic to the canary for 2m    v12  ███████████████████  95%    v13  █                     5%  → monitoring canary for 2m (health and metrics every 5s)    v13: 1,284 requests, 0.23% errors, p95 81ms    v12: 24,391 requests, 0.31% errors, p95 74ms  ✓ step 1/4 verified at 5% traffic...✓ traffic switched fully to slot green (zero downtime)✓ progressive rollout of myapp complete: v13 serves 100% of traffic on slot green

One-shot canary

phelix rebuild myapp --canary 5 routes 5% of traffic to the new version for the verification window, compares health and metrics against the stable baseline, and promotes on success. The share and the window come from deploy.rollout.canary and deploy.rollout.duration in phelix.yaml (defaults 10% and 30s).

--canary requires an existing deployment to serve as the stable baseline - deploy with --blue-green (or --replicas N) first. A rollout over a rolling fleet consolidates it to a single stable instance (its first replica) for the comparison and promotion.

Progressive rollouts

A progressive rollout raises the canary's traffic share step by step instead of in one jump. Each step carries a traffic percentage and an optional duration; shares must strictly increase and the final step must be 100% - the promotion.

phelix.yamlyaml

deploy:  strategy: progressive  rollout:    steps:      - traffic: 5%        duration: 2m      - traffic: 25%        duration: 5m      - traffic: 50%        duration: 5m      - traffic: 100%        # the final promotion step (required)

Every step is verified for its whole window before the next share is applied. A step that regresses aborts the rollout and restores the stable version at 100% of traffic.

Verification thresholds

The proxy counts requests, 5xx/failed responses and latency per backend, so each window compares the canary's error rate and p95 latency against the stable baseline using the verification thresholds:

Threshold	Default	Fails the step when
interval	5s	Health and metrics are polled on this cadence during each window
max_error_rate	5	The canary's absolute error rate exceeds this percentage
max_error_delta	2	The canary's error rate exceeds the baseline's by this many percentage points
max_p95_factor	3	The canary's p95 latency exceeds N times the baseline's p95

With no per-backend metrics available the rollout degrades to health-only verification instead of guessing. The canary must also pass the same deploy-tier health gate blue-green uses before it receives any traffic.

Safety behavior

Never route to an unhealthy canary. The canary must pass the deploy-tier health gate blue-green uses before it receives any traffic, and every step keeps probing it for the whole window.
Automatic rollback to stable. Any regression (health failure, error rate, latency) aborts the rollout: traffic switches back to the stable version at 100% atomically, the canary instance is stopped, and the failure is reported (CANARY_REGRESSION). This restore is built into the rollout - it does not need --auto-rollback, which still covers the cases where the restore itself fails.
Cancellation. Ctrl-C aborts the rollout through the same restore path (the stable version keeps 100% of traffic); the cleanup runs even though the deploy was interrupted.
Crash recovery. A rollout interrupted by a crash leaves the stable version serving; the next deploy restores stable routing and reclaims the leftover canary before doing anything else.
Success is durable. The rollout is only reported successful after the final promotion is complete: state persisted, version promoted in versions.json, old instance drained.

Requirements

The proxy daemon must be running (the rebuild auto-starts it).
An existing deployment as the stable baseline - deploy with --blue-green or --replicas N first.
--canary cannot be combined with --strategy, --blue-green, or --replicas - it already names a strategy. An unrecognized strategy value fails with INVALID_ARGUMENT (exit code 2) before anything is built.