diff --git a/.nimbus/routes.json b/.nimbus/routes.json index 6cf1d73a94e..87fc7edcceb 100644 --- a/.nimbus/routes.json +++ b/.nimbus/routes.json @@ -7963,7 +7963,6 @@ "/workers/configuration/integrations/external-services", "/workers/configuration/multipart-upload-metadata", "/workers/configuration/placement", - "/workers/configuration/previews", "/workers/configuration/routing", "/workers/configuration/routing/custom-domains", "/workers/configuration/routing/routes", @@ -7974,10 +7973,6 @@ "/workers/configuration/sites/start-from-existing", "/workers/configuration/sites/start-from-scratch", "/workers/configuration/sites/start-from-worker", - "/workers/configuration/versions-and-deployments", - "/workers/configuration/versions-and-deployments/gradual-deployments", - "/workers/configuration/versions-and-deployments/rollbacks", - "/workers/configuration/versions-and-deployments/version-overrides", "/workers/configuration/workers-with-page-rules", "/workers/databases", "/workers/databases/analytics-engine", @@ -8319,6 +8314,14 @@ "/workers/tutorials/upload-assets-with-r2", "/workers/tutorials/using-prisma-postgres-with-workers", "/workers/tutorials/workers-kv-from-rust", + "/workers/versions-and-deployments", + "/workers/versions-and-deployments/deployment-management", + "/workers/versions-and-deployments/gradual-deployments", + "/workers/versions-and-deployments/gradual-deployments/version-affinity", + "/workers/versions-and-deployments/gradual-deployments/with-durable-objects", + "/workers/versions-and-deployments/preview-urls", + "/workers/versions-and-deployments/rollbacks", + "/workers/versions-and-deployments/version-overrides", "/workers/vite-plugin", "/workers/vite-plugin/get-started", "/workers/vite-plugin/reference", diff --git a/public/__redirects b/public/__redirects index dfdbcbb3ba5..5af3bb29083 100644 --- a/public/__redirects +++ b/public/__redirects @@ -2259,7 +2259,7 @@ /workers/platform/sites/configuration/ /workers/configuration/sites/configuration/ 301 /workers/platform/deploy-button/ /workers/platform/deploy-buttons/ 301 /workers/configuration/deploy-button/ /workers/platform/deploy-buttons/ 301 -/workers/platform/deployments/ /workers/configuration/versions-and-deployments/ 301 +/workers/platform/deployments/ /workers/versions-and-deployments/ 301 /workers/platform/environment-variables/ /workers/configuration/environment-variables/ 301 /workers/platform/smart-placement/ /workers/configuration/placement/ 301 /workers/configuration/smart-placement/ /workers/configuration/placement/ 301 @@ -2280,7 +2280,13 @@ /workers/runtime-apis/service-bindings/ /workers/runtime-apis/bindings/service-bindings/ 301 /workers/observability/local-development-and-testing/ /workers/local-development/ 301 /workers/observability/sentry-integration/ /workers/observability/integrations/sentry 301 -/workers/configuration/deployments/ /workers/configuration/versions-and-deployments/ 301 +/workers/configuration/deployments/ /workers/versions-and-deployments/ 301 +/workers/configuration/previews/ /workers/versions-and-deployments/preview-urls/ 301 +/workers/configuration/versions-and-deployments/ /workers/versions-and-deployments/ 301 +/workers/configuration/versions-and-deployments/gradual-deployments/ /workers/versions-and-deployments/gradual-deployments/ 301 +/workers/configuration/versions-and-deployments/version-overrides/ /workers/versions-and-deployments/version-overrides/ 301 +/workers/configuration/versions-and-deployments/rollbacks/ /workers/versions-and-deployments/rollbacks/ 301 +/workers/static-assets/routing/advanced/gradual-rollouts/ /workers/versions-and-deployments/gradual-deployments/version-affinity/ 301 /workers/configuration/continuous-integration/ /workers/ci-cd/ 301 /workers/wrangler/ci-cd/ /workers/ci-cd/external-cicd/ 301 /workers/tutorials/hello-world-rust/ /workers/tutorials/ 301 diff --git a/src/content/changelog/workers/2025-02-03-workers-metrics-revamp.mdx b/src/content/changelog/workers/2025-02-03-workers-metrics-revamp.mdx index 9f01cc36ae3..dc8f702ab7a 100644 --- a/src/content/changelog/workers/2025-02-03-workers-metrics-revamp.mdx +++ b/src/content/changelog/workers/2025-02-03-workers-metrics-revamp.mdx @@ -10,7 +10,7 @@ We've revamped the [Workers Metrics dashboard](https://dash.cloudflare.com/?to=/ ![Workers Metrics dashboard](~/assets/images/workers/observability/workers-metrics.png) -Now you can easily compare metrics across Worker versions, understand the current state of a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/), and review key Workers metrics in a single view. This new interface enables you to: +Now you can easily compare metrics across Worker versions, understand the current state of a [gradual deployment](/workers/versions-and-deployments/gradual-deployments/), and review key Workers metrics in a single view. This new interface enables you to: - Drag-and-select using a graphical timepicker for precise metric selection. diff --git a/src/content/changelog/workers/2025-04-08-deploy-to-cloudflare-button.mdx b/src/content/changelog/workers/2025-04-08-deploy-to-cloudflare-button.mdx index d24d77883df..b181a32cdbb 100644 --- a/src/content/changelog/workers/2025-04-08-deploy-to-cloudflare-button.mdx +++ b/src/content/changelog/workers/2025-04-08-deploy-to-cloudflare-button.mdx @@ -14,7 +14,7 @@ The Deploy to Cloudflare button: 1. **Creates a new Git repository on your GitHub/ GitLab account**: Cloudflare will automatically clone and create a new repository on your account, so you can continue developing. 2. **Automatically provisions resources the app needs**: If your repository requires Cloudflare primitives like a [Workers KV namespace](/kv/), a [D1 database](/d1/), or an [R2 bucket](/r2/), Cloudflare will automatically provision them on your account and bind them to your Worker upon deployment. 3. **Configures Workers Builds (CI/CD)**: Every new push to your production branch on your newly created repository will automatically build and deploy courtesy of [Workers Builds](/workers/ci-cd/builds/). -4. **Adds preview URLs to each pull request**: If you'd like to test your changes before deploying, you can push changes to a [non-production branch](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds) and [preview URLs](/workers/configuration/previews/) will be generated and [posted back to GitHub as a comment](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment). +4. **Adds preview URLs to each pull request**: If you'd like to test your changes before deploying, you can push changes to a [non-production branch](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds) and [preview URLs](/workers/versions-and-deployments/preview-urls/) will be generated and [posted back to GitHub as a comment](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment). ![Import repo or choose template](~/assets/images/workers/dtw-user-flow.png) diff --git a/src/content/changelog/workers/2025-08-08-support-long-branch-names-preview-aliases.mdx b/src/content/changelog/workers/2025-08-08-support-long-branch-names-preview-aliases.mdx index 4b869cc6a72..5a2300e5af0 100644 --- a/src/content/changelog/workers/2025-08-08-support-long-branch-names-preview-aliases.mdx +++ b/src/content/changelog/workers/2025-08-08-support-long-branch-names-preview-aliases.mdx @@ -6,7 +6,7 @@ tags: date: 2025-08-14T01:00:00Z --- -We've updated [preview URLs](/workers/configuration/previews/) for Cloudflare Workers to support long branch names. +We've updated [preview URLs](/workers/versions-and-deployments/preview-urls/) for Cloudflare Workers to support long branch names. Previously, branch and Worker names exceeding the 63-character DNS limit would cause alias generation to fail, leaving pull requests without aliased preview URLs. This particularly impacted teams relying on descriptive branch naming. @@ -22,4 +22,4 @@ Now, Cloudflare automatically truncates long branch names and appends a unique h ## Requirements and compatibility - **Wrangler 4.30.0 or later**: This feature requires updating to wrangler@4.30.0+ -- **No configuration needed**: Works automatically with existing preview URL setups \ No newline at end of file +- **No configuration needed**: Works automatically with existing preview URL setups diff --git a/src/content/changelog/workers/2025-09-03-new-workers-api.mdx b/src/content/changelog/workers/2025-09-03-new-workers-api.mdx index d5f72b78d50..45be5a17a64 100644 --- a/src/content/changelog/workers/2025-09-03-new-workers-api.mdx +++ b/src/content/changelog/workers/2025-09-03-new-workers-api.mdx @@ -189,7 +189,7 @@ This dual approach means: ## Learn more - [Infrastructure as Code (IaC) guide](/workers/platform/infrastructure-as-code) - [API documentation](/api/resources/workers/subresources/beta/) -- [Versions and Deployments overview](/workers/configuration/versions-and-deployments/) +- [Versions and Deployments overview](/workers/versions-and-deployments/) ## Technical notes diff --git a/src/content/changelog/workers/2025-09-11-increased-version-rollback-limit.mdx b/src/content/changelog/workers/2025-09-11-increased-version-rollback-limit.mdx index ad92d184dcd..ef36c00e9b7 100644 --- a/src/content/changelog/workers/2025-09-11-increased-version-rollback-limit.mdx +++ b/src/content/changelog/workers/2025-09-11-increased-version-rollback-limit.mdx @@ -11,8 +11,8 @@ This allows you to: * Promote any of the 100 most recent versions to be the active deployment. -* Split traffic using [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) between your latest code and any of the 100 most recent versions. +* Split traffic using [gradual deployments](/workers/versions-and-deployments/gradual-deployments/) between your latest code and any of the 100 most recent versions. You can do this through the Cloudflare dashboard or with [Wrangler's rollback command](/workers/wrangler/commands/general/#rollback) -Learn more about [versioned deployments](/workers/configuration/versions-and-deployments/) and [rollbacks](/workers/configuration/versions-and-deployments/rollbacks/). +Learn more about [versioned deployments](/workers/versions-and-deployments/) and [rollbacks](/workers/versions-and-deployments/rollbacks/). \ No newline at end of file diff --git a/src/content/changelog/workers/2025-09-17-update-preview-url-setting.mdx b/src/content/changelog/workers/2025-09-17-update-preview-url-setting.mdx index b43c774dfed..9fe282634c4 100644 --- a/src/content/changelog/workers/2025-09-17-update-preview-url-setting.mdx +++ b/src/content/changelog/workers/2025-09-17-update-preview-url-setting.mdx @@ -5,7 +5,7 @@ date: 2025-09-17 --- import { WranglerConfig, Aside } from "~/components"; -To prevent the accidental exposure of applications, we've updated how [Worker preview URLs](/workers/configuration/previews/) (`-..workers.dev`) are handled. We made this change to ensure preview URLs are only active when intentionally configured, improving the default security posture of your Workers. +To prevent the accidental exposure of applications, we've updated how [Worker preview URLs](/workers/versions-and-deployments/preview-urls/) (`-..workers.dev`) are handled. We made this change to ensure preview URLs are only active when intentionally configured, improving the default security posture of your Workers. ## One-Time Update for Workers with workers.dev Disabled We performed a one-time update to disable preview URLs for existing Workers where the [workers.dev subdomain](/workers/configuration/routing/workers-dev/) was also disabled. @@ -16,7 +16,7 @@ If your Worker was affected, its preview URL (`-.Storage API provides access to a Durable Object's attached storage. -A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/configuration/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects. +A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects. ## Access storage diff --git a/src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx b/src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx index 10bdd29451b..3f26619bf43 100644 --- a/src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx +++ b/src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx @@ -86,7 +86,7 @@ A Durable Object incurs charges only when it is **actively running in-memory**, Durable Objects will occasionally shut down and objects are restarted, which will run your Durable Object class constructor. This can happen for various reasons, including: -- New Worker [deployments](/workers/configuration/versions-and-deployments/) with code updates +- New Worker [deployments](/workers/versions-and-deployments/) with code updates - Lack of requests to an object following the state transitions documented above - Cloudflare updates to the Workers runtime system - Workers runtime decisions on where to host objects diff --git a/src/content/docs/durable-objects/platform/known-issues.mdx b/src/content/docs/durable-objects/platform/known-issues.mdx index a590711f8bc..8023941f453 100644 --- a/src/content/docs/durable-objects/platform/known-issues.mdx +++ b/src/content/docs/durable-objects/platform/known-issues.mdx @@ -22,7 +22,7 @@ A Durable Object may be replaced in the event of a network partition or a softwa ## Code updates -Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. Because each Durable Object is globally unique, the situation can arise that a request arrives to the latest version of your Worker (running in one part of the world), which then calls to a unique Durable Object running the previous version of your code for a short period of time (typically seconds to minutes). If you create a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/), this period of time is determined by how long your live deployment is configured to use more than one version. +Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. Because each Durable Object is globally unique, the situation can arise that a request arrives to the latest version of your Worker (running in one part of the world), which then calls to a unique Durable Object running the previous version of your code for a short period of time (typically seconds to minutes). If you create a [gradual deployment](/workers/versions-and-deployments/gradual-deployments/), this period of time is determined by how long your live deployment is configured to use more than one version. For this reason, it is best practice to ensure that API changes between your Workers and Durable Objects are forward and backward compatible across code updates. diff --git a/src/content/docs/durable-objects/reference/durable-object-gradual-deployments.mdx b/src/content/docs/durable-objects/reference/durable-object-gradual-deployments.mdx index eee8b1dbeec..e2bb1684310 100644 --- a/src/content/docs/durable-objects/reference/durable-object-gradual-deployments.mdx +++ b/src/content/docs/durable-objects/reference/durable-object-gradual-deployments.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: navigation title: Gradual Deployments -external_link: /workers/configuration/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects +external_link: /workers/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects sidebar: order: 10 head: [] diff --git a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx index 40c2b41128c..86281d5b904 100644 --- a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx +++ b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx @@ -410,5 +410,5 @@ Note that `.toml` files do not allow line breaks in inline tables (the `{key = " You cannot enable a SQLite storage backend on an existing, deployed Durable Object class, so setting `new_sqlite_classes` on later migrations will fail with an error. Automatic migration of deployed classes from their key-value storage backend to SQLite storage backend will be available in the future. :::caution[Important] -Durable Object migrations are atomic operations and cannot be gradually deployed. To provide early feedback to developers, new Worker versions with new migrations cannot be uploaded. Refer to [Gradual deployments for Durable Objects](/workers/configuration/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects) for more information. +Durable Object migrations are atomic operations and cannot be gradually deployed. To provide early feedback to developers, new Worker versions with new migrations cannot be uploaded. Refer to [Gradual deployments for Durable Objects](/workers/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects) for more information. ::: diff --git a/src/content/docs/hyperdrive/configuration/rotate-credentials.mdx b/src/content/docs/hyperdrive/configuration/rotate-credentials.mdx index 01a153c687d..c9827645f3d 100644 --- a/src/content/docs/hyperdrive/configuration/rotate-credentials.mdx +++ b/src/content/docs/hyperdrive/configuration/rotate-credentials.mdx @@ -48,7 +48,7 @@ The command above will output the ID of your Hyperdrive. Set this ID in the [Wra -To update your Worker to use the new Hyperdrive configuration, redeploy your Worker or use [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/). +To update your Worker to use the new Hyperdrive configuration, redeploy your Worker or use [gradual deployments](/workers/versions-and-deployments/gradual-deployments/). ## Update the existing Hyperdrive configuration diff --git a/src/content/docs/kv/examples/routing-with-workers-kv.mdx b/src/content/docs/kv/examples/routing-with-workers-kv.mdx index 3ec2681d97b..bd9903e81c6 100644 --- a/src/content/docs/kv/examples/routing-with-workers-kv.mdx +++ b/src/content/docs/kv/examples/routing-with-workers-kv.mdx @@ -21,7 +21,7 @@ In single-tenant applications, this can be used to route requests to various ori In multi-tenant applications, requests can be routed to the tenant's respective origin resources (for example, requests to `tenantA.your-worker-hostname.com` routed to server for Tenant A, `tenantB.your-worker-hostname.com` routed to server for Tenant B). Routing can also be used to implement [A/B testing](/reference-architecture/diagrams/serverless/a-b-testing-using-workers/), canary deployments, or [blue-green deployments](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment) for your own external applications. -If you are looking to implement canary or blue-green deployments of applications built fully on Cloudflare Workers, see [Workers gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/). +If you are looking to implement canary or blue-green deployments of applications built fully on Cloudflare Workers, see [Workers gradual deployments](/workers/versions-and-deployments/gradual-deployments/). ## Route requests with Workers KV diff --git a/src/content/docs/rules/snippets/when-to-use.mdx b/src/content/docs/rules/snippets/when-to-use.mdx index e86e4a0e074..50415c4a546 100644 --- a/src/content/docs/rules/snippets/when-to-use.mdx +++ b/src/content/docs/rules/snippets/when-to-use.mdx @@ -86,14 +86,14 @@ Snippets are ideal for fast, cost-free request and response modifications at the | Route traffic dynamically between [origin servers](/rules/snippets/examples/serve-different-origin/) | ✅ | ✅ | | [Authenticate](/rules/snippets/examples/auth-with-headers/) requests, [pre-sign](/cache/interaction-cloudflare-products/waf-snippets/) URLs, run [A/B testing](/rules/snippets/examples/ab-testing-same-url/) | ✅ | ✅ | | Define logic using [JavaScript and Web APIs](/workers/languages/javascript/) | ✅ | ✅ | -| Perform compute-heavy tasks (for example, [AI](/workers-ai/), [image transformations](/images/optimization/transformations/transform-via-workers/)) | ❌ | ✅ | +| Perform compute-heavy tasks (for example, [AI](/workers-ai/), [image transformations](/images/optimization/transformations/transform-via-workers/)) | ❌ | ✅ | | Store persistent data (for example, [KV](/kv/), [Durable Objects](/durable-objects/), and [D1](/d1/)) | ❌ | ✅ | | Build [APIs](/d1/tutorials/build-a-comments-api/) and [full-stack applications](/pages/framework-guides/deploy-an-astro-site/#video-tutorial) | ❌ | ✅ | | Use TypeScript, Python, Rust, or other programming [languages](/workers/languages/) | ❌ | ✅ | | Support non-HTTP [protocols](/workers/reference/protocols/) | ❌ | ✅ | | Analyze execution [logs](/workers/observability/logs/workers-logs/) and track performance metrics | ❌ | ✅ | | Deploy via [command-line interface (CLI)](/workers/wrangler/) | ❌ | ✅ | -| Roll out gradually, roll back to previous [versions](/workers/configuration/versions-and-deployments/) | ❌ | ✅ | +| Roll out gradually, roll back to previous [versions](/workers/versions-and-deployments/) | ❌ | ✅ | | Optimize execution with [Smart Placement](/workers/configuration/placement/) | ❌ | ✅ | --- diff --git a/src/content/docs/workers/ci-cd/builds/build-branches.mdx b/src/content/docs/workers/ci-cd/builds/build-branches.mdx index 40b19ae9d75..db9163a1ff3 100644 --- a/src/content/docs/workers/ci-cd/builds/build-branches.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-branches.mdx @@ -8,7 +8,7 @@ products: - workers --- -When you connect a git repository to Workers, commits made on the production git branch will produce a Workers Build. If you want to take advantage of [preview URLs](/workers/configuration/previews/) and [pull request comments](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment), you can additionally enable "non-production branch builds" in order to trigger a build on all branches of your repository. +When you connect a git repository to Workers, commits made on the production git branch will produce a Workers Build. If you want to take advantage of [preview URLs](/workers/versions-and-deployments/preview-urls/) and [pull request comments](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment), you can additionally enable "non-production branch builds" in order to trigger a build on all branches of your repository. ## Change production branch diff --git a/src/content/docs/workers/ci-cd/builds/configuration.mdx b/src/content/docs/workers/ci-cd/builds/configuration.mdx index 032d023592e..8a71b43994d 100644 --- a/src/content/docs/workers/ci-cd/builds/configuration.mdx +++ b/src/content/docs/workers/ci-cd/builds/configuration.mdx @@ -62,7 +62,7 @@ Examples of other deploy commands you can set include: The non-production branch deploy command is only applicable when you have enabled [non-production branch builds](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds). -It defaults to `npx wrangler versions upload`, producing a [preview URL](/workers/configuration/previews/). Like the build and deploy commands, it can be customized to instead run anything. +It defaults to `npx wrangler versions upload`, producing a [preview URL](/workers/versions-and-deployments/preview-urls/). Like the build and deploy commands, it can be customized to instead run anything. Examples of other non-production branch deploy commands you can set include: @@ -128,4 +128,4 @@ The following system environment variables are injected by default (but can be o | `WORKERS_CI` | `1` | Changing build behaviour when run on Workers Builds versus locally | | `WORKERS_CI_BUILD_UUID` | `` | Passing the Build UUID along to custom workflows | | `WORKERS_CI_COMMIT_SHA` | `` | Passing current commit ID to error reporting, for example, Sentry | -| `WORKERS_CI_BRANCH` | ` - Annotations object specific to the Worker version. diff --git a/src/content/docs/workers/configuration/routing/workers-dev.mdx b/src/content/docs/workers/configuration/routing/workers-dev.mdx index 732cc8fa3a3..9d29731c532 100644 --- a/src/content/docs/workers/configuration/routing/workers-dev.mdx +++ b/src/content/docs/workers/configuration/routing/workers-dev.mdx @@ -26,7 +26,7 @@ All Workers are assigned a `workers.dev` route when they are created or renamed ## Manage access to `workers.dev` -When enabled, your `workers.dev` URL is available publicly. You can use [Cloudflare Access](/cloudflare-one/access-controls/policies/) to require visitors to authenticate before accessing preview URLs. You can limit access to yourself, your teammates, your organization, or anyone else you specify in your [access policy](/cloudflare-one/access-controls/policies/). +When enabled, your `workers.dev` URL is available publicly. You can use [Cloudflare Access](/cloudflare-one/access-controls/policies/) to require visitors to authenticate before accessing your `workers.dev` URL. You can limit access to yourself, your teammates, your organization, or anyone else you specify in your [access policy](/cloudflare-one/access-controls/policies/). To limit your `workers.dev` URL to authorized emails only: @@ -69,7 +69,7 @@ To disable the `workers.dev` route for a Worker, include the following in your W -When you redeploy your Worker with this change, the `workers.dev` route will be disabled. Disabling your `workers.dev` route does not disable Preview URLs. Learn how to [disable Preview URLs](/workers/configuration/previews/#disabling-preview-urls). +When you redeploy your Worker with this change, the `workers.dev` route will be disabled. Preview URLs default to matching your `workers_dev` setting unless explicitly configured. If you explicitly enabled Preview URLs, [disable them separately](/workers/versions-and-deployments/preview-urls/#toggle-preview-urls-enable-or-disable). If you do not specify `workers_dev = false` but add a [`routes` component](/workers/wrangler/configuration/#routes) to your [Wrangler configuration file](/workers/wrangler/configuration/), the value of `workers_dev` will be inferred as `false` on the next deploy. diff --git a/src/content/docs/workers/configuration/secrets.mdx b/src/content/docs/workers/configuration/secrets.mdx index 29a365578d1..f1d65bf1f96 100644 --- a/src/content/docs/workers/configuration/secrets.mdx +++ b/src/content/docs/workers/configuration/secrets.mdx @@ -91,7 +91,7 @@ Secrets can be added through [`wrangler secret put`](/workers/wrangler/commands/ npx wrangler secret put ``` -If using [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret put` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy). +If using [gradual deployments](/workers/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret put` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy). :::note Wrangler versions before 3.73.0 require you to specify a `--x-versions` flag. @@ -141,7 +141,7 @@ Secrets can be deleted through [`wrangler secret delete`](/workers/wrangler/comm npx wrangler secret delete ``` -If using [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret delete` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy). +If using [gradual deployments](/workers/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret delete` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy). ```sh npx wrangler versions secret delete diff --git a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx b/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx deleted file mode 100644 index be238b33fa0..00000000000 --- a/src/content/docs/workers/configuration/versions-and-deployments/gradual-deployments.mdx +++ /dev/null @@ -1,246 +0,0 @@ ---- -pcx_content_type: configuration -title: Gradual deployments -head: [] -description: Incrementally deploy code changes to your Workers with gradual deployments. -products: - - workers -sidebar: - order: 2 ---- - -import { Example, DashButton, PackageManagers } from "~/components"; - -Gradual Deployments give you the ability to incrementally deploy new [versions](/workers/configuration/versions-and-deployments/#versions) of Workers by splitting traffic across versions. - -![Gradual Deployments](~/assets/images/workers/platform/versions-and-deployments/gradual-deployments.png) - -Using gradual deployments, you can: - -- Gradually shift traffic to a newer version of your Worker. -- Monitor error rates and exceptions across versions using [analytics and logs](/workers/configuration/versions-and-deployments/gradual-deployments/#observability) tooling. -- [Roll back](/workers/configuration/versions-and-deployments/rollbacks/) to a previously stable version if you notice issues when deploying a new version. - -## Use gradual deployments - -The following section guides you through an example usage of gradual deployments. You will choose to use either [Wrangler](/workers/configuration/versions-and-deployments/gradual-deployments/#via-wrangler) or the Cloudflare dashboard to: - -- Create a new Worker. -- Publish a new version of that Worker without deploying it. -- Create a gradual deployment between the two versions. -- Progress the deployment of the new version to 100% of traffic. - -### Via Wrangler - -:::note - -Minimum required Wrangler version: 3.40.0. Versions before 3.73.0 require you to specify a `--x-versions` flag. - -::: - -#### 1. Create and deploy a new Worker - -Create a new `"Hello World"` Worker using the [`create-cloudflare` CLI (C3)](/pages/get-started/c3/) and deploy it. - - - -Answer `yes` or `no` to using TypeScript. Answer `yes` to deploying your application. This is the first version of your Worker. - -#### 2. Create a new version of the Worker - -To create a new version of the Worker, edit the Worker code by changing the `Response` content to your desired text and upload the Worker by using the [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload) command. - - - -This will create a new version of the Worker that is not automatically deployed. - -#### 3. Create a new deployment - -Use the [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy) command to -create a new deployment that splits traffic between two versions of the Worker. Follow the interactive prompts to create a deployment with the versions uploaded in [step #1](/workers/configuration/versions-and-deployments/gradual-deployments/#1-create-and-deploy-a-new-worker) and [step #2](/workers/configuration/versions-and-deployments/gradual-deployments/#2-create-a-new-version-of-the-worker). Select your desired percentages for each version. - - - -#### 4. Test the split deployment - -Run a cURL command on your Worker to test the split deployment. - -```bash -for j in {0..10} -do - curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev -done -``` - -You should see 10 responses. Responses will reflect the content returned by the versions in your deployment. Responses will vary depending on the percentages configured in [step #3](/workers/configuration/versions-and-deployments/gradual-deployments/#3-create-a-new-deployment). - -You can also target a specific version using [version overrides](/workers/configuration/versions-and-deployments/version-overrides/). - -#### 5. Set your new version to 100% deployment - -Run `wrangler versions deploy` again and follow the interactive prompts. Select the version uploaded in [step 2](/workers/configuration/versions-and-deployments/gradual-deployments/#2-create-a-new-version-of-the-worker) and set it to 100% deployment. - - - -### Via the Cloudflare dashboard - -1. In the Cloudflare dashboard, go to the **Workers & Pages** page. - - - -2. Select **Create application** > **Hello World** template > deploy your Worker. -3. Once the Worker is deployed, go to the online code editor through **Edit code**. Edit the Worker code (change the `Response` content) and upload the Worker. -4. To save changes, select the **down arrow** next to **Deploy** > **Save**. This will create a new version of your Worker. -5. Create a new deployment that splits traffic between the two versions created in step 3 and 5 by going to **Deployments** and selecting **Deploy Version**. -6. cURL your Worker to test the split deployment. - -```bash -for j in {0..10} -do - curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev -done -``` - -You should see 10 responses. Responses will reflect the content returned by the versions in your deployment. Responses will vary depending on the percentages configured in step #6. - -## Gradual deployments with static assets - -When your Worker serves [static assets](/workers/static-assets/), gradual deployments can cause asset compatibility issues where users receive HTML from one version that references assets only available in another version, leading to 404 errors. - -For detailed guidance on handling static assets during gradual rollouts, including specific examples and configuration steps, refer to [Gradual rollouts](/workers/static-assets/routing/advanced/gradual-rollouts/). - -## Version affinity - -By default, the percentages configured when using gradual deployments operate on a per-request basis — a request has a X% probability of invoking one of two versions of the Worker in the [deployment](/workers/configuration/versions-and-deployments/#deployments). - -You may want requests associated with a particular identifier (such as user, session, or any unique ID) to be handled by a consistent version of your Worker to prevent version skew. Version skew occurs when there are multiple versions of an application deployed that are not forwards/backwards compatible. You can configure version affinity to prevent the Worker's version from changing back and forth on a per-request basis. - -You can do this by setting the `Cloudflare-Workers-Version-Key` header on the incoming request to your Worker. For example: - -```sh -curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: foo' -``` - -For a given [deployment](/workers/configuration/versions-and-deployments/#deployments), all requests with a version key set to `foo` will be handled by the same version of your Worker. The specific version of your Worker that the version key `foo` corresponds to is determined by the percentages you have configured for each Worker version in your deployment. - -You can set the `Cloudflare-Workers-Version-Key` header 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](/workers/runtime-apis/bindings/service-bindings/). - -### Setting `Cloudflare-Workers-Version-Key` using Ruleset Engine - -You may want to extract a version key from certain properties of your request such as the URL, headers or cookies. You can configure a [Ruleset Engine](/ruleset-engine/) rule on your zone to do this. This allows you to specify version affinity based on these properties without having to modify the external client that makes the request. - -For example, if your worker serves video assets under the URI path `/assets/` and you wanted requests to each unique asset to be handled by a consistent version, you could define the following [request header transform rule](/rules/transform/request-header-modification/): - - - -Text in **Expression Editor**: - -```txt -starts_with(http.request.uri.path, "/asset/") -``` - -Selected operation under **Modify request header**: _Set dynamic_ - -**Header name**: `Cloudflare-Workers-Version-Key` - -**Value**: `regex_replace(http.request.uri.path, "/asset/(.*)", "${1}")` - - - -## Version overrides - -You can use [version overrides](/workers/configuration/versions-and-deployments/version-overrides/) to send a request to a specific version of your Worker, bypassing the percentage-based routing (even when at 0%). Version overrides also work on subrequests made through [service bindings](/workers/runtime-apis/bindings/service-bindings/). - -Refer to [Version overrides](/workers/configuration/versions-and-deployments/version-overrides/) for full details, including usage with service bindings. - -## Gradual deployments for Durable Objects - -To provide [global uniqueness](/durable-objects/platform/known-issues/#global-uniqueness), only one version of each [Durable Object](/durable-objects/) can run at a time. This means that gradual deployments work slightly differently for Durable Objects. - -When you create a new gradual deployment for a Worker with Durable Objects, each Durable Object is assigned a Worker version based on the percentages you configured in your [deployment](/workers/configuration/versions-and-deployments/#deployments). This version will not change until you create a new deployment. - -![Gradual Deployments Durable Objects](~/assets/images/workers/platform/versions-and-deployments/durable-objects.png) - -### Example - -This example assumes that you have previously created 3 Durable Object instances with names "foo", "bar" and "baz". - -Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker. - -Here is how the versions of your Durable Objects might change as you progress your gradual deployment: - -| Deployment config | "foo" | "bar" | "baz" | -| :---------------------------------: | :---: | :---: | :---: | -| Version A: 100%
| A | A | A | -| Version B: 20%
Version A: 80% | B | A | A | -| Version B: 50%
Version A: 50% | B | B | A | -| Version B: 100%
| B | B | B | - -This is only an example, so the versions assigned to your Durable Objects may be different. However, the following is guaranteed: - -- For a given deployment, requests to each Durable Object will always use the same Worker version. -- When you specify each version in the same order as the previous deployment and increase the percentage of a version, Durable Objects which were previously assigned that version will not be assigned a different version. In this example, Durable Object "foo" would never revert from version "B" to version "A". -- The Durable Object will only be [reset](/durable-objects/observability/troubleshooting/#durable-object-reset-because-its-code-was-updated) when it is assigned a different version, so each Durable Object will only be reset once in this example. - -:::note -Typically, a Worker bundle will define both the Durable Object class and a Worker that interacts with it. In this case, you cannot deploy changes to your Durable Object and its Worker independently. - -You should ensure that API changes between your Durable Object and its Worker are [forwards and backwards compatible](/durable-objects/platform/known-issues/#code-updates) whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other. -::: - -### Migrations - -Versions of Worker bundles containing new Durable Object migrations cannot be uploaded. This is because Durable Object migrations are atomic operations. Once a migration is deployed, rollbacks cannot take place to any version prior to the one that included the migration. - -Durable Object migrations can be deployed with the following command: - - - -To limit the blast radius of Durable Object migration deployments, migrations should be deployed independently of other code changes. - -To understand why Durable Object migrations are atomic operations, consider the hypothetical example of gradually deploying a delete migration. If a delete migration were applied to 50% of Durable Object instances, then Workers requesting those Durable Object instances would fail because they would have been deleted. - -To do this without producing errors, a version of the Worker which does not depend on any Durable Object instances would have to have already been rolled out. Then, you can deploy a delete migration without affecting any traffic and there is no reason to do so gradually. - -## Observability - -When using gradual deployments, you may want to attribute Workers invocations to a specific version in order to get visibility into the impact of deploying new versions. - -### Logpush - -A new `ScriptVersion` object is available in [Workers Logpush](/workers/observability/logs/logpush/). `ScriptVersion` can only be added through the Logpush API right now. Sample API call: - -```bash -curl -X POST 'https://api.cloudflare.com/client/v4/accounts//logpush/jobs' \ --H 'Authorization: Bearer ' \ --H 'Content-Type: application/json' \ --d '{ -"name": "workers-logpush", -"output_options": { - "field_names": ["Event", "EventTimestampMs", "Outcome", "Logs", "ScriptName", "ScriptVersion"], -}, -"destination_conf": "", -"dataset": "workers_trace_events", -"enabled": true -}'| jq . -``` - -`ScriptVersion` is an object with the following structure: - -```json -scriptVersion: { - id: "", - message: "", - tag: "" -} -``` - -### Runtime binding - -Use the [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) in to access version ID or version tag in your Worker. - -## Limits - -### Deployments limit - -You can only create a new deployment with the last 100 uploaded versions of your Worker. diff --git a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx b/src/content/docs/workers/configuration/versions-and-deployments/index.mdx deleted file mode 100644 index c32f452efe2..00000000000 --- a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -pcx_content_type: concept -title: Versions & Deployments -head: [] -description: Upload versions of Workers and create deployments to release new versions. -products: - - workers ---- -import { DashButton } from "~/components"; - -Versions track changes to your Worker. Deployments configure how those changes are deployed to your traffic. - -You can upload changes (versions) to your Worker independent of changing the version that is actively serving traffic (deployment). - -![Versions and Deployments](~/assets/images/workers/platform/versions-and-deployments/versions-and-deployments.png) - -Using versions and deployments is useful if: - -- You are running critical applications on Workers and want to reduce risk when deploying new versions of your Worker using a rolling deployment strategy. -- You want to monitor for performance differences when deploying new versions of your Worker. -- You have a CI/CD pipeline configured for Workers but want to cut manual releases. - -## Versions - -A version is defined by the state of code as well as the state of configuration in a Worker's [Wrangler configuration file](/workers/wrangler/configuration/). Versions track historical changes to [bundled code](/workers/wrangler/bundling/), [static assets](/workers/static-assets/) and changes to configuration like [bindings](/workers/runtime-apis/bindings/) and [compatibility date and compatibility flags](/workers/configuration/compatibility-dates/) over time. - -Versions also track metadata associated with a version, including: the version ID, the user that created the version, deploy source, and timestamp. Optionally, a version message and version tag can be configured on version upload. - -:::note -State changes for associated Workers [storage resources](/workers/platform/storage-options/) such as [KV](/kv/), [R2](/r2/), [Durable Objects](/durable-objects/) and [D1](/d1/) are not tracked with versions. -::: - -## Deployments - -Deployments track the version(s) of your Worker that are actively serving traffic. A deployment can consist of one or two versions of a Worker. - -By default, Workers supports an all-at-once deployment model where traffic is immediately shifted from one version to the newly deployed version automatically. Alternatively, you can use [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) to create a rolling deployment strategy. - -You can also track metadata associated with a deployment, including: the user that created the deployment, deploy source, timestamp and the version(s) in the deployment. Optionally, you can configure a deployment message when you create a deployment. - -## Use versions and deployments - -### Create a new version - -Review the different ways you can create versions of your Worker and deploy them. - -#### Upload a new version and deploy it immediately - -A new version that is automatically deployed to 100% of traffic when: - -- Changes are uploaded with [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) via the Cloudflare dashboard -- Changes are deployed with the command [`npx wrangler deploy`](/workers/wrangler/commands/workers/#deploy) via [Workers Builds](/workers/ci-cd/builds) -- Changes are uploaded with the [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/) - -#### Upload a new version to be gradually deployed or deployed at a later time - -:::note - -Wrangler versions before 3.73.0 require you to specify a `--x-versions` flag. - -::: - -To create a new version of your Worker that is not deployed immediately, use the [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload) command or create a new version in the Cloudflare dashboard code editor by selecting **Edit code**, then the **Save** option from the **Deploy** button dropdown. - -Versions created in this way can then be deployed all at once or gradually deployed using the [`wrangler versions deploy`](/workers/wrangler/commands/workers/#versions-deploy) command or via the Cloudflare dashboard under the **Deployments** tab. - -:::note -When using [Wrangler](/workers/wrangler/), changes made to a Worker's triggers [routes, domains](/workers/configuration/routing/) or [cron triggers](/workers/configuration/cron-triggers/) need to be applied with the command [`wrangler triggers deploy`](/workers/wrangler/commands/workers/#triggers-deploy). -::: - -:::note -New versions are not created when you make changes to [resources connected to your Worker](/workers/runtime-apis/bindings/). For example, if two Workers (Worker A and Worker B) are connected via a [service binding](/workers/runtime-apis/bindings/service-bindings/), changing the code of Worker B will not create a new version of Worker A. Changing the code of Worker B will only create a new version of Worker B. Changes to the service binding (such as, deleting the binding or updating the [environment](/workers/wrangler/environments/) it points to) on Worker A will also not create a new version of Worker B. -::: - -#### Directly manage Versions and Deployments - -See examples of creating a Worker, Versions, and Deployments directly with the API, library SDKs, and Terraform in [Infrastructure as Code](/workers/platform/infrastructure-as-code/). - -### View versions and deployments - -#### Via Wrangler - -Wrangler allows you to view the 100 most recent versions and deployments. Refer to the [`versions list`](/workers/wrangler/commands/workers/#versions-list) and [`deployments list`](/workers/wrangler/commands/workers/#deployments-list) documentation to view the commands. - -#### Via the Cloudflare dashboard - -To view your deployments in the Cloudflare dashboard: - -1. In the Cloudflare dashboard, go to the **Workers & Pages** page. - - - -2. Select your Worker > **Deployments**. - -## Limits - -### First upload - -You must use [C3](/workers/get-started/guide/#1-create-a-new-worker-project) or [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) the first time you create a new Workers project. Using [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload) the first time you upload a Worker will fail. - -### Service worker syntax - -Service worker syntax is not supported for versions that are uploaded through [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload). You must use ES modules format. - -Refer to [Migrate from Service Workers to ES modules](/workers/reference/migrate-to-module-workers/#advantages-of-migrating) to learn how to migrate your Workers from the service worker format to the ES modules format. - -### Durable Object migrations - -Uploading a version with [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/) is not supported. Use [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) if you are applying a [Durable Object migration](/durable-objects/reference/durable-objects-migrations/). - diff --git a/src/content/docs/workers/databases/index.mdx b/src/content/docs/workers/databases/index.mdx index 13161bf16d6..a07afab43cc 100644 --- a/src/content/docs/workers/databases/index.mdx +++ b/src/content/docs/workers/databases/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Databases description: Explore database integrations and connectors for Cloudflare Workers projects. sidebar: - order: 13 + order: 14 group: hideIndex: true products: diff --git a/src/content/docs/workers/framework-guides/index.mdx b/src/content/docs/workers/framework-guides/index.mdx index e7fd39e00a6..d190470c4d9 100644 --- a/src/content/docs/workers/framework-guides/index.mdx +++ b/src/content/docs/workers/framework-guides/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Framework guides sidebar: - order: 12 + order: 13 group: hideIndex: true head: [] diff --git a/src/content/docs/workers/languages/index.mdx b/src/content/docs/workers/languages/index.mdx index 0d3f1faab8d..62a79a61005 100644 --- a/src/content/docs/workers/languages/index.mdx +++ b/src/content/docs/workers/languages/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Languages sidebar: - order: 17 + order: 18 head: [] description: Languages supported on Workers, a polyglot platform. products: diff --git a/src/content/docs/workers/observability/index.mdx b/src/content/docs/workers/observability/index.mdx index 3371f252b2b..2a1cdae79d2 100644 --- a/src/content/docs/workers/observability/index.mdx +++ b/src/content/docs/workers/observability/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Observability sidebar: - order: 15 + order: 16 head: [] description: Understand how your Worker projects are performing via logs, traces, metrics, and other data sources. products: diff --git a/src/content/docs/workers/platform/index.mdx b/src/content/docs/workers/platform/index.mdx index ac0d65647e7..88a99a9d425 100644 --- a/src/content/docs/workers/platform/index.mdx +++ b/src/content/docs/workers/platform/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Platform description: Learn about Workers platform pricing, limits, storage options, and technical details. sidebar: - order: 18 + order: 19 products: - workers --- diff --git a/src/content/docs/workers/reference/index.mdx b/src/content/docs/workers/reference/index.mdx index 5133ad80cd9..69c519de1dd 100644 --- a/src/content/docs/workers/reference/index.mdx +++ b/src/content/docs/workers/reference/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Reference description: Conceptual and technical reference material for Cloudflare Workers architecture and behavior. sidebar: - order: 19 + order: 20 group: hideIndex: true products: diff --git a/src/content/docs/workers/reference/migrate-to-module-workers.mdx b/src/content/docs/workers/reference/migrate-to-module-workers.mdx index 556b7173a32..b331b443887 100644 --- a/src/content/docs/workers/reference/migrate-to-module-workers.mdx +++ b/src/content/docs/workers/reference/migrate-to-module-workers.mdx @@ -19,7 +19,7 @@ There are several reasons to migrate your Workers to the ES modules format: 1. Your Worker will run faster. With service workers, bindings are exposed as globals. This means that for every request, the Workers runtime must create a new JavaScript execution context, which adds overhead and time. Workers written using ES modules can reuse the same execution context across multiple requests. 2. Implementing [Durable Objects](/durable-objects/) requires Workers that use ES modules. 3. Bindings for [D1](/d1/), [Workers AI](/workers-ai/), [Vectorize](/vectorize/), [Workflows](/workflows/), and [Images](/images/optimization/binding/) can only be used from Workers that use ES modules. -4. You can [gradually deploy changes to your Worker](/workers/configuration/versions-and-deployments/gradual-deployments/) when you use the ES modules format. +4. You can [gradually deploy changes to your Worker](/workers/versions-and-deployments/gradual-deployments/) when you use the ES modules format. 5. You can easily publish Workers using ES modules to `npm`, allowing you to import and reuse Workers within your codebase. ## Migrate a Worker diff --git a/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx b/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx index 53634f63552..39d9e0c894f 100644 --- a/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx +++ b/src/content/docs/workers/runtime-apis/bindings/version-metadata.mdx @@ -17,7 +17,7 @@ products: import { TabItem, Tabs, WranglerConfig } from "~/components" -The version metadata binding can be used to access metadata associated with a [version](/workers/configuration/versions-and-deployments/#versions) from inside the Workers runtime. +The version metadata binding can be used to access metadata associated with a [version](/workers/versions-and-deployments/#versions) from inside the Workers runtime. Worker version ID, version tag and timestamp of when the version was created are available through the version metadata binding. They can be used in events sent to [Workers Analytics Engine](/analytics/analytics-engine/) or to any third-party analytics/metrics service in order to aggregate by Worker version. diff --git a/src/content/docs/workers/runtime-apis/index.mdx b/src/content/docs/workers/runtime-apis/index.mdx index cea820da03a..514c94b9916 100644 --- a/src/content/docs/workers/runtime-apis/index.mdx +++ b/src/content/docs/workers/runtime-apis/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Runtime APIs description: Explore the JavaScript and web platform APIs available in the Cloudflare Workers runtime. sidebar: - order: 10 + order: 11 products: - workers --- diff --git a/src/content/docs/workers/static-assets/index.mdx b/src/content/docs/workers/static-assets/index.mdx index d8b87edd026..a772d4bde2f 100644 --- a/src/content/docs/workers/static-assets/index.mdx +++ b/src/content/docs/workers/static-assets/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Static Assets sidebar: - order: 11 + order: 12 head: [] description: Create full-stack applications deployed to Cloudflare Workers. products: diff --git a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx index 41d3dfeee94..153b233bbcf 100644 --- a/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx +++ b/src/content/docs/workers/static-assets/migration-guides/migrate-from-pages.mdx @@ -323,7 +323,7 @@ Pages automatically creates a preview environment for each project, and can be i To get a similar experience in Workers, you must: -1. Ensure [preview URLs](/workers/configuration/previews/) are enabled (they are on by default). +1. Ensure [preview URLs](/workers/versions-and-deployments/preview-urls/) are enabled (they are on by default). @@ -343,7 +343,7 @@ To get a similar experience in Workers, you must: 1. [Enable non-production branch builds](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds) in Workers Builds. -Optionally, you can also [protect these preview URLs with Cloudflare Access](/workers/configuration/previews/#manage-access-to-preview-urls). +Optionally, you can also [protect these preview URLs with Cloudflare Access](/workers/versions-and-deployments/preview-urls/#manage-access-to-preview-urls). :::note @@ -412,9 +412,9 @@ This compatibility matrix compares the features of Workers and Pages. Unless oth | ----------------------------------------------------------------------------------------------------------- | ------- | ------- | | **Writing, Testing, and Deploying Code** | | | | [Cloudflare Vite plugin](/workers/vite-plugin/) | ✅ | ❌ | -| [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/) | ✅ | ✅ | -| [Gradual Deployments](/workers/configuration/versions-and-deployments/) | ✅ | ❌ | -| [Preview URLs](/workers/configuration/previews) | ✅ | ✅ | +| [Rollbacks](/workers/versions-and-deployments/rollbacks/) | ✅ | ✅ | +| [Gradual Deployments](/workers/versions-and-deployments/) | ✅ | ❌ | +| [Preview URLs](/workers/versions-and-deployments/preview-urls/) | ✅ | ✅ | | [Testing tools](/workers/testing) | ✅ | ✅ | | [Local Development](/workers/local-development/) | ✅ | ✅ | | [Remote Development (`--remote`)](/workers/wrangler/commands/) | ✅ | ❌ | diff --git a/src/content/docs/workers/static-assets/routing/advanced/gradual-rollouts.mdx b/src/content/docs/workers/static-assets/routing/advanced/gradual-rollouts.mdx index e3d810092fc..055184d3d05 100644 --- a/src/content/docs/workers/static-assets/routing/advanced/gradual-rollouts.mdx +++ b/src/content/docs/workers/static-assets/routing/advanced/gradual-rollouts.mdx @@ -1,115 +1,10 @@ --- -pcx_content_type: concept +pcx_content_type: navigation title: Gradual rollouts +description: Prevent asset mismatches during gradual Worker deployments with static assets. +external_link: /workers/versions-and-deployments/gradual-deployments/version-affinity/#static-assets sidebar: order: 4 -head: [] -description: Provide static asset routing solutions for gradual Worker deployments. products: - workers --- - -import { Example } from "~/components"; - -[Gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) route requests to different Worker versions based on configured percentages. When your Worker serves static assets, this per-request routing can cause asset reference mismatches that result in 404 errors and broken user experiences. - -Modern JavaScript frameworks commonly generate fingerprinted asset filenames during builds. For example, when you build a React application with Vite, your assets might look like: - -``` -dist/ -├── index.html -├── assets/ -│ ├── index-a1b2c3d4.js # Main bundle with content hash -│ ├── index-e5f6g7h8.css # Styles with content hash -│ └── logo-i9j0k1l2.svg # Images with content hash -``` - -During a gradual rollout between two versions of your application, you might have: - -**Version A (old build):** - -- `index.html` references `assets/index-a1b2c3d4.js` -- `assets/index-a1b2c3d4.js` exists - -**Version B (new build):** - -- `index.html` references `assets/index-m3n4o5p6.js` -- `assets/index-m3n4o5p6.js` exists - -If a user's initial request for `/` goes to Version A, they'll receive HTML that references `index-a1b2c3d4.js`. However, when their browser then requests `/assets/index-a1b2c3d4.js`, that request might be routed to Version B, which only contains `index-m3n4o5p6.js`, resulting in a 404 error. - -This issue affects applications built with any framework that fingerprints assets, including: - -- **React** (Create React App, Next.js, Vite) -- **Vue** (Vue CLI, Nuxt.js, Vite) -- **Angular** (Angular CLI) -- **Svelte** (SvelteKit, Vite) -- **Static site generators** that optimize asset loading - -## Preventing asset mismatches with version affinity - -[Version affinity](/workers/configuration/versions-and-deployments/gradual-deployments/#version-affinity) ensures all requests from the same user are handled by the same Worker version, preventing asset reference mismatches entirely. You can configure this using [Transform Rules](/rules/transform/request-header-modification/) to automatically set the `Cloudflare-Workers-Version-Key` header. - -### Session-based affinity - -For applications with user sessions, use session identifiers: - - - -Text in **Expression Editor**: - -```txt -http.cookie contains "session_id" -``` - -Selected operation under **Modify request header**: _Set dynamic_ - -**Header name**: `Cloudflare-Workers-Version-Key` - -**Value**: `http.request.cookies["session_id"][0]` - - - -### User-based affinity - -For authenticated applications, use user identifiers stored in cookies or headers: - - - -Text in **Expression Editor**: - -```txt -http.cookie contains "user_id" -``` - -Selected operation under **Modify request header**: _Set dynamic_ - -**Header name**: `Cloudflare-Workers-Version-Key` - -**Value**: `http.request.cookies["user_id"][0]` - - - -## Testing and monitoring - -Before rolling out to production, verify that your version affinity setup works correctly: - -```bash -# Test with version affinity - both requests should hit the same version -curl -H "Cookie: session_id=test123" https://your-worker.example.com/ -curl -H "Cookie: session_id=test123" https://your-worker.example.com/assets/index.js -``` - -During gradual rollouts, monitor your Worker's analytics for increased 404 response rates, especially for asset files (`.js`, `.css`, `.png`). Use [Analytics Engine](/analytics/analytics-engine/) or [Logpush](/workers/observability/logs/logpush/) to track these metrics and catch asset mismatch issues early. - -## Best practices - -When deploying applications with fingerprinted assets using gradual rollouts: - -- Use version affinity (preferably session-based) to ensure consistent asset loading -- Test asset loading using version overrides before increasing rollout percentages -- Monitor 404 rates during deployments to catch issues quickly -- Have rollback procedures ready in case asset problems arise -- Choose session-based or user-based affinity depending on your application's authentication model - -With proper version affinity configuration, you can safely perform gradual deployments of applications that use modern build tools and asset optimization without worrying about broken user experiences from missing assets. diff --git a/src/content/docs/workers/testing/index.mdx b/src/content/docs/workers/testing/index.mdx index bf3b4465776..352e0fd1ea3 100644 --- a/src/content/docs/workers/testing/index.mdx +++ b/src/content/docs/workers/testing/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Testing description: Compare testing options for Cloudflare Workers, including Vitest integration, Miniflare, and unstable_startWorker. sidebar: - order: 14 + order: 15 products: - workers --- diff --git a/src/content/docs/workers/versions-and-deployments/deployment-management.mdx b/src/content/docs/workers/versions-and-deployments/deployment-management.mdx new file mode 100644 index 00000000000..c0b3d236c17 --- /dev/null +++ b/src/content/docs/workers/versions-and-deployments/deployment-management.mdx @@ -0,0 +1,94 @@ +--- +pcx_content_type: how-to +title: Deployment management +head: [] +description: Upload versions independently and control when and how they are deployed to your Worker's traffic. +products: + - workers +sidebar: + order: 1 +--- + +import { DashButton, PackageManagers } from "~/components"; + +By default, a new version is created and immediately deployed to 100% of traffic when you use any of the following: + +- [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) +- [Workers Builds](/workers/ci-cd/builds/) +- The [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/) + +You can separate these steps so that uploading a version and deploying it are independent actions. This lets you control exactly when a new version goes live. + +## Upload a version without deploying + +### Via Wrangler + +Use the [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload) command: + + + +:::note +Wrangler versions before 3.73.0 require you to specify a `--x-versions` flag. +::: + +:::note +To apply changes to a Worker's triggers ([routes, domains](/workers/configuration/routing/), or [cron triggers](/workers/configuration/cron-triggers/)), use the [`wrangler triggers deploy`](/workers/wrangler/commands/workers/#triggers-deploy) command. +::: + +### Via the Cloudflare dashboard + +1. In the Cloudflare dashboard, go to the **Workers & Pages** page. + + + +2. Select your Worker > **Edit code**. +3. Make your changes, then select the **down arrow** next to **Deploy** > **Save**. + +:::note +New versions are not created when you make changes to [resources connected to your Worker](/workers/runtime-apis/bindings/). For example, if two Workers (Worker A and Worker B) are connected via a [service binding](/workers/runtime-apis/bindings/service-bindings/), changing the code of Worker B will not create a new version of Worker A. Changes to the service binding configuration (such as deleting the binding or updating the [environment](/workers/wrangler/environments/) it points to) on Worker A will also not create a new version of Worker B. +::: + +## Deploy an uploaded version + +Once you have uploaded a version, you can create a deployment that routes traffic to it. + +### Via Wrangler + +Use the [`wrangler versions deploy`](/workers/wrangler/commands/workers/#versions-deploy) command and follow the interactive prompts to select the version and set it to 100%: + + + +You can also set the traffic percentage to less than 100% to start a [gradual deployment](/workers/versions-and-deployments/gradual-deployments/). + +### Via the Cloudflare dashboard + +1. In the Cloudflare dashboard, go to the **Workers & Pages** page. + + + +2. Select your Worker > **Deployments**. +3. Select **Promote deployment** and choose the version you want to deploy. + +### Via Infrastructure as Code + +You can also create versions and deployments directly with the API, library SDKs, and Terraform. Refer to [Infrastructure as Code](/workers/platform/infrastructure-as-code/) for examples. + +## Limits + +### Deployments limit + +You can only create a deployment with the last 100 uploaded versions of your Worker. + +### First upload + +You must use [C3](/workers/get-started/guide/#1-create-a-new-worker-project) or [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) the first time you create a new Workers project. Using [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload) the first time you upload a Worker will fail. + +### Service worker syntax + +Service worker syntax is not supported for versions that are uploaded through [`wrangler versions upload`](/workers/wrangler/commands/workers/#versions-upload). You must use ES modules format. + +Refer to [Migrate from Service Workers to ES modules](/workers/reference/migrate-to-module-workers/#advantages-of-migrating) to learn how to migrate your Workers from the service worker format to the ES modules format. + +### Durable Object migrations + +Uploading a version with [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/) is not supported. Use [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) if you are applying a [Durable Object migration](/durable-objects/reference/durable-objects-migrations/). diff --git a/src/content/docs/workers/versions-and-deployments/gradual-deployments/index.mdx b/src/content/docs/workers/versions-and-deployments/gradual-deployments/index.mdx new file mode 100644 index 00000000000..6b0cad7a70b --- /dev/null +++ b/src/content/docs/workers/versions-and-deployments/gradual-deployments/index.mdx @@ -0,0 +1,155 @@ +--- +pcx_content_type: configuration +title: Gradual deployments +head: [] +description: Incrementally deploy code changes to your Workers with gradual deployments. +products: + - workers +sidebar: + order: 3 +--- + +import { DashButton, PackageManagers } from "~/components"; + +Gradual deployments let you incrementally deploy new [versions](/workers/versions-and-deployments/#versions) of your Worker by splitting traffic across versions. Instead of shifting all traffic to a new version at once, you can route a percentage of requests to the new version while the rest continue to be handled by the previous version. + +![Gradual Deployments](~/assets/images/workers/platform/versions-and-deployments/gradual-deployments.png) + +Using gradual deployments, you can: + +- Gradually shift traffic to a newer version of your Worker +- Monitor error rates and exceptions across versions using [observability](/workers/versions-and-deployments/gradual-deployments/#observability) tooling +- [Roll back](/workers/versions-and-deployments/rollbacks/) to a previously stable version if you notice issues + +## Use gradual deployments + +The following section guides you through an example usage of gradual deployments. + +### Via Wrangler + +:::note +Minimum required Wrangler version: 3.40.0. Versions before 3.73.0 require you to specify a `--x-versions` flag. +::: + +#### 1. Create and deploy a new Worker + +Create a new `"Hello World"` Worker using the [`create-cloudflare` CLI (C3)](/pages/get-started/c3/) and deploy it. + + + +Answer `yes` or `no` to using TypeScript. Answer `yes` to deploying your application. This is the first version of your Worker. + +#### 2. Create a new version of the Worker + +Edit the Worker code by changing the `Response` content and upload the Worker using the [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload) command. + + + +This will create a new version of the Worker that is not automatically deployed. + +#### 3. Create a new deployment + +Use the [`wrangler versions deploy`](/workers/wrangler/commands/general/#versions-deploy) command to create a new deployment that splits traffic between two versions. Follow the interactive prompts to select your desired percentages for each version. + + + +#### 4. Test the split deployment + +Run a cURL command on your Worker to test the split deployment. + +```bash +for j in {1..10} +do + curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev +done +``` + +You should see 10 responses. Responses will vary depending on the percentages configured in [step #3](/workers/versions-and-deployments/gradual-deployments/#3-create-a-new-deployment). + +You can also target a specific version using [version overrides](/workers/versions-and-deployments/version-overrides/). + +#### 5. Set your new version to 100% deployment + +Run `wrangler versions deploy` again and follow the interactive prompts. Select the new version and set it to 100%. + + + +### Via the Cloudflare dashboard + +1. In the Cloudflare dashboard, go to the **Workers & Pages** page. + + + +2. Select **Create application** > **Hello World** template > deploy your Worker. +3. Once the Worker is deployed, go to the online code editor through **Edit code**. Edit the Worker code (change the `Response` content). +4. To save changes without deploying, select the **down arrow** next to **Deploy** > **Save**. This will create a new version of your Worker. +5. Go to **Deployments** and select **Promote deployment** to create a split between the two versions. + +## Version skew + +Because gradual deployments mean multiple versions of your Worker serve traffic simultaneously, clients and services can end up interacting with more than one version in ways that produce errors or inconsistent behavior. This is called **version skew**. + +### Version skew within a Worker + +By default, each request is independently routed to a version based on the configured percentages. This means consecutive requests from the same user - including page reloads and asset fetches - can be handled by different versions. + +If you want to pin a user to a consistent version for the duration of the gradual deployment, you can use [version affinity](/workers/versions-and-deployments/gradual-deployments/version-affinity/). + +### Version skew between Workers + +When one Worker calls another via a [service binding](/workers/runtime-apis/bindings/service-bindings/), the two Workers may be at different points in their own gradual deployment. Worker A (on its new version) might call Worker B, but the request lands on Worker B's old version where the API contract is different. + +You can use [version overrides](/workers/versions-and-deployments/version-overrides/) to pin a downstream Worker to a specific version during a subrequest. + +## Durable Objects + +Gradual deployments work differently for [Durable Objects](/durable-objects/) because only one version of each Durable Object can run at a time. Refer to [Gradual Deployments with Durable Objects](/workers/versions-and-deployments/gradual-deployments/with-durable-objects/) for details on version assignment, guarantees, and migrations. + +## Observability + +When using gradual deployments, you may want to attribute Workers invocations to a specific version in order to get visibility into the impact of deploying new versions. + +### Logpush + +A new `ScriptVersion` object is available in [Workers Logpush](/workers/observability/logs/logpush/). `ScriptVersion` can only be added through the Logpush API right now. Sample API call: + +```bash +curl -X POST 'https://api.cloudflare.com/client/v4/accounts//logpush/jobs' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +-d '{ +"name": "workers-logpush", +"output_options": { + "field_names": ["Event", "EventTimestampMs", "Outcome", "Logs", "ScriptName", "ScriptVersion"] +}, +"destination_conf": "", +"dataset": "workers_trace_events", +"enabled": true +}'| jq . +``` + +`ScriptVersion` is an object with the following structure: + +```json +{ + "ScriptVersion": { + "id": "", + "message": "", + "tag": "" + } +} +``` + +### Runtime binding + +Use the [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) to access version ID or version tag in your Worker. + +## Limits + +### Deployments limit + +You can only create a gradual deployment with the last 100 uploaded versions of your Worker. diff --git a/src/content/docs/workers/versions-and-deployments/gradual-deployments/version-affinity.mdx b/src/content/docs/workers/versions-and-deployments/gradual-deployments/version-affinity.mdx new file mode 100644 index 00000000000..bff1931b5f6 --- /dev/null +++ b/src/content/docs/workers/versions-and-deployments/gradual-deployments/version-affinity.mdx @@ -0,0 +1,183 @@ +--- +pcx_content_type: configuration +title: Version affinity +description: Consistently route users to the same Worker version during gradual deployments using version affinity. +sidebar: + order: 1 +--- + +import { Example, TypeScriptExample } from "~/components"; + +During a [gradual deployment](/workers/versions-and-deployments/gradual-deployments/), each request has a random chance of routing to either version based on the specified percentages. This means the same user can be served content from a different version every time a request is made, which can cause **version skew** issues. + +Version affinity solves this by deterministically assigning users to a 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. + +## How it works + +Set the `Cloudflare-Workers-Version-Key` header on the incoming request to your Worker: + +```sh +curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: foo' +``` + +For a given [deployment](/workers/versions-and-deployments/#deployments), all requests with a version key set to `foo` will be handled by the same version of your Worker. The platform hashes the key and uses the result with the configured percentages to deterministically assign a version - you do not choose which version a key maps to. + +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. + +You can set the `Cloudflare-Workers-Version-Key` header 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](/workers/runtime-apis/bindings/service-bindings/). + +## Static assets + +{/* This section can be removed when skew protection launches as that will mean that version affinity is no longer required to support this use case (or could be replaced with a short section linked to the new skew protection page) */} + +Version affinity is particularly important when your Worker serves [static assets](/workers/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 of your application will have different asset filenames: + +- Version A's HTML references `assets/index-a1b2c3d4.js` +- Version B's HTML references `assets/index-m3n4o5p6.js` + +Without version affinity, a user can receive HTML from version A, but when their browser requests `index-a1b2c3d4.js`, that request may be routed to version B - which does not have that file - resulting in a 404 error and a broken page. + +Configuring version affinity using any of the methods in [Choose a version key](#choose-a-version-key) prevents this entirely by ensuring all requests from the same user are routed to the same version. + +## Choose a version key + +The right version key depends on what stable identifiers your application has available. You can set the header using a [Transform Rule](/rules/transform/request-header-modification/) on your zone, which extracts values from the request without modifying your application code. + +:::note +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](/workers/runtime-apis/bindings/service-bindings/). +::: + +### Authenticated applications + +If your application has a user identifier in a cookie or header, this is the best option. Each user is deterministically assigned to a version and stays there across sessions, devices, and reloads. + + + +Text in **Expression Editor**: + +```txt +http.cookie contains "user_id" +``` + +Selected operation under **Modify request header**: _Set dynamic_ + +**Header name**: `Cloudflare-Workers-Version-Key` + +**Value**: `http.request.cookies["user_id"][0]` + + + +### Applications with sessions + +If your application sets a session cookie, use the session identifier. 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. + + + +Text in **Expression Editor**: + +```txt +http.cookie contains "session_id" +``` + +Selected operation under **Modify request header**: _Set dynamic_ + +**Header name**: `Cloudflare-Workers-Version-Key` + +**Value**: `http.request.cookies["session_id"][0]` + + + +### Anonymous or cookieless applications + +If your application does not have any stable identifier in the request, you have two options: + +**Option 1: Use the client IP address.** This is the simplest approach and requires no application changes. Users behind the same NAT or VPN will be grouped together, and mobile users who switch networks may change version, but for most applications this significantly reduces version flip-flopping compared to random per-request routing. + + + +Text in **Expression Editor**: + +```txt +true +``` + +Selected operation under **Modify request header**: _Set dynamic_ + +**Header name**: `Cloudflare-Workers-Version-Key` + +**Value**: `ip.src` + + + +**Option 2: Set a long-lived cookie from your Worker.** On the first request (which will be randomly assigned), your Worker generates a stable identifier and sets it as a cookie. All subsequent requests use that cookie as the version key. This gives the best consistency for anonymous users, at the cost of a small amount of application code. + + + +```ts +export default { + async fetch(request: Request, env: Env): Promise { + 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: + + + +Text in **Expression Editor**: + +```txt +http.cookie contains "version-key" +``` + +Selected operation under **Modify request header**: _Set dynamic_ + +**Header name**: `Cloudflare-Workers-Version-Key` + +**Value**: `http.request.cookies["version-key"][0]` + + + +:::note +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. The cookie is set on the response, so all subsequent requests will be consistently routed. +::: + +## Testing + +You can verify that version affinity is working by sending multiple requests with the same version key and confirming they are handled by the same version: + +```sh +# Both requests should return responses from the same version +curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: test-user-123' +curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: test-user-123' +``` + +Use the [version metadata binding](/workers/runtime-apis/bindings/version-metadata/) to include the version ID in your Worker's response during testing. + +During gradual rollouts, monitor your Worker's analytics for increased 404 response rates, especially for asset files (`.js`, `.css`, `.png`). Use [Analytics Engine](/analytics/analytics-engine/) or [Logpush](/workers/observability/logs/logpush/) to track these metrics and catch version skew issues early. If you notice problems, you can [roll back](/workers/versions-and-deployments/rollbacks/) to the previous version. + +## Related resources + +- [Gradual deployments](/workers/versions-and-deployments/gradual-deployments/) - How percentage-based traffic splitting works +- [Version overrides](/workers/versions-and-deployments/version-overrides/) - Send a request to a specific version by ID (for smoke testing and debugging, not for end-user routing) +- [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) - Access version ID and tag from within your Worker diff --git a/src/content/docs/workers/versions-and-deployments/gradual-deployments/with-durable-objects.mdx b/src/content/docs/workers/versions-and-deployments/gradual-deployments/with-durable-objects.mdx new file mode 100644 index 00000000000..c1060f4f406 --- /dev/null +++ b/src/content/docs/workers/versions-and-deployments/gradual-deployments/with-durable-objects.mdx @@ -0,0 +1,56 @@ +--- +pcx_content_type: configuration +title: With Durable Objects +description: How gradual deployments work with Durable Objects, including version assignment, migrations, and guarantees. +sidebar: + order: 2 +--- + +import { PackageManagers } from "~/components"; + +To provide [global uniqueness](/durable-objects/platform/known-issues/#global-uniqueness), only one version of each [Durable Object](/durable-objects/) can run at a time. This means that gradual deployments work slightly differently for Durable Objects. + +When you create a new gradual deployment for a Worker with Durable Objects, each Durable Object is assigned a Worker version based on the percentages you configured in your [deployment](/workers/versions-and-deployments/#deployments). This version will not change until you create a new deployment. + +![Gradual Deployments Durable Objects](~/assets/images/workers/platform/versions-and-deployments/durable-objects.png) + +## Example + +This example assumes that you have previously created three Durable Object instances with names "foo", "bar", and "baz". + +Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker. + +Here is how the versions of your Durable Objects might change as you progress your gradual deployment: + +| Deployment config | "foo" | "bar" | "baz" | +| :---------------------------------: | :---: | :---: | :---: | +| Version A: 100%
| A | A | A | +| Version B: 20%
Version A: 80% | B | A | A | +| Version B: 50%
Version A: 50% | B | B | A | +| Version B: 100%
| B | B | B | + +This is only an example, so the versions assigned to your Durable Objects may be different. However, the following is guaranteed: + +- For a given deployment, requests to each Durable Object will always use the same Worker version. +- When you specify each version in the same order as the previous deployment and increase the percentage of a version, Durable Objects which were previously assigned that version will not be assigned a different version. In this example, Durable Object "foo" would never revert from version "B" to version "A". +- The Durable Object will only be [reset](/durable-objects/observability/troubleshooting/#durable-object-reset-because-its-code-was-updated) when it is assigned a different version, so each Durable Object will only be reset once in this example. + +:::note +Typically, a Worker bundle will define both the Durable Object class and a Worker that interacts with it. In this case, you cannot deploy changes to your Durable Object and its Worker independently. + +You should ensure that API changes between your Durable Object and its Worker are [forwards and backwards compatible](/durable-objects/platform/known-issues/#code-updates) whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other. +::: + +## Migrations + +Versions of Worker bundles containing new Durable Object migrations cannot be uploaded. This is because Durable Object migrations are atomic operations. Once a migration is deployed, rollbacks cannot take place to any version prior to the one that included the migration. + +Durable Object migrations can be deployed with the following command: + + + +To limit the blast radius of Durable Object migration deployments, migrations should be deployed independently of other code changes. + +To understand why Durable Object migrations are atomic operations, consider the hypothetical example of gradually deploying a delete migration. If a delete migration were applied to 50% of Durable Object instances, then Workers requesting those Durable Object instances would fail because they would have been deleted. + +To do this without producing errors, a version of the Worker which does not depend on any Durable Object instances would have to have already been rolled out. Then, you can deploy a delete migration without affecting any traffic and there is no reason to do so gradually. diff --git a/src/content/docs/workers/versions-and-deployments/index.mdx b/src/content/docs/workers/versions-and-deployments/index.mdx new file mode 100644 index 00000000000..5c089c4e4a3 --- /dev/null +++ b/src/content/docs/workers/versions-and-deployments/index.mdx @@ -0,0 +1,61 @@ +--- +pcx_content_type: concept +title: Versions & deployments +head: [] +description: Understand how Workers tracks changes with versions and releases them with deployments. +products: + - workers +sidebar: + order: 9 +--- + +import { DashButton } from "~/components"; + +Every time you change your Worker's code or configuration, Workers creates a **version**. A **deployment** determines which version(s) are actively serving traffic. + +![Versions and Deployments](~/assets/images/workers/platform/versions-and-deployments/versions-and-deployments.png) + +## Versions + +A version captures the complete state of your Worker at a point in time: its [bundled code](/workers/wrangler/bundling/), [static assets](/workers/static-assets/), [bindings](/workers/runtime-apis/bindings/), and [compatibility settings](/workers/configuration/compatibility-dates/). 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. + +:::note +State changes for associated [storage resources](/workers/platform/storage-options/) such as [KV](/kv/), [R2](/r2/), [Durable Objects](/durable-objects/), and [D1](/d1/) are not tracked with versions. +::: + +## Deployments + +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](/workers/versions-and-deployments/gradual-deployments/)). + +Each deployment tracks who created it, when, and which version(s) it includes. + +## Default behavior + +By default, these two concepts are coupled together - when you run [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy), Workers creates a new version and immediately deploys it to 100% of traffic in a single step. + +You can decouple them 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](/workers/versions-and-deployments/gradual-deployments/) or manual promotion. Refer to [Deployment management](/workers/versions-and-deployments/deployment-management/) for details. + +## View versions and deployments + +### Via Wrangler + +Wrangler allows you to view the 100 most recent versions and deployments. Refer to the [`versions list`](/workers/wrangler/commands/workers/#versions-list) and [`deployments list`](/workers/wrangler/commands/workers/#deployments-list) documentation for the commands. + +### Via the Cloudflare dashboard + +1. In the Cloudflare dashboard, go to the **Workers & Pages** page. + + + +2. Select your Worker > **Deployments**. + +## Next steps + +- [Deployment management](/workers/versions-and-deployments/deployment-management/) - Upload versions without deploying them and control when they go live +- [Preview URLs](/workers/versions-and-deployments/preview-urls/) - Test new versions before deploying them to production +- [Gradual deployments](/workers/versions-and-deployments/gradual-deployments/) - Split traffic between two versions using percentage-based routing +- [Version affinity](/workers/versions-and-deployments/gradual-deployments/version-affinity/) - Consistently route users to the same version across page loads during a gradual deployment +- [Version overrides](/workers/versions-and-deployments/version-overrides/) - Send a request to a specific version by ID for smoke testing and pinning between Workers +- [Rollbacks](/workers/versions-and-deployments/rollbacks/) - Revert to a previously deployed version diff --git a/src/content/docs/workers/configuration/previews.mdx b/src/content/docs/workers/versions-and-deployments/preview-urls.mdx similarity index 90% rename from src/content/docs/workers/configuration/previews.mdx rename to src/content/docs/workers/versions-and-deployments/preview-urls.mdx index 98bdc56c85b..e32a5670e53 100644 --- a/src/content/docs/workers/configuration/previews.mdx +++ b/src/content/docs/workers/versions-and-deployments/preview-urls.mdx @@ -5,11 +5,11 @@ head: [] description: Preview URLs allow you to preview new versions of your project without deploying it to production. products: - workers +sidebar: + order: 2 --- -import { Render, WranglerConfig, DashButton } from "~/components"; - -# Overview +import { WranglerConfig, DashButton } from "~/components"; Preview URLs allow you to preview new versions of your Worker without deploying it to production. @@ -26,7 +26,7 @@ Preview URLs can be: - Used for collaboration between teams to test code changes in a live environment and verify updates. - Used to test new API endpoints, validate data formats, and ensure backward compatibility with existing services. -When testing zone level performance or security features for a version, we recommend using [version overrides](/workers/configuration/versions-and-deployments/version-overrides/) so that your zone's performance and security settings apply. +When testing zone level performance or security features for a version, we recommend using [version overrides](/workers/versions-and-deployments/version-overrides/) so that your zone's performance and security settings apply. :::note Preview URLs are only available for Worker versions uploaded after 2024-09-25. @@ -36,7 +36,7 @@ Preview URLs are only available for Worker versions uploaded after 2024-09-25. ### Versioned Preview URLs -Every time you create a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker, a unique static version preview URL is generated automatically. These URLs use a version prefix and follow the format `-..workers.dev`. +Every time you create a new [version](/workers/versions-and-deployments/#versions) of your Worker, a unique static version preview URL is generated automatically. These URLs use a version prefix and follow the format `-..workers.dev`. New versions of a Worker are created when you run: @@ -52,7 +52,7 @@ Minimum required Wrangler version: 3.74.0. Check your version by running `wrangl #### View versioned preview URLs using Wrangler -The [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload) command uploads a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker and returns a preview URL for each version uploaded. +The [`wrangler versions upload`](/workers/wrangler/commands/general/#versions-upload) command uploads a new [version](/workers/versions-and-deployments/#versions) of your Worker and returns a preview URL for each version uploaded. #### View versioned preview URLs on the Workers dashboard diff --git a/src/content/docs/workers/configuration/versions-and-deployments/rollbacks.mdx b/src/content/docs/workers/versions-and-deployments/rollbacks.mdx similarity index 78% rename from src/content/docs/workers/configuration/versions-and-deployments/rollbacks.mdx rename to src/content/docs/workers/versions-and-deployments/rollbacks.mdx index 3344ae7e72c..8fb6fb2a5a3 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/rollbacks.mdx +++ b/src/content/docs/workers/versions-and-deployments/rollbacks.mdx @@ -5,16 +5,18 @@ head: [] description: Revert to an older version of your Worker. products: - workers +sidebar: + order: 5 --- import { DashButton } from "~/components"; -You can roll back to a previously deployed [version](/workers/configuration/versions-and-deployments/#versions) of your Worker using [Wrangler](/workers/wrangler/commands/general/#rollback) or the Cloudflare dashboard. Rolling back to a previous version of your Worker will immediately create a new [deployment](/workers/configuration/versions-and-deployments/#deployments) with the version specified and become the active deployment across all your deployed routes and domains. +You can roll back to a previously deployed [version](/workers/versions-and-deployments/#versions) of your Worker using [Wrangler](/workers/wrangler/commands/general/#rollback) or the Cloudflare dashboard. Rolling back to a previous version of your Worker will immediately create a new [deployment](/workers/versions-and-deployments/#deployments) with the version specified and become the active deployment across all your deployed routes and domains. You can roll back from any deployment, including: - A single-version deployment (rolling back replaces the current version with the selected version). -- A [split deployment](/workers/configuration/versions-and-deployments/gradual-deployments/) with two versions (rolling back replaces both versions with the selected version at 100% traffic). +- A [split deployment](/workers/versions-and-deployments/gradual-deployments/) with two versions (rolling back replaces both versions with the selected version at 100% traffic). ## Via Wrangler @@ -33,7 +35,7 @@ To roll back to a specified version of your Worker via the Cloudflare dashboard: ## Rolling back from a split deployment -If you are using a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/) with two versions splitting traffic, rolling back will: +If you are using a [gradual deployment](/workers/versions-and-deployments/gradual-deployments/) with two versions splitting traffic, rolling back will: 1. Replace the split deployment with a single-version deployment. 2. Route 100% of traffic to the version you selected for rollback. diff --git a/src/content/docs/workers/configuration/versions-and-deployments/version-overrides.mdx b/src/content/docs/workers/versions-and-deployments/version-overrides.mdx similarity index 66% rename from src/content/docs/workers/configuration/versions-and-deployments/version-overrides.mdx rename to src/content/docs/workers/versions-and-deployments/version-overrides.mdx index 6e0adad5257..4fbfd33c8af 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/version-overrides.mdx +++ b/src/content/docs/workers/versions-and-deployments/version-overrides.mdx @@ -3,24 +3,31 @@ pcx_content_type: configuration title: Version overrides description: Send requests to a specific version of your Worker in a gradual deployment using version overrides. sidebar: - order: 3 + order: 4 --- -You can use version overrides to send a request to a specific version of your Worker in your [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/). +import { TypeScriptExample } from "~/components"; -To specify a version override in your request, set the `Cloudflare-Workers-Version-Overrides` header on the request to your Worker. For example: +You can use version overrides to send a request to a specific version of your Worker in the current deployment, even those set to serve 0% of traffic. + +## How to set version overrides + +To specify a version override in your request, set the `Cloudflare-Workers-Version-Overrides` header on the request to your Worker. `Cloudflare-Workers-Version-Overrides` is a [Dictionary Structured Header](https://www.rfc-editor.org/rfc/rfc8941#name-dictionaries) that can contain multiple key-value pairs. Each **key** indicates the name of the Worker the override should be applied to. The **value** indicates the version ID that should be used and must be a [String](https://www.rfc-editor.org/rfc/rfc8941#name-strings). For example: ```sh curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"' ``` -`Cloudflare-Workers-Version-Overrides` is a [Dictionary Structured Header](https://www.rfc-editor.org/rfc/rfc8941#name-dictionaries). - -The dictionary can contain multiple key-value pairs. Each key indicates the name of the Worker the override should be applied to. The value indicates the version ID that should be used and must be a [String](https://www.rfc-editor.org/rfc/rfc8941#name-strings). +:::caution[Version 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`](/workers/wrangler/commands/general/#deployments-list) command or on the [**Workers & Pages** page of the Cloudflare dashboard > select your Worker > **Deployments** > **Active Deployment**](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/deployments). -:::note[Verifying that the version override was applied] +{/* To be removed/changed once this limit is increased for skew protection */} +Workers currently only supports serving **two** different versions in one deployment. Follow the instructions for [gradual deployments](/workers/versions-and-deployments/gradual-deployments/#use-gradual-deployments) to ensure the requested version is in the current deployment. You can set the new version to 0% traffic to avoid normal traffic being routed to it. + +::: + +### Verify that version overrides were applied There are a number of reasons why a request's version override may not be applied. For example: @@ -31,9 +38,7 @@ In the case that a request's version override is not applied, the request will b You can observe the version of your Worker that was invoked using [Observability](https://developers.cloudflare.com/workers/observability/), including in features such as [Logpush](/workers/observability/logs/logpush/). Alternatively, if you want to inform clients about the version they ran (e.g. for faster and more transparent debugging), you could use the [version metadata binding](/workers/runtime-apis/bindings/version-metadata/) and return the version ID in the Worker's response. -::: - -## Example +## Smoke test example You may want to test a new version in production before gradually deploying it to an increasing proportion of external traffic. This is commonly referred to as a "smoke test". @@ -62,38 +67,47 @@ You can set the `Cloudflare-Workers-Version-Overrides` header when making a subr If you forward the original request object, the override header carries through automatically: -```js + + +```ts // The override header from the inbound request is forwarded to the downstream Worker. export default { - async fetch(request, env) { - return env.MY_SERVICE.fetch(request); - }, + async fetch(request: Request, env: Env): Promise { + return env.MY_SERVICE.fetch(request); + }, }; ``` + + Alternatively, you can set an override header explicitly: -```js + + +```ts // Replace the version ID with the target version from `wrangler versions list`. export default { - async fetch(request, env) { - const response = await env.MY_SERVICE.fetch("https://example.com/", { - headers: { - "Cloudflare-Workers-Version-Overrides": - 'my-downstream-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"', - }, - }); - return response; - }, + async fetch(request: Request, env: Env): Promise { + const response = await env.MY_SERVICE.fetch("https://example.com/", { + headers: { + "Cloudflare-Workers-Version-Overrides": + 'my-downstream-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"', + }, + }); + return response; + }, }; ``` + + :::note Version overrides only apply to `fetch()`-based service binding calls. There is currently no way to specify version overrides when calling a service binding via RPC (`env.MY_SERVICE.someMethod()`), because RPC calls do not support attaching headers. ::: ## Related resources -- [Gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) — Learn how percentage-based traffic splitting works, including version affinity and observability. -- [Service bindings](/workers/runtime-apis/bindings/service-bindings/) — How Workers communicate with each other. -- [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) — Access version ID and tag from within your Worker. +- [Version affinity](/workers/versions-and-deployments/gradual-deployments/version-affinity/) - Use cookies & headers to pin users to a specific version during a gradual deployment. +- [Gradual deployments](/workers/versions-and-deployments/gradual-deployments/) - Learn how percentage-based traffic splitting works. +- [Service bindings](/workers/runtime-apis/bindings/service-bindings/) - How Workers communicate with each other. +- [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) - Access version ID and tag from within your Worker. diff --git a/src/content/docs/workers/vite-plugin/index.mdx b/src/content/docs/workers/vite-plugin/index.mdx index bd44845641c..b2e15669d52 100644 --- a/src/content/docs/workers/vite-plugin/index.mdx +++ b/src/content/docs/workers/vite-plugin/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: overview title: Vite plugin sidebar: - order: 16 + order: 17 description: A full-featured integration between Vite and the Workers runtime products: - workers diff --git a/src/content/docs/workers/wrangler/commands/workers.mdx b/src/content/docs/workers/wrangler/commands/workers.mdx index f24d525e1de..02f0a284c3f 100644 --- a/src/content/docs/workers/wrangler/commands/workers.mdx +++ b/src/content/docs/workers/wrangler/commands/workers.mdx @@ -288,7 +288,7 @@ This command configures your project for Cloudflare Workers without deploying. I Manage the secret variables for a Worker. -This action creates a new [version](/workers/configuration/versions-and-deployments/#versions) of the Worker and [deploys](/workers/configuration/versions-and-deployments/#deployments) it immediately. To only create a new version of the Worker, use the [`wrangler versions secret`](#versions-secret-put) commands. +This action creates a new [version](/workers/versions-and-deployments/#versions) of the Worker and [deploys](/workers/versions-and-deployments/#deployments) it immediately. To only create a new version of the Worker, use the [`wrangler versions secret`](#versions-secret-put) commands. @@ -391,13 +391,13 @@ The minimum required wrangler version to use these commands is 3.40.0. For versi @@ -438,7 +438,7 @@ The minimum required wrangler version to use these commands is 3.40.0. For versi ## `deployments` -[Deployments](/workers/configuration/versions-and-deployments/#deployments) track the version(s) of your Worker that are actively serving traffic. +[Deployments](/workers/versions-and-deployments/#deployments) track the version(s) of your Worker that are actively serving traffic. :::note The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the `--x-versions` flag. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 42d73078287..c2c3dc095df 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -173,7 +173,7 @@ The `main` key is optional for assets-only Workers. - Enables use of `*.workers.dev` subdomain to deploy your Worker. If you have a Worker that is only for `scheduled` events, you can set this to `false`. Defaults to `true`. Refer to [types of routes](#types-of-routes). - `preview_urls` - - Enables use of Preview URLs to test your Worker. Defaults to value of `workers_dev`. Refer to [Preview URLs](/workers/configuration/previews). + - Enables use of Preview URLs to test your Worker. Defaults to value of `workers_dev`. Refer to [Preview URLs](/workers/versions-and-deployments/preview-urls/). - `route` - A route that your Worker should be deployed to. Only one of `routes` or `route` is required. Refer to [types of routes](#types-of-routes). diff --git a/src/content/docs/workers/wrangler/index.mdx b/src/content/docs/workers/wrangler/index.mdx index f680985ddfd..b3872f7c020 100644 --- a/src/content/docs/workers/wrangler/index.mdx +++ b/src/content/docs/workers/wrangler/index.mdx @@ -3,7 +3,7 @@ title: Wrangler description: Wrangler is the CLI for the Cloudflare Developer Platform. Use it to build, test, and deploy Workers projects. pcx_content_type: navigation sidebar: - order: 15 + order: 16 head: - tag: title content: Wrangler diff --git a/src/content/glossary/workers.yaml b/src/content/glossary/workers.yaml index b1525e3310b..2ca033c6836 100644 --- a/src/content/glossary/workers.yaml +++ b/src/content/glossary/workers.yaml @@ -23,7 +23,7 @@ entries: - term: deployment general_definition: |- - [Deployments](/workers/configuration/versions-and-deployments/#deployments) track the version(s) of your Worker that are actively serving traffic. + [Deployments](/workers/versions-and-deployments/#deployments) track the version(s) of your Worker that are actively serving traffic. - term: Durable Objects general_definition: |- @@ -85,7 +85,7 @@ entries: - term: rollback general_definition: |- - [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/) are a way to deploy an older deployment to the Cloudflare global network. + [Rollbacks](/workers/versions-and-deployments/rollbacks/) are a way to deploy an older deployment to the Cloudflare global network. - term: R2 general_definition: |- @@ -111,7 +111,7 @@ entries: - term: version general_definition: |- - A [version](/workers/configuration/versions-and-deployments/#versions) is defined by the state of code as well as the state of configuration in a Worker's Wrangler file. + A [version](/workers/versions-and-deployments/#versions) is defined by the state of code as well as the state of configuration in a Worker's Wrangler file. - term: V8 general_definition: |- diff --git a/src/content/partials/workers/custom_headers.mdx b/src/content/partials/workers/custom_headers.mdx index c40fd5c2a19..bf3a5393c31 100644 --- a/src/content/partials/workers/custom_headers.mdx +++ b/src/content/partials/workers/custom_headers.mdx @@ -105,7 +105,7 @@ To enable other domains to fetch every static asset from your {props.product === {props.product === "workers" ? ( <> -This applies the `Access-Control-Allow-Origin` header to any incoming URL. Note that the CORS specification only allows `*`, `null`, or an exact origin as valid `Access-Control-Allow-Origin` values — wildcard patterns within origins are not supported. To allow CORS from specific preview URLs, you will need to handle this dynamically in your Worker code rather than through the `_headers` file. +This applies the `Access-Control-Allow-Origin` header to any incoming URL. Note that the CORS specification only allows `*`, `null`, or an exact origin as valid `Access-Control-Allow-Origin` values — wildcard patterns within origins are not supported. To allow CORS from specific preview URLs, you will need to handle this dynamically in your Worker code rather than through the `_headers` file. ) : ( <> diff --git a/src/content/release-notes/workers.yaml b/src/content/release-notes/workers.yaml index c223528be1c..876dee43834 100644 --- a/src/content/release-notes/workers.yaml +++ b/src/content/release-notes/workers.yaml @@ -155,7 +155,7 @@ entries: - The `internal_writable_stream_abort_clears_queue` compatibility flag will ensure that certain `WritableStream` `abort()` operations are handled immediately rather than lazily, ensuring that the stream is appropriately aborted when the consumer of the stream is no longer active. - publish_date: "2024-07-19" description: |- - - Workers with the [mTLS](/workers/runtime-apis/bindings/mtls/) binding now support [Gradual Deployments](/workers/configuration/versions-and-deployments/gradual-deployments/). + - Workers with the [mTLS](/workers/runtime-apis/bindings/mtls/) binding now support [Gradual Deployments](/workers/versions-and-deployments/gradual-deployments/). - publish_date: "2024-07-18" description: |- - Added a new `truncated` flag to [Tail Worker](/workers/observability/logs/tail-workers/) events to indicate when the event buffer is full and events are being dropped. @@ -169,7 +169,7 @@ entries: - Fixed a bug where when writing to an HTTP Response body would sometimes hang when the client disconnected (and sometimes throw an exception). It will now always throw an exception. - publish_date: "2024-07-01" description: |- - - When using [Gradual Deployments](/workers/configuration/versions-and-deployments/gradual-deployments/), you can now use [version overrides](/workers/configuration/versions-and-deployments/gradual-deployments/#version-overrides) to send a request to a specific version of your Worker. + - When using [Gradual Deployments](/workers/versions-and-deployments/gradual-deployments/), you can now use [version overrides](/workers/versions-and-deployments/version-overrides/) to send a request to a specific version of your Worker. - publish_date: "2024-06-28" description: |- - Fixed a bug which caused `Date.now()` to return skewed results if called before the first I/O of the first request after a Worker first started up. The value returned would be offset backwards by the amount of CPU time spent starting the Worker (compiling and running global scope), making it seem like the first I/O (e.g. first fetch()) was slower than it really was. This skew had nothing to do with Spectre mitigations; it was simply a longstanding bug. @@ -188,7 +188,7 @@ entries: - Blob and Body objects now include a new `bytes()` method, reflecting [recent](https://w3c.github.io/FileAPI/#bytes-method-algo) [additions](https://fetch.spec.whatwg.org/#dom-body-bytes) to web standards. - publish_date: "2024-06-03" description: |- - - Workers with [Smart Placement](/workers/configuration/placement/) enabled now support [Gradual Deployments](/workers/configuration/versions-and-deployments/gradual-deployments/). + - Workers with [Smart Placement](/workers/configuration/placement/) enabled now support [Gradual Deployments](/workers/versions-and-deployments/gradual-deployments/). - publish_date: "2024-05-17" description: |- - Updated v8 to version 12.6.