From de1eaeb57bd3499c6d398c0b203ed749d271771b Mon Sep 17 00:00:00 2001 From: mmalden <179233968+mia303@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:42:51 -0400 Subject: [PATCH 1/4] [Artifacts] Add HMD guide --- src/content/docs/artifacts/guides/hmd.mdx | 104 ++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 src/content/docs/artifacts/guides/hmd.mdx diff --git a/src/content/docs/artifacts/guides/hmd.mdx b/src/content/docs/artifacts/guides/hmd.mdx new file mode 100644 index 00000000000..16d7a75150d --- /dev/null +++ b/src/content/docs/artifacts/guides/hmd.mdx @@ -0,0 +1,104 @@ +--- +title: Health-mediated deployments +description: Deploy your Artifacts code with progressive rollouts using Health-Mediated Deployments, built on Workflows +pcx_content_type: how-to +sidebar: + order: 6 +products: + - artifacts + - workflows +--- + +Health-mediated deployments (HMD) allow developers to deploy their code via staged rollouts. For example, you can specify percentage-based rollouts with soak time at each step (i.e. progress the rollout by 10%, wait for five minutes, and then progress another 10%) to deploy safely in case you need to pause or rollback. + +You can configure HMD at the Worker, project, or repository level through either a Cloudflare-managed plan or a Bring Your Own [Workflow](/workflows) (BYO-W) plan. + +Cloudflare-managed plans are presets which include percentage-based rollouts, soak times, and threshold error rates for common use cases, i.e. + +### CLI + +1. Begin an HMD deployment with `cf hmd start`. +2. If your project has an existing `cloudflare.hmd.ts` file, a new HMD deployment will trigger. Otherwise, you will be prompted to select a rollout plan. + +Select from the available plans (TBD) or choose `custom` to define your own logic via BYO-W. A `cloudflare.hmd.ts` file will be generated in your current directory (Worker, project, or monorepo). + +If `custom` is selected, you will be prompted for the following inputs: +- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] +- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] +- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% + +You can edit your `cloudflare.hmd.ts` file directly for more customizable logic. For more information, refer to the BYO-W section below. + +3. You can query your rollout with `cf hmd status` and take action including `pause`, `terminate`, and `rollback`. + +### Dashboard + +1. Configure HMD by navigating into **Workers** -> **Settings** +2. Select from a Cloudflare-managed plan or choose `custom`. +3. If `custom`, you can specify: + +- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] +- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] +- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% + +This will add a `cloudflare.hmd.ts` file to your project. + +## BYO-W via API + +BYO-W allows you to orchestrate your health-mediated deployment with the built-in functionality of Cloudflare Workflows. Each step in your deployment corresponds to a [Workflow step](/workflows/build/workers-api/#workflowstep). + +First, define an array for your percentage-based rollout: + +```ts +const PERCENTAGES = [25, 50, 75, 100]; +``` + +Next, define how to advance your deployment via `step.rollout` +```ts +await step.rollout(`rollout ${percentage}%`, +percentage, +{ rollback: (ctx) => version.abort(ctx.output) }, + ); +``` + +Then implement your soak time for that step in the rollout via [step.sleep](/workflows/build/sleeping-and-retrying/#sleep-a-workflow). + +```ts +await step.sleep(`wait ${percentage}%`, "5 minutes"); +``` + +BYO-W also supports `step.health`: custom querying against [Workers Observability](/workers/observability/), so you can define conditions under which the deployment should pause, terminate, or rollback. + +```ts + await step.health(userWobsQuery) +``` + +A full `cloudflare.hmd.ts` file might look this this: + +```ts +import { HMDWorkflow, Version } from "@cloudflare/hmd"; +import type { WorkflowStep } from "cloudflare:workers"; + +const PERCENTAGES = [10, 15, 30, 40, 50, 60, 70, 80, 90, 100]; + +export class DiscordHMD extends HMDWorkflow { + protected async rollout(version: Version, step: WorkflowStep): Promise { + for (const percentage of PERCENTAGES) { +await step.sleep(`wait ${percentage}%`, "5 minutes"); + + await step.health(userWobsQuery) + +await step.rollout(`rollout ${percentage}%`, +percentage, +{ rollback: (ctx) => version.abort(ctx.output) }, + ); + } + } +} +``` + +If your deployment requires human-in-the-loop intervention, for either normal progression or rollbacks, pauses, or termination, use [waitForEvent](/workflows/build/events-and-parameters/#wait-for-events). + +## Observability + +You can view the progression of your deployment in the [Workflows] tab of the dashboard. Each deployment is surfaced as a Workflow instance. \ No newline at end of file From 72d457c58e7b312190afb916484ffb66c6e1dd10 Mon Sep 17 00:00:00 2001 From: mmalden <179233968+mia303@users.noreply.github.com> Date: Wed, 15 Jul 2026 11:50:39 -0400 Subject: [PATCH 2/4] [Workflows] Update with template --- src/content/docs/artifacts/guides/hmd.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/content/docs/artifacts/guides/hmd.mdx b/src/content/docs/artifacts/guides/hmd.mdx index 16d7a75150d..bde8bccdde6 100644 --- a/src/content/docs/artifacts/guides/hmd.mdx +++ b/src/content/docs/artifacts/guides/hmd.mdx @@ -47,6 +47,22 @@ This will add a `cloudflare.hmd.ts` file to your project. BYO-W allows you to orchestrate your health-mediated deployment with the built-in functionality of Cloudflare Workflows. Each step in your deployment corresponds to a [Workflow step](/workflows/build/workers-api/#workflowstep). +Your `cloudflare.hmd.ts` file will be generated with the following: + +```ts +import { HMDWorkflow } from "cloudflare: hmd"; +import type { Version } from "cloudflare: hmd"; +import type { WorkflowStep } from "cloudflare:workers"; + +export class MyHMD extends HMDWorkflow { + protected async rollout(version: Version, step: WorkflowStep): Promise { +// your rollout logic +} +} +``` + +The Version object represents the Worker version being deployed. [Workflow step](/workflows/build/workers-api/#workflowstep) is the standard Workflows step API extended with HMD-specific methods, including `step.health` and `step.rollout` (see below). + First, define an array for your percentage-based rollout: ```ts From 1cb6e8eb0d038aedb81983a7bc01b290d325ca18 Mon Sep 17 00:00:00 2001 From: mmalden <179233968+mia303@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:05:26 -0400 Subject: [PATCH 3/4] [Artifacts] Rename HMD guide to gradual deployments --- .../artifacts/guides/gradual-deployments.mdx | 148 ++++++++++++++++++ src/content/docs/artifacts/guides/hmd.mdx | 120 -------------- 2 files changed, 148 insertions(+), 120 deletions(-) create mode 100644 src/content/docs/artifacts/guides/gradual-deployments.mdx delete mode 100644 src/content/docs/artifacts/guides/hmd.mdx diff --git a/src/content/docs/artifacts/guides/gradual-deployments.mdx b/src/content/docs/artifacts/guides/gradual-deployments.mdx new file mode 100644 index 00000000000..4eda5bdfdc8 --- /dev/null +++ b/src/content/docs/artifacts/guides/gradual-deployments.mdx @@ -0,0 +1,148 @@ +--- +title: Gradual deployments +description: Deploy your Artifacts code with progressive rollouts using gradual deployments, built on Workflows +pcx_content_type: how-to +sidebar: + order: 6 +products: + - artifacts + - workflows +--- + +Gradual deployments allow developers to deploy their code via staged rollouts. For example, you can specify percentage-based rollouts with soak time at each step (i.e. progress the rollout by 10%, wait for five minutes, and then progress another 10%) to deploy safely in case you need to pause or rollback. + +You can configure gradual deployments at the Worker, project, or repository level through either a Cloudflare-managed plan or a Bring Your Own [Workflow](/workflows) (BYO-W) plan. + +Cloudflare-managed plans are presets which include percentage-based rollouts, soak times, and threshold error rates for common use cases, i.e. + +### CLI + +1. Begin a gradual deployment with `cf grad-dep start`. +2. If your project has an existing `cloudflare.grad-dep.ts` file, a new gradual deployment will trigger. Otherwise, you will be prompted to select a rollout plan. + +Select from the available plans (TBD) or choose `custom` to define your own logic via BYO-W. A `cloudflare.grad-dep.ts` file will be generated in your current directory (Worker, project, or monorepo). + +If `custom` is selected, you will be prompted for the following inputs: +- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] +- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] +- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% + +You can edit your `cloudflare.grad-dep.ts` file directly for more customizable logic. For more information, refer to the BYO-W section below. + +3. You can query your rollout with `cf grad-dep status` and take action including `pause`, `terminate`, and `rollback`. + +### Dashboard + +1. Configure gradual deployments by navigating into **Workers** -> **Settings** +2. Select from a Cloudflare-managed plan or choose `custom`. +3. If `custom`, you can specify: + +- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] +- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] +- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% + +This will add a `cloudflare.grad-dep.ts` file to your project. + +## BYO-W via API + +BYO-W allows you to orchestrate your gradual deployment with the built-in functionality of Cloudflare Workflows. Each step in your deployment corresponds to a [Workflow step](/workflows/build/workers-api/#workflowstep). + +In this example, we'll show you how to set up a custom rollout yourself. Here are the main components you'll work with: + +- **`GradDepWorkflow`** — the base class you extend. You define your deployment logic in its `rollout` method. +- **`Version`** — an object representing the Worker version being deployed. Call `version.abort()` to roll back. +- **`step.rollout`** — advances the deployment to a given percentage. +- **`step.sleep`** — the soak time you wait between steps. See [step.sleep](/workflows/build/sleeping-and-retrying/#sleep-a-workflow). +- **`step.health`** — a health check that queries [Workers Observability](/workers/observability/). If the query breaches its threshold, the deployment automatically pauses and rolls back. + +`step.rollout`, `step.sleep`, and `step.health` come from the [Workflow step](/workflows/build/workers-api/#workflowstep) API — the standard Workflows step API, extended with the gradual-deployment-specific `step.rollout` and `step.health` methods. To customize your deployment, you'll swap in your own values and queries for these pieces. + +Your `cloudflare.grad-dep.ts` file will be generated with the following skeleton: + +```ts +import { GradDepWorkflow } from "cloudflare: grad-dep"; +import type { Version } from "cloudflare: grad-dep"; +import type { WorkflowStep } from "cloudflare:workers"; + +export class MyGradDep extends GradDepWorkflow { + protected async rollout(version: Version, step: WorkflowStep): Promise { +// your rollout logic +} +} +``` + +First, define an array for your percentage-based rollout: + +```ts +const PERCENTAGES = [25, 50, 75, 100]; +``` + +Next, define how to advance your deployment via `step.rollout`: +```ts +await step.rollout(`rollout ${percentage}%`, +percentage, +{ rollback: (ctx) => version.abort(ctx.output) }, + ); +``` + +Then implement your soak time for that step in the rollout via `step.sleep`: + +```ts +await step.sleep(`wait ${percentage}%`, "5 minutes"); +``` + +Finally, use `step.health` to query against Workers Observability. Define a query that specifies the metric and the threshold that should trip a rollback: + +```ts +// Define what "healthy" means: roll back if the 4xx/5xx rate exceeds 5% +const errorRateQuery = { + metric: "http.error_rate", + threshold: 0.05, + window: "5 minutes", +}; +``` + +Then pass it to `step.health`. If the query breaches its threshold, the deployment pauses and rolls back automatically: + +```ts +await step.health(`check ${percentage}%`, errorRateQuery); +``` + +Putting these components together, a full `cloudflare.grad-dep.ts` file might look like this: + +```ts +import { GradDepWorkflow, Version } from "@cloudflare/grad-dep"; +import type { WorkflowStep } from "cloudflare:workers"; + +const PERCENTAGES = [10, 15, 30, 40, 50, 60, 70, 80, 90, 100]; + +// Roll back if the 4xx/5xx rate exceeds 5% over a 5-minute window +const errorRateQuery = { + metric: "http.error_rate", + threshold: 0.05, + window: "5 minutes", +}; + +export class DiscordGradDep extends GradDepWorkflow { + protected async rollout(version: Version, step: WorkflowStep): Promise { + for (const percentage of PERCENTAGES) { + // Advance the rollout to the next percentage + await step.rollout(`rollout ${percentage}%`, percentage, { + rollback: (ctx) => version.abort(ctx.output), + }); + + // Soak: let the new version take traffic before checking + await step.sleep(`wait ${percentage}%`, "5 minutes"); + + // Check health; auto-pauses and rolls back if the threshold is breached + await step.health(`check ${percentage}%`, errorRateQuery); + } + } +} +``` + +If your deployment requires human-in-the-loop intervention, for either normal progression or rollbacks, pauses, or termination, use [waitForEvent](/workflows/build/events-and-parameters/#wait-for-events). + +## Observability + +You can view the progression of your deployment in the [Workflows] tab of the dashboard. Each deployment is surfaced as a Workflow instance. diff --git a/src/content/docs/artifacts/guides/hmd.mdx b/src/content/docs/artifacts/guides/hmd.mdx deleted file mode 100644 index bde8bccdde6..00000000000 --- a/src/content/docs/artifacts/guides/hmd.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Health-mediated deployments -description: Deploy your Artifacts code with progressive rollouts using Health-Mediated Deployments, built on Workflows -pcx_content_type: how-to -sidebar: - order: 6 -products: - - artifacts - - workflows ---- - -Health-mediated deployments (HMD) allow developers to deploy their code via staged rollouts. For example, you can specify percentage-based rollouts with soak time at each step (i.e. progress the rollout by 10%, wait for five minutes, and then progress another 10%) to deploy safely in case you need to pause or rollback. - -You can configure HMD at the Worker, project, or repository level through either a Cloudflare-managed plan or a Bring Your Own [Workflow](/workflows) (BYO-W) plan. - -Cloudflare-managed plans are presets which include percentage-based rollouts, soak times, and threshold error rates for common use cases, i.e. - -### CLI - -1. Begin an HMD deployment with `cf hmd start`. -2. If your project has an existing `cloudflare.hmd.ts` file, a new HMD deployment will trigger. Otherwise, you will be prompted to select a rollout plan. - -Select from the available plans (TBD) or choose `custom` to define your own logic via BYO-W. A `cloudflare.hmd.ts` file will be generated in your current directory (Worker, project, or monorepo). - -If `custom` is selected, you will be prompted for the following inputs: -- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] -- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] -- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% - -You can edit your `cloudflare.hmd.ts` file directly for more customizable logic. For more information, refer to the BYO-W section below. - -3. You can query your rollout with `cf hmd status` and take action including `pause`, `terminate`, and `rollback`. - -### Dashboard - -1. Configure HMD by navigating into **Workers** -> **Settings** -2. Select from a Cloudflare-managed plan or choose `custom`. -3. If `custom`, you can specify: - -- Percentage-based rollout, i.e. [10%, 20%, 50%, 80%, 100%] -- Soak time per step, i.e. [10 minutes, 10 minutes, 30 minutes, 30 minutes, 30 minutes] -- Threshold for pause, rollback, and teriminate, i.e. 4xx errors at 5% - -This will add a `cloudflare.hmd.ts` file to your project. - -## BYO-W via API - -BYO-W allows you to orchestrate your health-mediated deployment with the built-in functionality of Cloudflare Workflows. Each step in your deployment corresponds to a [Workflow step](/workflows/build/workers-api/#workflowstep). - -Your `cloudflare.hmd.ts` file will be generated with the following: - -```ts -import { HMDWorkflow } from "cloudflare: hmd"; -import type { Version } from "cloudflare: hmd"; -import type { WorkflowStep } from "cloudflare:workers"; - -export class MyHMD extends HMDWorkflow { - protected async rollout(version: Version, step: WorkflowStep): Promise { -// your rollout logic -} -} -``` - -The Version object represents the Worker version being deployed. [Workflow step](/workflows/build/workers-api/#workflowstep) is the standard Workflows step API extended with HMD-specific methods, including `step.health` and `step.rollout` (see below). - -First, define an array for your percentage-based rollout: - -```ts -const PERCENTAGES = [25, 50, 75, 100]; -``` - -Next, define how to advance your deployment via `step.rollout` -```ts -await step.rollout(`rollout ${percentage}%`, -percentage, -{ rollback: (ctx) => version.abort(ctx.output) }, - ); -``` - -Then implement your soak time for that step in the rollout via [step.sleep](/workflows/build/sleeping-and-retrying/#sleep-a-workflow). - -```ts -await step.sleep(`wait ${percentage}%`, "5 minutes"); -``` - -BYO-W also supports `step.health`: custom querying against [Workers Observability](/workers/observability/), so you can define conditions under which the deployment should pause, terminate, or rollback. - -```ts - await step.health(userWobsQuery) -``` - -A full `cloudflare.hmd.ts` file might look this this: - -```ts -import { HMDWorkflow, Version } from "@cloudflare/hmd"; -import type { WorkflowStep } from "cloudflare:workers"; - -const PERCENTAGES = [10, 15, 30, 40, 50, 60, 70, 80, 90, 100]; - -export class DiscordHMD extends HMDWorkflow { - protected async rollout(version: Version, step: WorkflowStep): Promise { - for (const percentage of PERCENTAGES) { -await step.sleep(`wait ${percentage}%`, "5 minutes"); - - await step.health(userWobsQuery) - -await step.rollout(`rollout ${percentage}%`, -percentage, -{ rollback: (ctx) => version.abort(ctx.output) }, - ); - } - } -} -``` - -If your deployment requires human-in-the-loop intervention, for either normal progression or rollbacks, pauses, or termination, use [waitForEvent](/workflows/build/events-and-parameters/#wait-for-events). - -## Observability - -You can view the progression of your deployment in the [Workflows] tab of the dashboard. Each deployment is surfaced as a Workflow instance. \ No newline at end of file From daa6952d37354588c3dbf946ef91c9d6d25a8901 Mon Sep 17 00:00:00 2001 From: mmalden <179233968+mia303@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:07:44 -0400 Subject: [PATCH 4/4] Add note that gradual deployments will apply to all rollouts once configured --- src/content/docs/artifacts/guides/gradual-deployments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/artifacts/guides/gradual-deployments.mdx b/src/content/docs/artifacts/guides/gradual-deployments.mdx index 4eda5bdfdc8..483580abe41 100644 --- a/src/content/docs/artifacts/guides/gradual-deployments.mdx +++ b/src/content/docs/artifacts/guides/gradual-deployments.mdx @@ -11,7 +11,7 @@ products: Gradual deployments allow developers to deploy their code via staged rollouts. For example, you can specify percentage-based rollouts with soak time at each step (i.e. progress the rollout by 10%, wait for five minutes, and then progress another 10%) to deploy safely in case you need to pause or rollback. -You can configure gradual deployments at the Worker, project, or repository level through either a Cloudflare-managed plan or a Bring Your Own [Workflow](/workflows) (BYO-W) plan. +You can configure gradual deployments at the Worker, project, or repository level through either a Cloudflare-managed plan or a Bring Your Own [Workflow](/workflows) (BYO-W) plan. Once gradual deployments are configured, every deployment will automatically follow your defined rollout plan. Cloudflare-managed plans are presets which include percentage-based rollouts, soak times, and threshold error rates for common use cases, i.e.