From fe133f042653cecb5bb2a714fe8d29d38f25c673 Mon Sep 17 00:00:00 2001 From: Richard McDaniel <1130888+rmcdaniel@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:33:44 +0000 Subject: [PATCH] Prepare Chart 3.0.0 for native Server 3.12.0 Advance the chart default to native Server 3.12.0. The release requires an explicit schema upgrade on every backend, so the chart major advances under the chart's semver rules. Values keys and templates are unchanged. Refs #1227 Co-Authored-By: Claude Opus 5.5 --- k8s/helm/durable-workflow/Chart.yaml | 14 ++--- k8s/helm/durable-workflow/README.md | 2 +- k8s/helm/durable-workflow/docs/UPGRADING.md | 61 +++++++++++++++++++++ k8s/helm/durable-workflow/values.yaml | 2 +- resources/release/source-release.json | 4 +- 5 files changed, 72 insertions(+), 11 deletions(-) diff --git a/k8s/helm/durable-workflow/Chart.yaml b/k8s/helm/durable-workflow/Chart.yaml index 5bbe42d61..64c2443ea 100644 --- a/k8s/helm/durable-workflow/Chart.yaml +++ b/k8s/helm/durable-workflow/Chart.yaml @@ -5,11 +5,11 @@ type: application # The chart's own semver version. Bumped on every chart release; treated as # independent of the server image version (appVersion). Breaking-change rules # for this version live in docs/UPGRADING.md alongside the chart. -version: 2.1.0 +version: 3.0.0 # The immutable native Durable Workflow Server this chart release packages. # The onboarding default in values.yaml and appVersion are generated from the # checked-in source release record (helm_chart.app_version). -appVersion: "3.11.0" +appVersion: "3.12.0" kubeVersion: ">=1.27.0-0" home: https://durable-workflow.github.io/docs/2.0/deployment sources: @@ -30,14 +30,14 @@ annotations: # exact commit that most recently changed the packaged chart. org.opencontainers.image.source: https://github.com/durable-workflow/server dev.durable-workflow.source-revision: "unreleased" - dev.durable-workflow.image-reference: "docker.io/durableworkflow/server:3.11.0" + dev.durable-workflow.image-reference: "docker.io/durableworkflow/server:3.12.0" artifacthub.io/license: MIT artifacthub.io/category: integration-delivery # Free-form changelog for the current chart release shown by Artifact Hub. artifacthub.io/changes: | - kind: changed - description: "Default image advances to native Server 3.11.0. No schema step is required from 3.10.x; values and resource contracts remain compatible. Earlier releases retain the explicit schema-upgrade and restore boundaries in docs/UPGRADING.md." + description: "Default image advances to native Server 3.12.0. Every backend needs an explicit additive schema upgrade from 3.11.x with all replicas stopped; startup never upgrades and rollback requires restoring the pre-upgrade backup. Values keys are unchanged. See docs/UPGRADING.md." + - kind: fixed + description: "Native local external payloads stay readable and reclaimable after a namespace storage policy is disabled or moved. Each object keeps its original root binding; keep every retained payload root mounted until its objects are reclaimed." - kind: added - description: "Failed-run redrive reuses complete ordered plain timer pairs with a fresh shared timer ID and no timer work. Reused event clocks and the persisted initial run-start anchor retain fractional precision; repeated redrives preserve recorded clock strings." - - kind: changed - description: "Worker protocol 1.20 and control plane 2 remain unchanged. Historical missing fractions cannot be reconstructed. Published PHP, Python and Rust replay qualification remains separately attributable under Server #980. https://github.com/durable-workflow/server/releases/tag/3.11.0" + description: "Read-only open-run version usage query behind capabilities.workflow_version_usage. Worker protocol 1.20 and control plane 2 remain unchanged. https://github.com/durable-workflow/server/releases/tag/3.12.0" diff --git a/k8s/helm/durable-workflow/README.md b/k8s/helm/durable-workflow/README.md index c89557cbf..06a1387bd 100644 --- a/k8s/helm/durable-workflow/README.md +++ b/k8s/helm/durable-workflow/README.md @@ -77,7 +77,7 @@ helm install durable-workflow ./k8s/helm/durable-workflow \ ```yaml image: - tag: "3.11.0" + tag: "3.12.0" # Pin a digest in production: # digest: "sha256:abc123..." diff --git a/k8s/helm/durable-workflow/docs/UPGRADING.md b/k8s/helm/durable-workflow/docs/UPGRADING.md index a7820a6f6..3bb419235 100644 --- a/k8s/helm/durable-workflow/docs/UPGRADING.md +++ b/k8s/helm/durable-workflow/docs/UPGRADING.md @@ -69,6 +69,67 @@ chart MINOR bump and an entry below. ## Per-version migration notes +### Chart 3.0.0 / Server 3.12.0 (native) + +**Every backend needs an explicit native schema upgrade from 3.11.x.** Chart +3.0.0 selects native Server 3.12.0 and retains the existing values and resource +contract; Chart 2.x values files work unchanged. The chart major advances +because changing its default image requires operator action on every backend +under this guide's existing semver rule. An explicit `image.tag` or +`image.digest` override must select the intended qualified image too. The PHP +Server remains 2.11.8. + +| Backend | Schema step | +| --- | --- | +| SQLite | 14 to 15 | +| PostgreSQL | 15 to 16 | +| MariaDB | 15 to 16 | +| MySQL | 16 to 17 | + +1. Stop every Server replica sharing the database, including replicas outside + this Helm release. Keep the database running. +2. Back up the database and every external payload root, including roots no + longer selected for new uploads. +3. Run the new image's `schema-upgrade` once through the opt-in upgrade hook or + manual Job in [Native schema upgrades](../README.md#native-schema-upgrades). + The hook requires live proof that all Server replicas are stopped. +4. Restart every replica on the same new image and verify readiness, reported + version 3.12.0 and worker registration. + +Startup does not upgrade an older schema automatically. If the step is skipped, +a 3.12.0 pod on the older schema refuses with `native_schema_upgrade_required` +and stays unready; with the default `RollingUpdate` (`maxUnavailable: 0`) the +existing pods keep serving and `--atomic` rolls the release back. Until +`schema-upgrade` has run, rolling back to Chart 2.1.0 is an ordinary Helm +rollback. From 3.9.x or earlier, the same command also applies the intervening +steps below; 3.10.x and 3.11.x share one schema. MySQL and MariaDB can resume +an interrupted upgrade; SQLite and PostgreSQL apply their step transactionally. +After `schema-upgrade`, rolling back requires restoring the pre-upgrade +database and payload storage backup: an older binary, including 3.11.x, refuses +the upgraded database with `native_schema_newer_than_binary`. Objects written +and policy changes made after the upgrade are not in that backup. + +The step adds a nullable payload storage binding and a namespace storage +generation without rewriting existing rows. Each native local external payload +now keeps the root it was admitted under, so reads, retention pruning, +abandoned-upload cleanup and namespace deletion still reach objects after a +namespace storage policy is disabled or moved. Keep every retained root mounted +on the Server pods (`native.storage.existingClaim`, or `server.extraVolumes` +and `server.extraVolumeMounts` for roots outside `/app/storage`) until its +objects and committed deletion records are reclaimed. A missing or substituted +root returns `external_payload_storage_binding_unavailable` (HTTP 409); the +runtime does not recreate an empty root. Objects already stranded by a policy +change under 3.11.x or earlier need the explicit-location repair in +[Objects written before the upgrade](../../../../docs/releases/3.12.0.md#objects-written-before-the-upgrade). + +Server 3.12.0 also adds the read-only open-run version usage query, discovered +only through `capabilities.workflow_version_usage: true`. Worker protocol 1.20, +control plane version 2 and the 3.11.0 redrive rules are unchanged. This chart +does not establish CLI, Waterline or Cloud adoption, and does not resolve +Server #980 or #1204. + +See [Server 3.12.0 release notes](../../../../docs/releases/3.12.0.md). + ### Chart 2.1.0 / Server 3.11.0 (native) Chart 2.1.0 selects native Server 3.11.0. From 3.10.x, no schema step is diff --git a/k8s/helm/durable-workflow/values.yaml b/k8s/helm/durable-workflow/values.yaml index befeed897..5e47c18fc 100644 --- a/k8s/helm/durable-workflow/values.yaml +++ b/k8s/helm/durable-workflow/values.yaml @@ -42,7 +42,7 @@ image: # scripts/ci/sync-source-release.mjs. Do not edit this default. # A tag must match the runtime: 3.x (or latest) for native, 2.x for php. # The chart refuses a mismatch at render time. - tag: "3.11.0" + tag: "3.12.0" # Optional digest pin. When set, takes precedence over tag for change control. # Example: "sha256:abc123..." # The chart cannot see which runtime a digest names. Pin a native digest diff --git a/resources/release/source-release.json b/resources/release/source-release.json index 50104d94a..abf54a463 100644 --- a/resources/release/source-release.json +++ b/resources/release/source-release.json @@ -4,7 +4,7 @@ "version": "2.11.8" }, "helm_chart": { - "version": "2.1.0", - "app_version": "3.11.0" + "version": "3.0.0", + "app_version": "3.12.0" } }