Canary Deployments: How to Roll Out Backend Changes Safely
A canary deployment sends a small slice of traffic to a new backend version, watches metrics, then promotes or rolls back. How it differs from blue-green, how CodeDeploy and Kubernetes progressive delivery do it, and how Encore fits without claiming built-in traffic splitting.
A canary deployment ships a new backend version to a small share of real traffic, watches whether that share stays healthy, then either promotes the version to everyone or pulls it back. The name comes from the canary in the coal mine: a few requests take the risk so the rest of the fleet does not.
Unlike blue-green cutover, canary accepts mixed versions on purpose so a small share of traffic validates the release before the rest moves. This guide covers how canaries work, how they differ from blue-green, how AWS and Kubernetes implement them at a high level, and how Encore (infrastructure from code) fits without inventing a traffic-splitting feature it does not have.
What is a canary deploy?
You run the stable revision for most traffic and a canary revision for a small percentage, often 5 or 10 percent. Metrics and alerts watch the canary: error rate, latency, saturation, business counters. If the canary looks wrong, you shift weight back to stable. If it looks right, you increase the percentage in steps until the canary is the new stable.
The hard requirements are a router that can split traffic by weight, metrics that isolate the canary, and a rollback that is as automated as the promote path. Without them, a canary behaves like an ordinary rolling deploy.
Canary vs blue-green
Use canary when you need signal from production users and can tolerate mixed versions. Use blue-green when mixed versions are unsafe or when rollback must be a single router flip. A common pattern is rolling deploys for ordinary releases and reserve canary or blue-green for high-risk changes.
How platforms implement canaries
AWS CodeDeploy on ECS and Lambda
AWS CodeDeploy ships predefined canary configurations for Amazon ECS and AWS Lambda. For ECS, CodeDeployDefault.ECSCanary10Percent5Minutes sends 10 percent of traffic to the new task set, waits five minutes, then sends the rest. A 15-minute variant exists for slower bake times. Linear options shift 10 percent every one or three minutes instead. CloudWatch alarms attached to the deployment group can stop the rollout when error or latency thresholds fire.
That path needs the ECS blue/green deployment controller, two target groups and the CodeDeploy roles ECS documents. Each of those has to be set up.
Kubernetes progressive delivery
On Kubernetes, canaries usually mean a second Deployment plus a Service, Ingress, Gateway or mesh that weights traffic. Controllers such as Argo Rollouts and Flagger automate the steps: raise weight, run analysis, promote or abort. Google Cloud Deploy can run canary phases against GKE and Cloud Run with configured percentage steps and optional automated analysis.
The shared idea is the same as CodeDeploy: percentage steps, health signals, automatic or manual promote.
What you measure during a canary
Watch the canary cohort, not only the global service dashboard. Error rate and p95 latency are the baseline. Add saturation (CPU, memory, queue lag) and one or two business metrics that would move if the release were wrong, such as checkout success or auth failure rate. Bake time has to be long enough for traffic to represent real use; a five-minute canary at 3 a.m. proves little.
What does Encore offer instead of canary splitting?
Encore combines an open source infrastructure SDK for TypeScript and Go with a platform that provisions and deploys into your own AWS or GCP account. Encore does not document built-in canary traffic splitting, weighted target group schedules or CodeDeploy-style percentage steps.
What Encore does provide around safer rollouts:
Set up the app
Run in your terminal to get started locally.
Expose a version marker and a health endpoint so any external canary layer, or a simple smoke check, can tell revisions apart:
// hello/hello.ts
import { api } from "encore.dev/api";
export const health = api(
{ expose: true, method: "GET", path: "/health" },
async (): Promise<{ ok: boolean; release: string }> => {
return { ok: true, release: "2026-11-05" };
},
);
encore run runs the service locally with the infrastructure the code declares. On deploy, Encore creates the Fargate services, load balancer and declared resources in your account, and provisions an IAM role for the service. An AI coding agent can bump the release string, add a metric hook and open a pull request, and reviewers and automated checks use the preview environment before production.
If you need a true percentage canary on ECS, wire CodeDeploy or ALB weights yourself on top of infrastructure you control, or run canaries at the edge. Encore handles the path from commit to a rolling deploy with the infrastructure declared in the app, and its traces help you decide whether the release was good.
Best fit: Teams that want infrastructure from code and fast, observable redeploys in their own cloud, adding CodeDeploy, a mesh or Cloud Deploy when a release needs weighted canaries.
Good to know
- A canary without canary-scoped metrics gives no usable signal. Split dashboards by revision or target group before the first production canary.
- Feature flags can approximate canaries inside one deploy, and they do not replace traffic shifting when the risk is in process startup, memory or migrations.
- Prefer expandable schema changes so a partial rollout never leaves the stable version unable to read new rows.
Related guides
Frequently asked questions
What is a canary deployment?
A canary deployment releases a new version to a small percentage of traffic first, watches error rates and latency, then either shifts the rest of the traffic to the new version or rolls back to the stable version.
What is the difference between canary and blue-green deployment?
Blue-green switches all traffic from one environment to another in one cutover. Canary keeps both versions serving users at once and increases the new version's share over time, so bad releases affect only a fraction of requests before you decide.
How does AWS CodeDeploy canary work for ECS?
For Amazon ECS, CodeDeploy can shift 10 percent of traffic to the new task set, wait five or fifteen minutes, then shift the remaining 90 percent, using configurations such as CodeDeployDefault.ECSCanary10Percent5Minutes. CloudWatch alarms can stop the deployment if metrics breach.
Does Encore have built-in canary traffic splitting?
No. Encore does not document percentage-based canary traffic shifting. It redeploys quickly into your AWS or GCP account with rolling updates behind health checks, provisions infrastructure from code, and gives you traces and logs so you can judge a release. Use CodeDeploy, a service mesh or Cloud Deploy if you need weighted canaries.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.
