Skip to content

Commit 29fc423

Browse files
Shivs11Shivs11
authored
Add one-time move to the versioning override API! (#808)
<!-- Describe what has changed in this PR --> **What changed?** - WISOTT <!-- Tell your future self why have you made these changes --> **Why?** - So that operators can have a versioning override that is not sticky. The idea is that the next task of the workflow execution moves to the target version, after which the behaviour/version of the workflow are dictated by the worker response. <!-- Are there any breaking changes on binary or code level? --> **Breaking changes** - No, since this is a new option that I am adding whose default value is false (it's opt-in) <!-- If this breaks the Server, please provide the Server PR to merge right after this PR was merged. --> **Server PR** - [here](temporalio/temporal#10763)
1 parent 69fa653 commit 29fc423

3 files changed

Lines changed: 91 additions & 3 deletions

File tree

‎openapi/openapiv2.json‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11112,6 +11112,16 @@
1111211112
}
1111311113
}
1111411114
},
11115+
"VersioningOverrideOneTimeOverride": {
11116+
"type": "object",
11117+
"properties": {
11118+
"targetDeploymentVersion": {
11119+
"$ref": "#/definitions/v1WorkerDeploymentVersion",
11120+
"description": "Required. Worker Deployment Version to receive the one-time Workflow Task."
11121+
}
11122+
},
11123+
"description": "Routes Workflow Tasks for this execution to `target_deployment_version`\nuntil a Workflow Task completes on that version, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nExample: if an execution is one-time moved from version X to version Y, and\nversion Z later becomes current:\n- if worker Y reports Pinned, the execution stays on Y;\n- if worker Y reports AutoUpgrade, the execution routes to Z on a future\n Workflow Task;\n- if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,\n the current run stays on Y and the execution can route to Z after\n continue-as-new.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending."
11124+
},
1111511125
"VersioningOverridePinnedOverride": {
1111611126
"type": "object",
1111711127
"properties": {
@@ -20170,12 +20180,16 @@
2017020180
"properties": {
2017120181
"pinned": {
2017220182
"$ref": "#/definitions/VersioningOverridePinnedOverride",
20173-
"description": "Override the workflow to have Pinned behavior."
20183+
"description": "Override the workflow to have Pinned behavior. This is a sticky override:\nWorkflow Tasks continue to route according to this override until it is\nexplicitly removed."
2017420184
},
2017520185
"autoUpgrade": {
2017620186
"type": "boolean",
2017720187
"description": "Override the workflow to have AutoUpgrade behavior."
2017820188
},
20189+
"oneTime": {
20190+
"$ref": "#/definitions/VersioningOverrideOneTimeOverride",
20191+
"description": "Override Workflow Task routing to a specific Worker Deployment Version until\none Workflow Task completes there. After completion, the workflow execution's\nVersioning Behavior and Deployment Version come from the worker's completion\nresponse."
20192+
},
2017920193
"behavior": {
2018020194
"$ref": "#/definitions/v1VersioningBehavior",
2018120195
"description": "Required.\nDeprecated. Use `override`."

‎openapi/openapiv3.yaml‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18362,10 +18362,23 @@ components:
1836218362
pinned:
1836318363
allOf:
1836418364
- $ref: '#/components/schemas/VersioningOverride_PinnedOverride'
18365-
description: Override the workflow to have Pinned behavior.
18365+
description: |-
18366+
Override the workflow to have Pinned behavior. This is a sticky override:
18367+
Workflow Tasks continue to route according to this override until it is
18368+
explicitly removed.
1836618369
autoUpgrade:
1836718370
type: boolean
1836818371
description: Override the workflow to have AutoUpgrade behavior.
18372+
oneTime:
18373+
allOf:
18374+
- $ref: '#/components/schemas/VersioningOverride_OneTimeOverride'
18375+
description: |-
18376+
Override Workflow Task routing to a specific Worker Deployment Version until
18377+
one Workflow Task completes there. After completion, the workflow execution's
18378+
Versioning Behavior and Deployment Version come from the worker's completion
18379+
response.
18380+
(-- api-linter: core::0142::time-field-type=disabled
18381+
aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
1836918382
behavior:
1837018383
enum:
1837118384
- VERSIONING_BEHAVIOR_UNSPECIFIED
@@ -18400,6 +18413,33 @@ components:
1840018413

1840118414
Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new
1840218415
workflows, and cron workflows.
18416+
VersioningOverride_OneTimeOverride:
18417+
type: object
18418+
properties:
18419+
targetDeploymentVersion:
18420+
allOf:
18421+
- $ref: '#/components/schemas/WorkerDeploymentVersion'
18422+
description: Required. Worker Deployment Version to receive the one-time Workflow Task.
18423+
description: |-
18424+
Routes Workflow Tasks for this execution to `target_deployment_version`
18425+
until a Workflow Task completes on that version, then clears the override.
18426+
18427+
This does not force the workflow's normal Versioning Behavior to become
18428+
Pinned. After the Workflow Task completes on `target_deployment_version`,
18429+
the workflow execution's normal Versioning Behavior and Deployment Version
18430+
are taken from the worker's completion response.
18431+
18432+
Example: if an execution is one-time moved from version X to version Y, and
18433+
version Z later becomes current:
18434+
- if worker Y reports Pinned, the execution stays on Y;
18435+
- if worker Y reports AutoUpgrade, the execution routes to Z on a future
18436+
Workflow Task;
18437+
- if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,
18438+
the current run stays on Y and the execution can route to Z after
18439+
continue-as-new.
18440+
18441+
If no Workflow Task completes on `target_deployment_version`, this override
18442+
remains pending.
1840318443
VersioningOverride_PinnedOverride:
1840418444
type: object
1840518445
properties:

‎temporal/api/workflow/v1/message.proto‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -609,11 +609,21 @@ message WorkflowExecutionOptions {
609609
message VersioningOverride {
610610
// Indicates whether to override the workflow to be AutoUpgrade or Pinned.
611611
oneof override {
612-
// Override the workflow to have Pinned behavior.
612+
// Override the workflow to have Pinned behavior. This is a sticky override:
613+
// Workflow Tasks continue to route according to this override until it is
614+
// explicitly removed.
613615
PinnedOverride pinned = 3;
614616

615617
// Override the workflow to have AutoUpgrade behavior.
616618
bool auto_upgrade = 4;
619+
620+
// Override Workflow Task routing to a specific Worker Deployment Version until
621+
// one Workflow Task completes there. After completion, the workflow execution's
622+
// Versioning Behavior and Deployment Version come from the worker's completion
623+
// response.
624+
// (-- api-linter: core::0142::time-field-type=disabled
625+
// aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
626+
OneTimeOverride one_time = 5;
617627
}
618628

619629
// Required.
@@ -647,6 +657,30 @@ message VersioningOverride {
647657
temporal.api.deployment.v1.WorkerDeploymentVersion version = 2;
648658
}
649659

660+
// Routes Workflow Tasks for this execution to `target_deployment_version`
661+
// until a Workflow Task completes on that version, then clears the override.
662+
//
663+
// This does not force the workflow's normal Versioning Behavior to become
664+
// Pinned. After the Workflow Task completes on `target_deployment_version`,
665+
// the workflow execution's normal Versioning Behavior and Deployment Version
666+
// are taken from the worker's completion response.
667+
//
668+
// Example: if an execution is one-time moved from version X to version Y, and
669+
// version Z later becomes current:
670+
// - if worker Y reports Pinned, the execution stays on Y;
671+
// - if worker Y reports AutoUpgrade, the execution routes to Z on a future
672+
// Workflow Task;
673+
// - if worker Y reports Pinned and the workflow uses upgrade-on-continue-as-new,
674+
// the current run stays on Y and the execution can route to Z after
675+
// continue-as-new.
676+
//
677+
// If no Workflow Task completes on `target_deployment_version`, this override
678+
// remains pending.
679+
message OneTimeOverride {
680+
// Required. Worker Deployment Version to receive the one-time Workflow Task.
681+
temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1;
682+
}
683+
650684
enum PinnedOverrideBehavior {
651685
// Unspecified.
652686
PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0;

0 commit comments

Comments
 (0)