As the lead for a high-traffic Cloudflare Workers API, how would you set the team's gradual deployment policy: starting percentage, promotion gates, rollback ownership and exceptions?
answer
- change the default from deploy
- 0% plus overrides, then a small step
- per-version signals gate promotion
- rollback is cheap, data is not
- some changes must skip the split
basics
~20 sMake uploads the default and releases a gated step: 0% with override smoke tests, then a small percentage held until per-version metrics are stable. Let on-call roll back freely, and ship Durable Object class and container changes alone with wrangler deploy.
solid answer
~40 sI would make production builds run `wrangler versions upload` (in Workers Builds, set the deploy command to `npx wrangler versions upload`) and promote in a gated step. Start at 0% and smoke-test with `Cloudflare-Workers-Version-Overrides`, then 1-10% depending on traffic, held until error rate and latency per version, attributed through the version metadata binding, are stable; then 50% and 100%. If users must see one version consistently, require a `Cloudflare-Workers-Version-Key`. On-call may run `wrangler rollback` at any time, which only works if every release keeps the previous version able to read current data. Exceptions: Durable Object class changes and container updates ship alone with `wrangler deploy`, triggers through `wrangler triggers deploy`, secrets through `wrangler versions secret put`.
go deeper
Know that a team can release a Worker in steps with wrangler versions deploy and undo a release quickly with wrangler rollback.
Describe the pipeline shape: upload on merge, a 0% smoke test, percentage steps, and per-version metrics from the version metadata binding.
Account for the platform's edges in the policy: stray wrangler deploy runs, secrets mid-rollout, triggers outside versions, and rollback being blocked or unsafe after data changes.
Weigh blast radius against release speed and ceremony, set thresholds for which Workers need gradual rollouts, give on-call rollback authority, and make backward-compatible data changes a standing rule.
## The decision A lead who owns a high-traffic API Worker has to turn Cloudflare's gradual deployment tooling into a **team rule**: how a release starts, what lets it move forward, who may stop it, and which changes take a different path. There is no single right policy; the right one depends on traffic volume, how much a bad release costs, and how much ceremony the team will tolerate. What follows are the levers and the trade-offs. ## Lever 1: make the default path upload, not deploy Out of the box, `wrangler deploy`, Workers Builds and the Script Upload API all **release to 100% immediately**. A gradual policy starts by changing that default: - In an external CI pipeline, the production job runs `wrangler versions upload --tag "$GIT_SHA"` and a separate, gated job runs `wrangler versions deploy`. - With Workers Builds, set the **deploy command** to `npx wrangler versions upload` so production-branch builds create versions without promoting them; promotion then happens from the dashboard or a pipeline. - Ban stray `wrangler deploy` runs against the Worker. During a split, Wrangler only warns, and a non-interactive job answers its prompt with yes, which sends the new upload to 100%. The cost: every release now needs a second action, which slows small fixes. Some teams keep one-step `wrangler deploy` for low-traffic internal Workers and require gradual rollouts only above a traffic or criticality threshold. ## Lever 2: the first percentage and the hold time Cloudflare imposes few constraints here: two versions, percentages that total 100, any split from 0 to 100. The choices are yours: 1. **0% plus overrides.** Deploying the new version at 0% and sending smoke tests with `Cloudflare-Workers-Version-Overrides` exercises it in production with no user traffic, on the real routes rather than a separate Version URL hostname. 2. **The first real step.** On a very high-traffic Worker, 1% may yield enough requests within minutes to compare error rates; on a quieter one, 5% or 10% for longer gives a meaningful sample. A smaller step limits blast radius; a larger step reaches statistical confidence faster. 3. **Per-request versus per-user.** Without `Cloudflare-Workers-Version-Key`, a 5% split hits 5% of requests, which means many users touch both versions. If cross-request consistency matters (hashed assets, multi-step flows), require a version key before a Worker may use gradual rollouts. ## Lever 3: promotion gates A step should move forward on evidence, not on a timer alone. The policy names the signals and where they come from: - The **version metadata binding** (`env.CF_VERSION_METADATA.id`) in logs, analytics events or a response header, so error rate, latency and CPU time can be compared per version. - The `ScriptVersion` field in Workers Logpush, for teams that ship logs elsewhere. - Who decides: an automated check against thresholds, a human approval, or both for high-risk changes. ## Lever 4: who owns rollback Rollback on Workers is **one command, applied immediately**: `wrangler rollback <version-id> --message "..."` returns a version to 100%, even from a split. That argues for letting the **on-call engineer roll back without approval**. The policy should also cover: - **Tokens.** CI uses `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from its secret store, scoped to the one account and zone. Decide whether on-call uses the same pipeline or a personal token with the same scope. - **Limits.** Only the 100 most recent versions are eligible, and a Durable Object class change, or a deleted KV namespace, R2 bucket or queue binding, blocks rollback past that point. - **Data.** Rollback does not revert D1, KV, R2 or Durable Object state, so the rule "every release keeps the previous version able to read current data" (expand-then-contract migrations) is what makes on-call rollback safe. ## Lever 5: the exceptions Some changes cannot or should not go through a gradual rollout, and the policy should list them: | Change | Path | |---|---| | Creating, deleting, renaming or transferring a Durable Object class | `wrangler deploy` on its own, separate from other code changes | | Container image updates | `wrangler deploy`, since `wrangler versions upload` does not update container images | | Routes, custom domains, cron schedules | `wrangler triggers deploy`, which is global and not versioned | | Secrets during a rollout | `wrangler versions secret put`, then release the new version | | Emergency fix | A documented fast path, for example 0% smoke test then straight to 100% | ## A defensible default For a high-traffic API Worker, a reasonable starting policy is: upload on merge, 0% smoke test with overrides, 5% held until per-version metrics are stable, then 50% and 100%; on-call may roll back at any time; Durable Object class changes and container updates ship alone with `wrangler deploy`; every schema change is expand-then-contract. Revisit the percentages after the first few incidents, because the right step size is whatever caught your last bad release early enough.
- When would you not require gradual deployments for a Worker at all?For low-traffic or internal Workers where a percentage split would not produce enough requests to compare versions, and where a bad release is cheap. One-step `wrangler deploy` plus fast `wrangler rollback` is simpler there. The cut-off is a traffic or criticality threshold the team writes down, not a per-release judgment.
- How do you stop the rollback-is-safe assumption from failing on a data change?Make backward-compatible data changes a review rule: expand-then-contract for D1 schemas, optional new fields in KV values and Durable Object storage, and destructive steps only after no deployable version reads the old shape. Changes that cannot meet it, such as Durable Object class lifecycle changes, ship alone and are flagged as one-way.
- Workers Builds releases gradually by default, so no pipeline change is needed.
- Rollback needs a change-approval board because it rebuilds and redeploys the old commit.
- Durable Object class deletions are safest rolled out at 5% first.
- A 5% split always means only 5% of users ever see the new version.
- Cron schedule changes roll out with the version's traffic percentage.