Gradual deployments with Durable Objects: reset behavior
A Durable Object will only be reset when it is assigned a different version. During a complete gradual deployment, each Durable Object will only be reset once.
Cloudflare Workers · all subjects
deployment
107 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
Durable Objects and Worker version skew during gradual deployments
When using gradual deployments, different versions of Durable Objects and their Workers will interact with each other. You must ensure that API changes between your Durable Object and its Worker are forwards and backwards compatible whether you are using gradual deployments or not. This requirement is even more critical with gradual deployments due to the likelihood of version skew.
Durable Object lifecycle changes are atomic and cannot be uploaded with other changes
Versions of Worker bundles that change Durable Object class lifecycle cannot be uploaded. This applies to both the declarative exports field and the legacy migrations array. Durable Object lifecycle changes are atomic operations because once a lifecycle change is deployed, rollbacks cannot take place to any version prior to the one that included the change.
Durable Object lifecycle changes deployment command
Durable Object lifecycle changes can be deployed with the command: wrangler deploy
Durable Object lifecycle changes should be deployed independently
To limit the blast radius of Durable Object lifecycle changes, they should be deployed independently of other code changes.
Worker code example for setting long-lived version affinity cookie
```ts export default { async fetch(request: Request, env: Env): Promise<Response> { const response = await handleRequest(request, env); // Set a long-lived cookie to use as a version affinity key. const COOKIE_NAME = "version-key"; // can be any name const cookieHeader = request.headers.get("Cookie") ?? ""; const hasAffinityCookie = new RegExp(`(?:^|;\\s*)${COOKIE_NAME}=`).test(cookieHeader); if (!hasAffinityCookie) { const id = crypto.randomUUID(); response.headers.append( "Set-Cookie", `${COOKIE_NAME}=${id}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=31536000`, ); } return response; }, }; ``` Then create a Transform Rule to use this cookie as the version key with Expression Editor condition `http.cookie contains "version-key"`, operation _Set dynamic_, Header name `Cloudflare-Workers-Version-Key`, Value `http.request.cookies["version-key"][0]`. On the very first request from a new user, no cookie exists yet, so the request will be randomly assigned to a version based on the configured percentages.
Transform Rules not available for *.workers.dev domains
Transform Rules require your Worker to be on a route on a zone you control. They are not available for Workers served on `*.workers.dev` domains. For `*.workers.dev`, you would need to set the header from the client or from an upstream Worker using a service binding.
Version affinity prevents version skew during gradual deployments
Version affinity deterministically assigns users to a specific Worker version based on a stable identifier, so they consistently hit the same version across page loads and subrequests for the duration of the gradual deployment. Without version affinity, each request has a random chance of routing to either version based on specified percentages, which can cause version skew issues where users receive content from different versions.
Set Cloudflare-Workers-Version-Key header for version affinity
To enable version affinity, set the `Cloudflare-Workers-Version-Key` header on the incoming request to your Worker. All requests with the same version key value will be handled by the same version of your Worker. The platform hashes the key and uses the result with configured percentages to deterministically assign a version.
Version affinity works with service bindings
The `Cloudflare-Workers-Version-Key` header can be set both when making an external request from the Internet to your Worker, as well as when making a subrequest from one Worker to another Worker using a service binding.
Version affinity persistence as gradual deployment progresses
As you progress a gradual deployment (for example, from 10% to 20% to 50%), users whose keys were already assigned to the new version will remain on it. Users on the old version will progressively move to the new version as the percentage increases, but will not flip back unless you roll back.
Version affinity critical for static assets with content-hashed filenames
Version affinity is particularly important when your Worker serves static assets with content-hashed filenames (like `index-a1b2c3d4.js`), which is the default behavior of most modern build tools and frameworks. During a gradual rollout, different versions have different asset filenames. Without version affinity, a user can receive HTML from version A but when the browser requests an asset, that request may route to version B which does not have that file, resulting in a 404 error and broken page.
Version key from authenticated user identifier
For authenticated applications with a user identifier in a cookie or header, use that identifier as the version key. Each user is deterministically assigned to a version and stays there across sessions, devices, and reloads. Use a Transform Rule with Expression Editor condition `http.cookie contains "user_id"`, operation _Set dynamic_, Header name `Cloudflare-Workers-Version-Key`, Value `http.request.cookies["user_id"][0]`.
Version key from session cookie
For applications with sessions, use the session identifier as the version key. This gives consistent routing for the duration of the session. If the session expires and a new one is created, the user may be assigned to a different version. Use a Transform Rule with Expression Editor condition `http.cookie contains "session_id"`, operation _Set dynamic_, Header name `Cloudflare-Workers-Version-Key`, Value `http.request.cookies["session_id"][0]`.
Version key from client IP address
For anonymous or cookieless applications, use the client IP address as the version key. This is the simplest approach requiring no application changes. Users behind the same NAT or VPN will be grouped together, and mobile users who switch networks may change version, but this significantly reduces version flip-flopping compared to random per-request routing. Use a Transform Rule with Expression Editor condition `true`, operation _Set dynamic_, Header name `Cloudflare-Workers-Version-Key`, Value `ip.src`.
Version key from long-lived cookie set by Worker
For anonymous users without any stable identifier in the request, set a long-lived cookie from your Worker on the first request. On first request (randomly assigned), generate a stable identifier and set it as a cookie with `Set-Cookie: version-key={id}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=31536000`. All subsequent requests use that cookie as the version key, providing the best consistency for anonymous users at the cost of a small amount of application code.
Decoupling versions and deployments
You can decouple version creation and deployment so that uploading a version and deploying it are independent actions. This gives you control over when new code goes live and lets you use strategies like gradual deployments or manual promotion.
View versions and deployments in Cloudflare dashboard
To view versions and deployments in the Cloudflare dashboard, go to the Workers & Pages page, select your Worker, and then select Deployments.
What a version captures
A version captures the complete state of your Worker at a point in time, including its bundled code, static assets, bindings, and compatibility settings. Each version has a unique ID and tracks who created it, when, and from where. You can optionally attach a message and tag to a version when you upload it.
Storage resources not tracked with versions
State changes for associated storage resources such as KV, R2, Durable Objects, and D1 are not tracked with versions.
What a deployment determines
A deployment determines which version(s) of your Worker are actively serving traffic. A deployment can reference one version serving 100% of traffic, or two versions with traffic split between them during a gradual deployment. Each deployment tracks who created it, when, and which version(s) it includes.
Default wrangler deploy behavior
By default, when you run 'wrangler deploy', Workers creates a new version and immediately deploys it to 100% of traffic in a single step. This couples version creation and deployment together.
Wrangler view versions and deployments
Wrangler allows you to view the 100 most recent versions and deployments using the 'versions list' and 'deployments list' commands.
Wrangler rollback command
To roll back to a specified version of your Worker via Wrangler, use the wrangler rollback command.
Rollback from split deployment
When rolling back from a split deployment with two versions, the rollback replaces both versions with the selected version at 100% traffic, converting the split deployment to a single-version deployment.
Rollback creates new deployment
Rolling back to a previous version of your Worker immediately creates a new deployment with the version specified and becomes the active deployment across all your deployed routes and domains.
Rollback from single-version deployment
When rolling back from a single-version deployment, the current version is replaced with the selected version.
Dashboard rollback procedure
To roll back via the Cloudflare dashboard: navigate to Workers & Pages, select your Worker, go to Deployments, select the three dot icon on the right of the version you want to roll back to, and select Rollback.
Rollback interactive mode version selection
When using Wrangler in interactive mode, you can select from up to 100 recent versions. To roll back to a specific version not in the interactive list, you can specify the version ID directly on the command line.
When new Worker versions are created
New versions of a Worker are created when you run `wrangler deploy`, `wrangler versions upload`, or when you make edits via the Cloudflare dashboard. A unique static version preview URL is generated automatically for each new version.
Aliased Preview URLs minimum Wrangler version
Aliased Preview URLs require Wrangler version 4.21.0 or higher. Check your version by running `wrangler --version`.
Create aliased preview URLs with wrangler versions upload
Aliases are created during `wrangler versions upload` by providing the `--preview-alias` flag with a valid alias name. Example: `wrangler versions upload --preview-alias staging`. The resulting alias is immediately available at: `staging-<WORKER_NAME>.<SUBDOMAIN>.workers.dev`
Aliased Preview URLs rules and limitations
Aliases must follow these rules: (1) May only be created during version upload. (2) Must use only lowercase letters, numbers, and dashes. (3) Must begin with a lowercase letter. (4) The alias and Worker name combined (with a dash) must not exceed 63 characters due to DNS label limits. (5) Only the 1000 most recently deployed aliases are retained; when a new alias is created beyond this limit, the least recently deployed alias is deleted.
Preview URLs default enablement status
Preview URLs are enabled by default when `workers_dev` is enabled. Preview URLs are disabled by default when `workers_dev` is disabled.
Disabling Preview URLs in dashboard overrides wrangler config
If you enable or disable Preview URLs in the Cloudflare dashboard, but do not update your Worker's Wrangler file accordingly, the Preview URLs status will change the next time you deploy your Worker with Wrangler. The Wrangler configuration takes precedence on the next deployment.
Preview URLs for zone-level features testing
When testing zone-level performance or security features for a version, use version overrides so that your zone's performance and security settings apply instead of using Preview URLs.
Preview URLs use cases
Preview URLs can be integrated into CI/CD pipelines for automatic preview environment generation for every pull request. They are useful for collaboration between teams to test code changes in a live environment and verify updates. They can be used to test new API endpoints, validate data formats, and ensure backward compatibility with existing services.
Preview URLs overview and types
Preview URLs allow you to preview new versions of a Worker without deploying to production. There are two types: Versioned Preview URLs (unique URL generated automatically for each new version) and Aliased Preview URLs (static, human-readable alias manually assigned to a version). Both follow the format: <VERSION_PREFIX OR ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev. Preview URLs are only available for Worker versions uploaded after 2024-09-25.
Versioned Preview URLs minimum Wrangler version
Versioned Preview URLs require Wrangler version 3.74.0 or higher. Check your version by running `wrangler --version`. Update Wrangler to use this feature.
Version override must be in current deployment
A version override will only be applied if the specified version is in the current deployment. The versions in the current deployment can be found using the `wrangler deployments list` command or on the Workers & Pages page in the Cloudflare dashboard by selecting your Worker > Deployments > Active Deployment.
Version override not applied fallback
If a request's version override is not applied, the request will be routed according to the percentages set in the gradual deployment configuration. This can occur if the deployment does not contain the specified version or if the header value is not a valid Dictionary.
Smoke test deployment pattern
To smoke test a new version before gradual deployment: Create a new deployment with `wrangler versions deploy` and specify 0% for the new version while keeping the previous version at 100%. Then test the new version with a version override before gradually progressing the new version to 100%.
Input vs output wrangler configuration with Vite
When using the Cloudflare Vite plugin, the wrangler configuration file you provide (wrangler.jsonc, wrangler.json, or wrangler.toml) is the input file. Running vite build creates a separate output wrangler.json file that is a snapshot of the configuration at build time, modified to reference build artifacts. The output wrangler.json is used for preview and deployment.
Npm run build output structure with Vite plugin
Running npm run build with the Cloudflare Vite plugin creates a dist directory containing two subdirectories: client (containing browser code) and a directory named after the project (containing Worker code and the output wrangler.json configuration).
Deploy with npm exec wrangler deploy
Run npm exec wrangler deploy to deploy the application to Cloudflare. This command automatically uses the output wrangler.json from the build output.
Deploy Worker with npm run deploy
Deploy your application to Cloudflare Workers with 'npm run deploy'. After successful deployment, Wrangler outputs your Worker's URL in the format https://<your-subdomain>.workers.dev and displays the Current Version ID.
Deploy schema to production database before deployment
Before deploying your Worker to production, execute your schema against the remote database with 'npx wrangler d1 execute <database-name> --remote --file=./schemas/schema.sql' to ensure the production database has the correct schema.