Deploying

Canary releases

Try a new image on one web replica while the others keep serving the current one, then promote it everywhere or abort.

Using them

The app's Settings → Releases, the CLI, or the API:

stackd canary start web --image ghcr.io/acme/web:1.5.0   # one replica
stackd canary status web                                  # how it's doing
stackd canary promote web                                 # everywhere
stackd canary abort web                                   # back

POST /api/apps/{id}/canary ({"image": …}, the app's own image when omitted: a built app's newest build, not running yet), GET for its state, POST …/canary/promote and …/canary/abort.

  • Start needs at least two healthy (or running) web replicas. It deploys the image to one replica (the oldest), replacing it once the new one is up, as any deploy does; the others keep what most of them run (the baseline). The app's image stays as it was.
  • Traffic: with load balancing (the app's Load balance setting) every domain's requests are spread over the replicas, so the canary gets one in N. Without it, it gets what reaches its server. Compare its errors and latency in the app's Traffic tab and its replica's logs and metrics (stackd logs web -f).
  • Promote deploys the canary's image everywhere and makes it the app's image. Abort puts the baseline back on the canary's server (and, for a built app whose image became the canary's build, back as the app's image).

Good to know

  • Any deploy everywhere ends a canary under way.
  • Deploy tokens may run canaries; on a protected app only admins may, since a canary is a release.