Skip to content

Add one-time move to the versioning override API! #808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shivs11 wants to merge 5 commits into
base: main
Choose a base branch
from
+75 −0
Open

Add one-time move to the versioning override API! #808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
39d3ef8
Add one-time versioning override API
Shivs11 Jun 17, 2026
4766bf7
Rename one-time versioning override type
Shivs11 Jun 17, 2026
f9ce673
Clarify one-time override routing comment
Shivs11 Jun 17, 2026
daa1442
Clarify one-time override completion semantics
Shivs11 Jun 17, 2026
0553ec2
Suppress linter for one-time override field
Shivs11 Jun 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11097,6 +11097,16 @@
}
}
},
"VersioningOverrideOneTimeOverride": {
"type": "object",
"properties": {
"targetDeploymentVersion": {
"$ref": "#/definitions/v1WorkerDeploymentVersion",
"description": "Required. Worker Deployment Version to receive the one-time Workflow Task."
}
},
"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\nFor example, if the target worker reports Pinned, the execution will remain\npinned after this override is cleared. If the target worker reports\nAutoUpgrade, the execution will resume AutoUpgrade routing after this\noverride is cleared.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending."
},
"VersioningOverridePinnedOverride": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -20147,6 +20157,10 @@
"type": "boolean",
"description": "Override the workflow to have AutoUpgrade behavior."
},
"oneTime": {
"$ref": "#/definitions/VersioningOverrideOneTimeOverride",
"description": "Temporarily override workflow task routing to a specific Worker Deployment Version\nuntil one Workflow Task completes there. After completion, the workflow\nexecution's Versioning Behavior and Deployment Version come from the\nworker's completion response."
},
"behavior": {
"$ref": "#/definitions/v1VersioningBehavior",
"description": "Required.\nDeprecated. Use `override`."
Expand Down
33 changes: 33 additions & 0 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18343,6 +18343,16 @@ components:
autoUpgrade:
type: boolean
description: Override the workflow to have AutoUpgrade behavior.
oneTime:
allOf:
- $ref: '#/components/schemas/VersioningOverride_OneTimeOverride'
description: |-
Temporarily override workflow task routing to a specific Worker Deployment Version
until one Workflow Task completes there. After completion, the workflow
execution's Versioning Behavior and Deployment Version come from the
worker's completion response.
(-- api-linter: core::0142::time-field-type=disabled
aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
behavior:
enum:
- VERSIONING_BEHAVIOR_UNSPECIFIED
Expand Down Expand Up @@ -18377,6 +18387,29 @@ components:

Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new
workflows, and cron workflows.
VersioningOverride_OneTimeOverride:
type: object
properties:
targetDeploymentVersion:
allOf:
- $ref: '#/components/schemas/WorkerDeploymentVersion'
description: Required. Worker Deployment Version to receive the one-time Workflow Task.
description: |-
Routes Workflow Tasks for this execution to `target_deployment_version`
until a Workflow Task completes on that version, then clears the override.

This does not force the workflow's normal Versioning Behavior to become
Pinned. After the Workflow Task completes on `target_deployment_version`,
the workflow execution's normal Versioning Behavior and Deployment Version
are taken from the worker's completion response.

For example, if the target worker reports Pinned, the execution will remain
pinned after this override is cleared. If the target worker reports
AutoUpgrade, the execution will resume AutoUpgrade routing after this
override is cleared.

If no Workflow Task completes on `target_deployment_version`, this override
remains pending.
VersioningOverride_PinnedOverride:
type: object
properties:
Expand Down
28 changes: 28 additions & 0 deletions temporal/api/workflow/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -614,6 +614,14 @@ message VersioningOverride {

// Override the workflow to have AutoUpgrade behavior.
bool auto_upgrade = 4;

// Temporarily override workflow task routing to a specific Worker Deployment Version
// until one Workflow Task completes there. After completion, the workflow
// execution's Versioning Behavior and Deployment Version come from the
// worker's completion response.
// (-- api-linter: core::0142::time-field-type=disabled
// aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --)
OneTimeOverride one_time = 5;

@rkannan82 rkannan82 Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have given this naming some more thought. What do you think about?

  • MoveAndKeepDefaultBehavior: this clearly tells the behavior. move to version X, then respect whatever is the default versioning configuration defined in code. It tells this is not sticky unlike PinnedOverride where it moves to version X and stays put.

  • Also add the following to the comment:
    When you moves the wf from version x to y, and a new version z arrives.

    • if a workflow is pinned, it will stay on the y
    • if wf is auto upgrade -- it will move to z
    • if wf uses upgrade on can -- it will move to z when can happens

  • Personally, I would avoid using temporary.

@Shivs11 Shivs11 Jun 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I quite like the model that you took when naming this, however, the only thing that bothers me is the word "Default" -- the thing is, in worker-versioning, you have two things that could be the "Default" for the true versioning behaviour of a workflow; they are:

  • The workflow annotation on the workflow type
  • The default workflow behaviour on the worker that is assigned to execute this workflow

When you have a versioning behaviour that is defined on the workflow type, that's the behaviour that is always followed.

Having said that, here are some of the things that came to my head the second I read your suggestion:

  • What do we mean by "Default Behaviour" here? I have a feeling that an operator might could get confused thinking about which specific behaviour (workflow type annotation, worker registration) here. I worry that the word is quite overloaded here.
  • I could also see a world where someone could interpret this as: "keep the old/default behavior this workflow had before the move."
  • I am still inclined to using OneTimeOverride only because from the lens of an operator, it portrays the message of moving their workflows one time to a new version. While the after math of this move is subtle, I think we can rely on the operator reading the comments to have a stronger clarity

curious to hear your thoughts on this @rkannan82

}

// Required.
Expand Down Expand Up @@ -647,6 +655,26 @@ message VersioningOverride {
temporal.api.deployment.v1.WorkerDeploymentVersion version = 2;
}

// Routes Workflow Tasks for this execution to `target_deployment_version`
// until a Workflow Task completes on that version, then clears the override.
//
// This does not force the workflow's normal Versioning Behavior to become
// Pinned. After the Workflow Task completes on `target_deployment_version`,
// the workflow execution's normal Versioning Behavior and Deployment Version
// are taken from the worker's completion response.
//
// For example, if the target worker reports Pinned, the execution will remain
// pinned after this override is cleared. If the target worker reports
// AutoUpgrade, the execution will resume AutoUpgrade routing after this
// override is cleared.
//
// If no Workflow Task completes on `target_deployment_version`, this override
// remains pending.
message OneTimeOverride {
// Required. Worker Deployment Version to receive the one-time Workflow Task.
temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1;
}

enum PinnedOverrideBehavior {
// Unspecified.
PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0;
Expand Down
Loading