Skip to content

CONCEPT Cited by 1 source

Percentage rollout

A percentage rollout serves a variation to X% of the requests that match a rule — so a flag can be ramped 5% → 10% → 50% → 100% of users over time while holding the architecture and the deploy constant.

The load-bearing property isn't "X% of requests randomly get the new behavior" — it's that a given caller identity stays in the same bucket across ramps. Flip-flopping the same user between variations on successive requests is worse than no rollout at all: it breaks sessions, caches, and the agent-observes-metrics-then-ramps loop.

Why consistent hashing is the mechanism

Percentage rollouts are implemented by hashing a stable context attribute (typically userId) to a bucket in [0, 100):

  • Include the caller in the rollout iff hash(userId) % 100 < X.
  • Use the same hash function and the same attribute at every ramp. Since the hash of a given userId never changes, raising X from 10 to 50 strictly grows the included set — no one who was in the rollout at 10% falls out at 50%.

Cloudflare Flagship states the property directly:

"Rollouts use consistent hashing on the specified context attribute. The same attribute value (userId, for example) always hashes to the same bucket, so they won't flip between variations across requests. You can ramp from 5% to 10% to 50% to 100% of users, so those who were already in the rollout stay in it." (Source: sources/2026-04-17-cloudflare-introducing-flagship-feature-flags-built-for-the-age-of-ai.)

See concepts/consistent-hashing for the underlying primitive.

Choice of bucketing attribute matters

The percentage rollout is a function of the chosen attribute:

  • userId → sticky per user; one user sees one variation for the lifetime of the ramp.
  • sessionId → sticky per session; same user can cross variations across sessions.
  • deviceId → sticky per device.
  • orgId / accountId → whole tenants move together (useful for B2B rollouts).

The attribute is not an implementation detail — it's the cohort definition.

Percentage rollout vs. gradual deployment

These are adjacent but distinct:

  • Gradual deployment (e.g. Cloudflare Workers gradual deployments) splits request traffic between different uploaded versions of the binary. The old and new code coexist as separate deployments.
  • Percentage rollout serves a variation within a single deployed version — the new code is already there, just gated by the flag.

Flagship names the distinction explicitly:

"Unlike gradual deployments, which split traffic between different uploaded versions of your Worker, feature flags let you roll out behavior by percentage within a single version that is serving 100% of traffic."

Ramp-safety guarantee

The monotonic bucket-growth invariant gives the rolling-forward operator (or AI agent; see concepts/agent-controlled-deployment) a one-way door:

  • Observe metrics at X%.
  • If green, raise to Y > X% — previously-included users stay included, new users join.
  • If red, lower to X' < X% — the last-admitted cohort is removed; the previously-stable cohort keeps the new behavior.

Without consistent hashing, lowering the percentage would scramble cohorts — and every ramp would be a partial re-roll.

Seen in

Last updated · 200 distilled / 1,178 read