From 3c07b1050d70eaa7d4bef8523574d0ae4b24591f Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 25 Apr 2025 17:03:00 -0700 Subject: [PATCH 01/31] prevent misconfiguration of VersioningOverride and add more pinned options --- openapi/openapiv2.json | 33 +++++++++++++++++++++++--- openapi/openapiv3.yaml | 23 ++++++++++++++++-- temporal/api/enums/v1/workflow.proto | 9 +++++++ temporal/api/workflow/v1/message.proto | 13 +++++++++- 4 files changed, 72 insertions(+), 6 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index f62324e59..43e0fb81e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11832,6 +11832,27 @@ ], "default": "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED" }, + "v1PinnedBehaviorOverride": { + "type": "string", + "enum": [ + "PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED", + "PINNED_BEHAVIOR_OVERRIDE_PIN_RUN", + "PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION" + ], + "default": "PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED", + "title": "- PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED: Keep original pinned behavior which might be pin run or execution\n - PINNED_BEHAVIOR_OVERRIDE_PIN_RUN: Pin run to specific version\n - PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION: Pin execution to specific version" + }, + "v1PinnedOverrideBehavior": { + "type": "object", + "properties": { + "type": { + "$ref": "#/definitions/v1PinnedBehaviorOverride" + }, + "version": { + "type": "string" + } + } + }, "v1PollActivityTaskQueueResponse": { "type": "object", "properties": { @@ -14544,17 +14565,23 @@ "v1VersioningOverride": { "type": "object", "properties": { + "pinned": { + "$ref": "#/definitions/v1PinnedOverrideBehavior" + }, + "autoUpgrade": { + "type": "boolean" + }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", - "description": "Required." + "description": "Required.\nDeprecated. Use `type`." }, "deployment": { "$ref": "#/definitions/v1Deployment", - "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `pinned_version`." + "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `type.pinned.version`." }, "pinnedVersion": { "type": "string", - "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\"." + "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `type.pinned.version`." } }, "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 24aa63f88..2f45ab177 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -8953,6 +8953,18 @@ components: attempt: type: integer format: int32 + PinnedOverrideBehavior: + type: object + properties: + type: + enum: + - PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED + - PINNED_BEHAVIOR_OVERRIDE_PIN_RUN + - PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION + type: string + format: enum + version: + type: string PollWorkflowTaskQueueResponse: type: object properties: @@ -11845,13 +11857,19 @@ components: VersioningOverride: type: object properties: + pinned: + $ref: '#/components/schemas/PinnedOverrideBehavior' + autoUpgrade: + type: boolean behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED - VERSIONING_BEHAVIOR_PINNED - VERSIONING_BEHAVIOR_AUTO_UPGRADE type: string - description: Required. + description: |- + Required. + Deprecated. Use `type`. format: enum deployment: allOf: @@ -11859,13 +11877,14 @@ components: description: |- Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. Identifies the worker deployment to pin the workflow to. - Deprecated. Use `pinned_version`. + Deprecated. Use `type.pinned.version`. pinnedVersion: type: string description: |- Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. Identifies the worker deployment version to pin the workflow to, in the format ".". + Deprecated. Use `type.pinned.version`. description: |- Used to override the versioning behavior (and pinned deployment version, if applicable) of a specific workflow execution. If set, takes precedence over the worker-sent values. See diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index d9216c635..8254f865c 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -183,3 +183,12 @@ enum VersioningBehavior { // complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; } + +enum PinnedBehaviorOverride { + // Keep original pinned behavior which might be pin run or execution + PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED = 0; + // Pin run to specific version + PINNED_BEHAVIOR_OVERRIDE_PIN_RUN = 1; + // Pin execution to specific version + PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION = 2; +} diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 590b73d69..bd25221ef 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -531,20 +531,31 @@ message WorkflowExecutionOptions { // `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` // to indicate that it should be mutated. message VersioningOverride { + oneof type { + PinnedOverrideBehavior pinned = 3; + bool auto_upgrade = 4; + } // Required. + // Deprecated. Use `type`. temporal.api.enums.v1.VersioningBehavior behavior = 1; // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. // Identifies the worker deployment to pin the workflow to. - // Deprecated. Use `pinned_version`. + // Deprecated. Use `type.pinned.version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. // Identifies the worker deployment version to pin the workflow to, in the format // ".". + // Deprecated. Use `type.pinned.version`. string pinned_version = 9; } +message PinnedOverrideBehavior { + temporal.api.enums.v1.PinnedBehaviorOverride type = 1; + string version = 2; +} + // When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and // there is already an existing running workflow, OnConflictOptions defines actions to be taken on // the existing running workflow. In this case, it will create a WorkflowExecutionOptionsUpdatedEvent From 50774726905023507e6c75db7efcbedb8a8ee5e9 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 13:08:13 -0700 Subject: [PATCH 02/31] pushing without make proto for feedback --- temporal/api/deployment/v1/message.proto | 47 +++++++++++------- temporal/api/enums/v1/workflow.proto | 9 ---- temporal/api/taskqueue/v1/message.proto | 24 +++++----- temporal/api/workflow/v1/message.proto | 39 ++++++++++----- .../workflowservice/v1/request_response.proto | 48 +++++++++---------- 5 files changed, 92 insertions(+), 75 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index e31c45bb6..fd315e906 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -117,8 +117,7 @@ message DeploymentListInfo { // their first poller arrives to the server. // Experimental. Worker Deployments are experimental and might significantly change in the future. message WorkerDeploymentVersionInfo { - // The fully-qualified string representation of the version, in the form ".". - string version = 1; + WorkerDeploymentVersion version = 1; string deployment_name = 2; google.protobuf.Timestamp create_time = 3; @@ -207,13 +206,29 @@ message WorkerDeploymentInfo { string last_modifier_identity = 5; message WorkerDeploymentVersionSummary { - // The fully-qualified string representation of the version, in the form ".". - string version = 1; + WorkerDeploymentVersion version = 1; google.protobuf.Timestamp create_time = 2; enums.v1.VersionDrainageStatus drainage_status = 3; } } +// A Worker Deployment Version (Version, for short) represents a different +// version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo) +// Version records are created in Temporal server automatically when their +// first poller arrives to the server. +// Experimental. Worker Deployment Versions are experimental and might significantly change in the future. +message WorkerDeploymentVersion { + // A unique identifier for this Version within the Deployment it is a part of. + // Not necessarily unique within the namespace. + // The combination of `deployment_name` and `build_id` uniquely identifies + // this Version within the namespace. + string build_id = 1; + + // Identifies the Worker Deployment this Version is part of. + // Must be unique within the namespace. + string deployment_name = 2; +} + message VersionMetadata { // Arbitrary key-values. map entries = 1; @@ -222,22 +237,22 @@ message VersionMetadata { message RoutingConfig { // Always present. Specifies which Deployment Version should should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. - // Can be one of the following: - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) - string current_version = 1; - // When present, it means the traffic is being shifted from the Current Version to the Ramping - // Version. - // Must always be different from Current Version. Can be one of the following: - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + oneof current_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + bool unversioned = 8; + } + // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. + // Must always be different from Current Version. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - string ramping_version = 2; + oneof ramping_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 9; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + bool unversioned = 10; + } // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 8254f865c..d9216c635 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -183,12 +183,3 @@ enum VersioningBehavior { // complete on the old Version. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; } - -enum PinnedBehaviorOverride { - // Keep original pinned behavior which might be pin run or execution - PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED = 0; - // Pin run to specific version - PINNED_BEHAVIOR_OVERRIDE_PIN_RUN = 1; - // Pin execution to specific version - PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION = 2; -} diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 53ddfec83..63b4c3c87 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -59,22 +59,22 @@ message TaskQueueMetadata { message TaskQueueVersioningInfo { // Always present. Specifies which Deployment Version should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. - // Can be one of the following: - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) - string current_version = 1; - // When present, it means the traffic is being shifted from the Current Version to the Ramping - // Version. - // Must always be different from `current_version`. Can be one of the following: - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + oneof current_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 5; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + bool unversioned = 6; + } + // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. + // Must always be different from `current_version`. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - string ramping_version = 2; + oneof ramping_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + bool unversioned = 8; + } // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index bd25221ef..aa74c64a9 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -171,15 +171,14 @@ message WorkflowExecutionVersioningInfo { // Note that `deployment` is overridden by `versioning_override` if the latter is present. // Deprecated. Use `version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; - // The Worker Deployment Version that completed the last workflow task of this workflow - // execution, in the form ".". + // The Worker Deployment Version that completed the last workflow task of this workflow execution. // Must be present if and only if `behavior` is set. An absent value means no workflow task is // completed, or the workflow is unversioned. // For child workflows of Pinned parents, this will be set to parent's Pinned Version when the // the child starts so that child's first workflow task goes to the same Version as the parent. // Note that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version` // will override this value. - string version = 5; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; // Present if user has set an execution-specific versioning override. This override takes // precedence over SDK-sent `behavior` (and `version` when override is PINNED). An // override can be set when starting a new execution, as well as afterwards by calling the @@ -242,7 +241,7 @@ message DeploymentTransition { message DeploymentVersionTransition { // Required. The target Version of the transition. May be `__unversioned__` which means a // so-far-versioned workflow is transitioning to unversioned workers. - string version = 1; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 1; // Later: safe transition info } @@ -531,29 +530,43 @@ message WorkflowExecutionOptions { // `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` // to indicate that it should be mutated. message VersioningOverride { - oneof type { - PinnedOverrideBehavior pinned = 3; + // Indicates whether to override the workflow to be AutoUpgrade or Pinned. + oneof override { + // Send the next workflow task to the Version specified in the override. + PinnedOverride pinned = 3; + // Send the next workflow task to the Current Deployment Version + // of its Task Queue when the next workflow task is dispatched. bool auto_upgrade = 4; } // Required. - // Deprecated. Use `type`. + // Deprecated. Use `override`. temporal.api.enums.v1.VersioningBehavior behavior = 1; // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. // Identifies the worker deployment to pin the workflow to. - // Deprecated. Use `type.pinned.version`. + // Deprecated. Use `override.pinned.version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; // Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. // Identifies the worker deployment version to pin the workflow to, in the format // ".". - // Deprecated. Use `type.pinned.version`. + // Deprecated. Use `override.pinned.version`. string pinned_version = 9; -} -message PinnedOverrideBehavior { - temporal.api.enums.v1.PinnedBehaviorOverride type = 1; - string version = 2; + message PinnedOverride { + PinnedOverrideBehavior type = 1; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + } + + enum PinnedOverrideBehavior { + // If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior. + // If original behavior is AutoUpgrade, override behavior to Pinned. + PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED = 0; + // Override workflow behavior to be Pinned. + PINNED_BEHAVIOR_OVERRIDE_PINNED = 1; + // Override workflow behavior to be PinnedUntilContinueAsNew. + PINNED_BEHAVIOR_OVERRIDE_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + } } // When StartWorkflowExecution uses the conflict policy WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING and diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 86750d258..434a04d14 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1966,8 +1966,7 @@ message DescribeDeploymentResponse { message DescribeWorkerDeploymentVersionRequest { string namespace = 1; - // Deployment Version identifier in the form ".". - string version = 2; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } message DescribeWorkerDeploymentVersionResponse { @@ -2023,12 +2022,11 @@ message SetCurrentDeploymentResponse { // Set/unset the Current Version of a Worker Deployment. message SetWorkerDeploymentCurrentVersionRequest { string namespace = 1; - string deployment_name = 2; - // Required. Can be one of the following: - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - string version = 3; + // Required. + oneof version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + string unversioned_deployment_name = 8; + }; // Optional. This can be the value of conflict_token from a Describe, or another Worker // Deployment API. Passing a non-nil conflict token will cause this request to fail if the // Deployment's configuration has been modified between the API call that generated the @@ -2057,21 +2055,21 @@ message SetWorkerDeploymentCurrentVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // The version that was current before executing this operation, in the form - // ".". Can also be the `__unversioned__` special value. - string previous_version = 2; + // The version that was current before executing this operation. + oneof previous_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 3; + bool unversioned = 4; + }; } // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. message SetWorkerDeploymentRampingVersionRequest { string namespace = 1; - string deployment_name = 2; - // Can be one of the following: - // - Absent/empty value to unset the Ramping Version. Must be paired with `percentage=0`. - // - A Deployment Version identifier in the form ".". - // - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - // with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - string version = 3; + // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. + oneof version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 8; + string unversioned_deployment_name = 9; + }; // Ramp percentage to set. Valid range: [0,100]. float percentage = 4; @@ -2106,9 +2104,11 @@ message SetWorkerDeploymentRampingVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // The version that was ramping before executing this operation, in the form - // ".". Can also be the `__unversioned__` special value. - string previous_version = 2; + // The version that was ramping before executing this operation. + oneof previous_version { + temporal.api.deployment.v1.WorkerDeploymentVersion v = 4; + bool unversioned = 5; + }; // The ramping version percentage before executing this operation. float previous_percentage = 3; } @@ -2141,8 +2141,7 @@ message ListWorkerDeploymentsResponse { // can be skipped by passing `skip-drainage=true`. message DeleteWorkerDeploymentVersionRequest { string namespace = 1; - // Deployment Version identifier in the form ".". - string version = 2; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; // Pass to force deletion even if the Version is draining. In this case the open pinned // workflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions. bool skip_drainage = 3; @@ -2168,8 +2167,7 @@ message DeleteWorkerDeploymentResponse { // Used to update the user-defined metadata of a Worker Deployment Version. message UpdateWorkerDeploymentVersionMetadataRequest { string namespace = 1; - // Deployment Version identifier in the form ".". - string version = 2; + temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; map upsert_entries = 3; // List of keys to remove from the metadata. repeated string remove_entries = 4; From 56c61ba8a9340fab229292626dd54630d630f324 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 13:18:24 -0700 Subject: [PATCH 03/31] stash --- temporal/api/deployment/v1/message.proto | 8 ++++---- temporal/api/taskqueue/v1/message.proto | 8 ++++---- temporal/api/workflow/v1/message.proto | 6 +++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index fd315e906..58cd64752 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -240,18 +240,18 @@ message RoutingConfig { // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) oneof current_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool unversioned = 8; + bool current_unversioned = 8; } // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. // Must always be different from Current Version. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. oneof ramping_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 9; + temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool unversioned = 10; + bool ramping_unversioned = 10; } // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 63b4c3c87..4cc454e03 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -62,18 +62,18 @@ message TaskQueueVersioningInfo { // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) oneof current_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 5; + temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool unversioned = 6; + bool current_unversioned = 8; } // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. // Must always be different from `current_version`. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. oneof ramping_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool unversioned = 8; + bool ramping_unversioned = 10; } // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index aa74c64a9..be7c18ecc 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -561,11 +561,11 @@ message VersioningOverride { enum PinnedOverrideBehavior { // If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior. // If original behavior is AutoUpgrade, override behavior to Pinned. - PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED = 0; + PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; // Override workflow behavior to be Pinned. - PINNED_BEHAVIOR_OVERRIDE_PINNED = 1; + PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; // Override workflow behavior to be PinnedUntilContinueAsNew. - PINNED_BEHAVIOR_OVERRIDE_PINNED_UNTIL_CONTINUE_AS_NEW = 2; + PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; } } From d0c70f5efccb9a4f664c0bcb492dc1c882539cfc Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 13:41:05 -0700 Subject: [PATCH 04/31] committing without full make proto for feedback --- temporal/api/deployment/v1/message.proto | 15 ++++++- temporal/api/taskqueue/v1/message.proto | 5 +++ .../workflowservice/v1/request_response.proto | 39 +++++++++++++++---- temporal/api/workflowservice/v1/service.proto | 8 ++-- 4 files changed, 54 insertions(+), 13 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 58cd64752..ac34cdbad 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -117,7 +117,10 @@ message DeploymentListInfo { // their first poller arrives to the server. // Experimental. Worker Deployments are experimental and might significantly change in the future. message WorkerDeploymentVersionInfo { - WorkerDeploymentVersion version = 1; + reserved 1; + reserved "version"; + + WorkerDeploymentVersion deployment_version = 11; string deployment_name = 2; google.protobuf.Timestamp create_time = 3; @@ -206,7 +209,10 @@ message WorkerDeploymentInfo { string last_modifier_identity = 5; message WorkerDeploymentVersionSummary { - WorkerDeploymentVersion version = 1; + reserved 1; + reserved "version"; + + WorkerDeploymentVersion deployment_version = 4; google.protobuf.Timestamp create_time = 2; enums.v1.VersionDrainageStatus drainage_status = 3; } @@ -235,6 +241,11 @@ message VersionMetadata { } message RoutingConfig { + reserved 1; + reserved "current_version"; + reserved 2; + reserved "ramping_version"; + // Always present. Specifies which Deployment Version should should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 4cc454e03..44fa9ee0a 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -57,6 +57,11 @@ message TaskQueueMetadata { // Experimental. Worker Deployments are experimental and might significantly change in the future. message TaskQueueVersioningInfo { + reserved 1; + reserved "current_version"; + reserved 2; + reserved "ramping_version"; + // Always present. Specifies which Deployment Version should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c1bf203d1..8a99fc461 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1965,8 +1965,11 @@ message DescribeDeploymentResponse { } message DescribeWorkerDeploymentVersionRequest { - string namespace = 1; - temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; + reserved 2; + reserved "version"; + + string namespace = 1; + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; } message DescribeWorkerDeploymentVersionResponse { @@ -2021,9 +2024,14 @@ message SetCurrentDeploymentResponse { // Set/unset the Current Version of a Worker Deployment. message SetWorkerDeploymentCurrentVersionRequest { + reserved 2; + reserved "deployment_name"; + reserved 3; + reserved "version"; + string namespace = 1; // Required. - oneof version { + oneof deployment_version { temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; string unversioned_deployment_name = 8; }; @@ -2051,12 +2059,15 @@ message SetWorkerDeploymentCurrentVersionRequest { } message SetWorkerDeploymentCurrentVersionResponse { + reserved 2; + reserved "previous_version"; + // This value is returned so that it can be optionally passed to APIs // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; // The version that was current before executing this operation. - oneof previous_version { + oneof previous_deployment_version { temporal.api.deployment.v1.WorkerDeploymentVersion v = 3; bool unversioned = 4; }; @@ -2064,6 +2075,11 @@ message SetWorkerDeploymentCurrentVersionResponse { // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. message SetWorkerDeploymentRampingVersionRequest { + reserved 2; + reserved "deployment_name"; + reserved 3; + reserved "version"; + string namespace = 1; // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. oneof version { @@ -2100,12 +2116,15 @@ message SetWorkerDeploymentRampingVersionRequest { } message SetWorkerDeploymentRampingVersionResponse { + reserved 2; + reserved "previous_version"; + // This value is returned so that it can be optionally passed to APIs // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; // The version that was ramping before executing this operation. - oneof previous_version { + oneof previous_deployment_version { temporal.api.deployment.v1.WorkerDeploymentVersion v = 4; bool unversioned = 5; }; @@ -2140,8 +2159,11 @@ message ListWorkerDeploymentsResponse { // - It is not draining (see WorkerDeploymentVersionInfo.drainage_info). This condition // can be skipped by passing `skip-drainage=true`. message DeleteWorkerDeploymentVersionRequest { + reserved 2; + reserved "version"; + string namespace = 1; - temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; // Pass to force deletion even if the Version is draining. In this case the open pinned // workflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions. bool skip_drainage = 3; @@ -2166,8 +2188,11 @@ message DeleteWorkerDeploymentResponse { // Used to update the user-defined metadata of a Worker Deployment Version. message UpdateWorkerDeploymentVersionMetadataRequest { + reserved 2; + reserved "version"; + string namespace = 1; - temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; map upsert_entries = 3; // List of keys to remove from the metadata. repeated string remove_entries = 4; diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 18dacc1bf..40f0db7f2 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -789,9 +789,9 @@ service WorkflowService { // Experimental. This API might significantly change or be removed in a future release. rpc DescribeWorkerDeploymentVersion (DescribeWorkerDeploymentVersionRequest) returns (DescribeWorkerDeploymentVersionResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/worker-deployment-versions/{version}" + get: "/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}" additional_bindings { - get: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{version}" + get: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}" } }; } @@ -857,7 +857,7 @@ service WorkflowService { // Version if it is the Version being set as Current. // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentCurrentVersion (SetWorkerDeploymentCurrentVersionRequest) returns (SetWorkerDeploymentCurrentVersionResponse) { - option (google.api.http) = { + option (google.api.http) = { // TODO(carlydf): replace deployment_name with appropriate thing here (how to handle one-of?) post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-current-version" body: "*" additional_bindings { @@ -911,7 +911,7 @@ service WorkflowService { // gradual ramp to unversioned workers too. // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentRampingVersion (SetWorkerDeploymentRampingVersionRequest) returns (SetWorkerDeploymentRampingVersionResponse) { - option (google.api.http) = { + option (google.api.http) = { // TODO(carlydf): replace deployment_name with appropriate thing here (how to handle one-of?) post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-ramping-version" body: "*" additional_bindings { From e8ee98b8c65408c47ab0ed5276092c0bd5d0a381 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 13:51:34 -0700 Subject: [PATCH 05/31] make names more consistent --- temporal/api/deployment/v1/message.proto | 4 ++-- temporal/api/taskqueue/v1/message.proto | 4 ++-- .../workflowservice/v1/request_response.proto | 16 ++++++++-------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index ac34cdbad..8bf9adb90 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -250,7 +250,7 @@ message RoutingConfig { // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) - oneof current_version { + oneof current { temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool current_unversioned = 8; @@ -259,7 +259,7 @@ message RoutingConfig { // Must always be different from Current Version. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - oneof ramping_version { + oneof ramping { temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool ramping_unversioned = 10; diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 44fa9ee0a..e46344588 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -66,7 +66,7 @@ message TaskQueueVersioningInfo { // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) - oneof current_version { + oneof current { temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool current_unversioned = 8; @@ -75,7 +75,7 @@ message TaskQueueVersioningInfo { // Must always be different from `current_version`. // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - oneof ramping_version { + oneof ramping { temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool ramping_unversioned = 10; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 8a99fc461..6bb69373a 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2031,8 +2031,8 @@ message SetWorkerDeploymentCurrentVersionRequest { string namespace = 1; // Required. - oneof deployment_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 7; + oneof current { + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; string unversioned_deployment_name = 8; }; // Optional. This can be the value of conflict_token from a Describe, or another Worker @@ -2067,8 +2067,8 @@ message SetWorkerDeploymentCurrentVersionResponse { // did not change between this API call and a future write. bytes conflict_token = 1; // The version that was current before executing this operation. - oneof previous_deployment_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 3; + oneof previous_current { + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; bool unversioned = 4; }; } @@ -2082,8 +2082,8 @@ message SetWorkerDeploymentRampingVersionRequest { string namespace = 1; // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. - oneof version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 8; + oneof ramping { + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8; string unversioned_deployment_name = 9; }; // Ramp percentage to set. Valid range: [0,100]. @@ -2124,8 +2124,8 @@ message SetWorkerDeploymentRampingVersionResponse { // did not change between this API call and a future write. bytes conflict_token = 1; // The version that was ramping before executing this operation. - oneof previous_deployment_version { - temporal.api.deployment.v1.WorkerDeploymentVersion v = 4; + oneof previous_ramping { + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4; bool unversioned = 5; }; // The ramping version percentage before executing this operation. From 60a9f0bcf1c98e8d301c86eaf13c545c7f0e420c Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:12:08 -0700 Subject: [PATCH 06/31] make proto --- openapi/openapiv2.json | 402 ++++++++------- openapi/openapiv3.yaml | 487 ++++++++++-------- temporal/api/workflowservice/v1/service.proto | 20 +- 3 files changed, 510 insertions(+), 399 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index a0c89fbb0..5647e3fec 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1732,7 +1732,7 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployment-versions/{version}": { + "/api/v1/namespaces/{namespace}/worker-deployment-versions/{deploymentVersion.deploymentName}/{deploymentVersion.buildId}": { "get": { "summary": "Describes a worker deployment version.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "DescribeWorkerDeploymentVersion2", @@ -1758,8 +1758,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -1794,8 +1801,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -1820,7 +1834,7 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata": { + "/api/v1/namespaces/{namespace}/worker-deployment-versions/{deploymentVersion.deploymentName}/{deploymentVersion.buildId}/update-metadata": { "post": { "summary": "Updates the user-given metadata attached to a Worker Deployment Version.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "UpdateWorkerDeploymentVersionMetadata2", @@ -1846,8 +1860,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -1911,15 +1932,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}": { - "get": { - "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DescribeWorkerDeployment2", + "/api/v1/namespaces/{namespace}/worker-deployments/set-current-version": { + "post": { + "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentCurrentVersion2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" } }, "default": { @@ -1937,24 +1958,28 @@ "type": "string" }, { - "name": "deploymentName", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" + } } ], "tags": [ "WorkflowService" ] - }, - "delete": { - "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DeleteWorkerDeployment2", + } + }, + "/api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version": { + "post": { + "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentRampingVersion2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" } }, "default": { @@ -1972,17 +1997,12 @@ "type": "string" }, { - "name": "deploymentName", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "identity", - "description": "Optional. The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" + } } ], "tags": [ @@ -1990,15 +2010,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version": { - "post": { - "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentCurrentVersion2", + "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}": { + "get": { + "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeWorkerDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" + "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" } }, "default": { @@ -2020,30 +2040,20 @@ "in": "path", "required": true, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" - } } ], "tags": [ "WorkflowService" ] - } - }, - "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": { - "post": { - "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentRampingVersion2", + }, + "delete": { + "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DeleteWorkerDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" + "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" } }, "default": { @@ -2067,12 +2077,11 @@ "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" - } + "name": "identity", + "description": "Optional. The identity of the client who initiated this request.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5206,7 +5215,7 @@ ] } }, - "/namespaces/{namespace}/worker-deployment-versions/{version}": { + "/namespaces/{namespace}/worker-deployment-versions/{deploymentVersion.deploymentName}/{deploymentVersion.buildId}": { "get": { "summary": "Describes a worker deployment version.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "DescribeWorkerDeploymentVersion", @@ -5232,8 +5241,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -5268,8 +5284,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -5294,7 +5317,7 @@ ] } }, - "/namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata": { + "/namespaces/{namespace}/worker-deployment-versions/{deploymentVersion.deploymentName}/{deploymentVersion.buildId}/update-metadata": { "post": { "summary": "Updates the user-given metadata attached to a Worker Deployment Version.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "UpdateWorkerDeploymentVersionMetadata", @@ -5320,8 +5343,15 @@ "type": "string" }, { - "name": "version", - "description": "Deployment Version identifier in the form \".\".", + "name": "deploymentVersion.deploymentName", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deploymentVersion.buildId", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", "in": "path", "required": true, "type": "string" @@ -5385,15 +5415,15 @@ ] } }, - "/namespaces/{namespace}/worker-deployments/{deploymentName}": { - "get": { - "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DescribeWorkerDeployment", + "/namespaces/{namespace}/worker-deployments/set-current-version": { + "post": { + "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentCurrentVersion", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" } }, "default": { @@ -5411,24 +5441,28 @@ "type": "string" }, { - "name": "deploymentName", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" + } } ], "tags": [ "WorkflowService" ] - }, - "delete": { - "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DeleteWorkerDeployment", + } + }, + "/namespaces/{namespace}/worker-deployments/set-ramping-version": { + "post": { + "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentRampingVersion", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" } }, "default": { @@ -5446,17 +5480,12 @@ "type": "string" }, { - "name": "deploymentName", - "in": "path", + "name": "body", + "in": "body", "required": true, - "type": "string" - }, - { - "name": "identity", - "description": "Optional. The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" + } } ], "tags": [ @@ -5464,15 +5493,15 @@ ] } }, - "/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version": { - "post": { - "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentCurrentVersion", + "/namespaces/{namespace}/worker-deployments/{deploymentName}": { + "get": { + "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeWorkerDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" + "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" } }, "default": { @@ -5494,30 +5523,20 @@ "in": "path", "required": true, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" - } } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": { - "post": { - "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentRampingVersion", + }, + "delete": { + "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DeleteWorkerDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" + "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" } }, "default": { @@ -5541,12 +5560,11 @@ "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" - } + "name": "identity", + "description": "Optional. The identity of the client who initiated this request.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -6956,12 +6974,32 @@ }, "description": "Replaces the routing rule with the given source Build ID." }, - "WorkerDeploymentInfoWorkerDeploymentVersionSummary": { + "VersioningOverridePinnedOverride": { "type": "object", "properties": { + "type": { + "$ref": "#/definitions/VersioningOverridePinnedOverrideBehavior" + }, "version": { - "type": "string", - "description": "The fully-qualified string representation of the version, in the form \".\"." + "$ref": "#/definitions/v1WorkerDeploymentVersion" + } + } + }, + "VersioningOverridePinnedOverrideBehavior": { + "type": "string", + "enum": [ + "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", + "PINNED_OVERRIDE_BEHAVIOR_PINNED", + "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" + ], + "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", + "description": " - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior.\nIf original behavior is AutoUpgrade, override behavior to Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Override workflow behavior to be PinnedUntilContinueAsNew." + }, + "WorkerDeploymentInfoWorkerDeploymentVersionSummary": { + "type": "object", + "properties": { + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" }, "createTime": { "type": "string", @@ -7512,9 +7550,11 @@ "WorkflowServiceSetWorkerDeploymentCurrentVersionBody": { "type": "object", "properties": { - "version": { - "type": "string", - "title": "Required. Can be one of the following:\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "unversionedDeploymentName": { + "type": "string" }, "conflictToken": { "type": "string", @@ -7535,9 +7575,11 @@ "WorkflowServiceSetWorkerDeploymentRampingVersionBody": { "type": "object", "properties": { - "version": { - "type": "string", - "title": "Can be one of the following:\n- Absent/empty value to unset the Ramping Version. Must be paired with `percentage=0`.\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "unversionedDeploymentName": { + "type": "string" }, "percentage": { "type": "number", @@ -8043,6 +8085,10 @@ "WorkflowServiceUpdateWorkerDeploymentVersionMetadataBody": { "type": "object", "properties": { + "deploymentVersion": { + "type": "object", + "description": "A Worker Deployment Version (Version, for short) represents a different\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." + }, "upsertEntries": { "type": "object", "additionalProperties": { @@ -9700,7 +9746,7 @@ "type": "object", "properties": { "version": { - "type": "string", + "$ref": "#/definitions/v1WorkerDeploymentVersion", "description": "Required. The target Version of the transition. May be `__unversioned__` which means a\nso-far-versioned workflow is transitioning to unversioned workers." } }, @@ -11857,27 +11903,6 @@ ], "default": "PENDING_WORKFLOW_TASK_STATE_UNSPECIFIED" }, - "v1PinnedBehaviorOverride": { - "type": "string", - "enum": [ - "PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED", - "PINNED_BEHAVIOR_OVERRIDE_PIN_RUN", - "PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION" - ], - "default": "PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED", - "title": "- PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED: Keep original pinned behavior which might be pin run or execution\n - PINNED_BEHAVIOR_OVERRIDE_PIN_RUN: Pin run to specific version\n - PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION: Pin execution to specific version" - }, - "v1PinnedOverrideBehavior": { - "type": "object", - "properties": { - "type": { - "$ref": "#/definitions/v1PinnedBehaviorOverride" - }, - "version": { - "type": "string" - } - } - }, "v1PollActivityTaskQueueResponse": { "type": "object", "properties": { @@ -12744,13 +12769,19 @@ "v1RoutingConfig": { "type": "object", "properties": { - "currentVersion": { - "type": "string", - "title": "Always present. Specifies which Deployment Version should should receive new workflow\nexecutions and tasks of existing unversioned or AutoUpgrade workflows.\nCan be one of the following:\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set (see `ramping_version`.)" + "currentDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" }, - "rampingVersion": { - "type": "string", - "description": "When present, it means the traffic is being shifted from the Current Version to the Ramping\nVersion.\nMust always be different from Current Version. Can be one of the following:\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." + "currentUnversioned": { + "type": "boolean", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + }, + "rampingDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "rampingUnversioned": { + "type": "boolean", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "rampingVersionPercentage": { "type": "number", @@ -13239,9 +13270,11 @@ "format": "byte", "description": "This value is returned so that it can be optionally passed to APIs\nthat write to the Worker Deployment state to ensure that the state\ndid not change between this API call and a future write." }, - "previousVersion": { - "type": "string", - "description": "The version that was current before executing this operation, in the form\n\".\". Can also be the `__unversioned__` special value." + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "unversioned": { + "type": "boolean" } } }, @@ -13253,9 +13286,11 @@ "format": "byte", "description": "This value is returned so that it can be optionally passed to APIs\nthat write to the Worker Deployment state to ensure that the state\ndid not change between this API call and a future write." }, - "previousVersion": { - "type": "string", - "description": "The version that was ramping before executing this operation, in the form\n\".\". Can also be the `__unversioned__` special value." + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "unversioned": { + "type": "boolean" }, "previousPercentage": { "type": "number", @@ -14097,13 +14132,19 @@ "v1TaskQueueVersioningInfo": { "type": "object", "properties": { - "currentVersion": { - "type": "string", - "title": "Always present. Specifies which Deployment Version should receive new workflow\nexecutions and tasks of existing unversioned or AutoUpgrade workflows.\nCan be one of the following:\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set (see `ramping_version`.)" + "currentDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" }, - "rampingVersion": { - "type": "string", - "description": "When present, it means the traffic is being shifted from the Current Version to the Ramping\nVersion.\nMust always be different from `current_version`. Can be one of the following:\n- A Deployment Version identifier in the form \".\".\n- Or, the \"__unversioned__\" special value, to represent all the unversioned workers (those\n with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." + "currentUnversioned": { + "type": "boolean", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + }, + "rampingDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "rampingUnversioned": { + "type": "boolean", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "rampingVersionPercentage": { "type": "number", @@ -14591,22 +14632,24 @@ "type": "object", "properties": { "pinned": { - "$ref": "#/definitions/v1PinnedOverrideBehavior" + "$ref": "#/definitions/VersioningOverridePinnedOverride", + "description": "Send the next workflow task to the Version specified in the override." }, "autoUpgrade": { - "type": "boolean" + "type": "boolean", + "description": "Send the next workflow task to the Current Deployment Version\nof its Task Queue when the next workflow task is dispatched." }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", - "description": "Required.\nDeprecated. Use `type`." + "description": "Required.\nDeprecated. Use `override`." }, "deployment": { "$ref": "#/definitions/v1Deployment", - "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `type.pinned.version`." + "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the worker deployment to pin the workflow to.\nDeprecated. Use `override.pinned.version`." }, "pinnedVersion": { "type": "string", - "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `type.pinned.version`." + "description": "Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`.\nIdentifies the worker deployment version to pin the workflow to, in the format\n\".\".\nDeprecated. Use `override.pinned.version`." } }, "description": "Used to override the versioning behavior (and pinned deployment version, if applicable) of a\nspecific workflow execution. If set, takes precedence over the worker-sent values. See\n`WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call\n`UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask`\nto indicate that it should be mutated." @@ -14668,12 +14711,25 @@ }, "description": "Worker Deployment options set in SDK that need to be sent to server in every poll.\nExperimental. Worker Deployments are experimental and might significantly change in the future." }, - "v1WorkerDeploymentVersionInfo": { + "v1WorkerDeploymentVersion": { "type": "object", "properties": { - "version": { + "buildId": { "type": "string", - "description": "The fully-qualified string representation of the version, in the form \".\"." + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace." + }, + "deploymentName": { + "type": "string", + "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace." + } + }, + "description": "A Worker Deployment Version (Version, for short) represents a different\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." + }, + "v1WorkerDeploymentVersionInfo": { + "type": "object", + "properties": { + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" }, "deploymentName": { "type": "string" @@ -15413,8 +15469,8 @@ "description": "The worker deployment that completed the last workflow task of this workflow execution. Must\nbe present if `behavior` is set. Absent value means no workflow task is completed, or the\nlast workflow task was completed by an unversioned worker. Unversioned workers may still send\na deployment value which will be stored here, so the right way to check if an execution is\nversioned if an execution is versioned or not is via the `behavior` field.\nNote that `deployment` is overridden by `versioning_override` if the latter is present.\nDeprecated. Use `version`." }, "version": { - "type": "string", - "description": "The Worker Deployment Version that completed the last workflow task of this workflow\nexecution, in the form \".\".\nMust be present if and only if `behavior` is set. An absent value means no workflow task is\ncompleted, or the workflow is unversioned.\nFor child workflows of Pinned parents, this will be set to parent's Pinned Version when the\nthe child starts so that child's first workflow task goes to the same Version as the parent.\nNote that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version`\nwill override this value." + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version that completed the last workflow task of this workflow execution.\nMust be present if and only if `behavior` is set. An absent value means no workflow task is\ncompleted, or the workflow is unversioned.\nFor child workflows of Pinned parents, this will be set to parent's Pinned Version when the\nthe child starts so that child's first workflow task goes to the same Version as the parent.\nNote that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version`\nwill override this value." }, "versioningOverride": { "$ref": "#/definitions/v1VersioningOverride", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b09ba605a..c27019d7b 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1537,7 +1537,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployment-versions/{version}: + /api/v1/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}: get: tags: - WorkflowService @@ -1551,12 +1551,32 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name + in: path + required: true + schema: + type: string + - name: deployment_version.build_id in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string + - name: deploymentVersion.buildId + in: query + description: |- + A unique identifier for this Version within the Deployment it is a part of. + Not necessarily unique within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies + this Version within the namespace. + schema: + type: string + - name: deploymentVersion.deploymentName + in: query + description: |- + Identifies the Worker Deployment this Version is part of. + Must be unique within the namespace. + schema: + type: string responses: "200": description: OK @@ -1588,12 +1608,32 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string + - name: deployment_version.build_id + in: path + required: true + schema: + type: string + - name: deploymentVersion.buildId + in: query + description: |- + A unique identifier for this Version within the Deployment it is a part of. + Not necessarily unique within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies + this Version within the namespace. + schema: + type: string + - name: deploymentVersion.deploymentName + in: query + description: |- + Identifies the Worker Deployment this Version is part of. + Must be unique within the namespace. + schema: + type: string - name: skipDrainage in: query description: |- @@ -1619,8 +1659,8 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata: - post: + ? /api/v1/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}/update-metadata + : post: tags: - WorkflowService description: |- @@ -1633,9 +1673,13 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name + in: path + required: true + schema: + type: string + - name: deployment_version.build_id in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string @@ -1695,84 +1739,82 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}: - get: + /api/v1/namespaces/{namespace}/worker-deployments/set-current-version: + post: tags: - WorkflowService description: |- - Describes a Worker Deployment. + Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping + Version if it is the Version being set as Current. Experimental. This API might significantly change or be removed in a future release. - operationId: DescribeWorkerDeployment + operationId: SetWorkerDeploymentCurrentVersion parameters: - name: namespace in: path required: true schema: type: string - - name: deploymentName - in: path - required: true - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - delete: + /api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version: + post: tags: - WorkflowService description: |- - Deletes records of (an old) Deployment. A deployment can only be deleted if - it has no Version in it. + Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for + gradual ramp to unversioned workers too. Experimental. This API might significantly change or be removed in a future release. - operationId: DeleteWorkerDeployment + operationId: SetWorkerDeploymentRampingVersion parameters: - name: namespace in: path required: true schema: type: string - - name: deploymentName - in: path - required: true - schema: - type: string - - name: identity - in: query - description: Optional. The identity of the client who initiated this request. - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version: - post: + /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}: + get: tags: - WorkflowService description: |- - Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping - Version if it is the Version being set as Current. + Describes a Worker Deployment. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentCurrentVersion + operationId: DescribeWorkerDeployment parameters: - name: namespace in: path @@ -1784,34 +1826,27 @@ paths: required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' - required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' + $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version: - post: + delete: tags: - WorkflowService description: |- - Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for - gradual ramp to unversioned workers too. + Deletes records of (an old) Deployment. A deployment can only be deleted if + it has no Version in it. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentRampingVersion + operationId: DeleteWorkerDeployment parameters: - name: namespace in: path @@ -1823,19 +1858,18 @@ paths: required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' - required: true + - name: identity + in: query + description: Optional. The identity of the client who initiated this request. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' + $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' default: description: Default error response content: @@ -4624,7 +4658,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployment-versions/{version}: + /namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}: get: tags: - WorkflowService @@ -4638,12 +4672,32 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name + in: path + required: true + schema: + type: string + - name: deployment_version.build_id in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string + - name: deploymentVersion.buildId + in: query + description: |- + A unique identifier for this Version within the Deployment it is a part of. + Not necessarily unique within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies + this Version within the namespace. + schema: + type: string + - name: deploymentVersion.deploymentName + in: query + description: |- + Identifies the Worker Deployment this Version is part of. + Must be unique within the namespace. + schema: + type: string responses: "200": description: OK @@ -4675,12 +4729,32 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name + in: path + required: true + schema: + type: string + - name: deployment_version.build_id in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string + - name: deploymentVersion.buildId + in: query + description: |- + A unique identifier for this Version within the Deployment it is a part of. + Not necessarily unique within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies + this Version within the namespace. + schema: + type: string + - name: deploymentVersion.deploymentName + in: query + description: |- + Identifies the Worker Deployment this Version is part of. + Must be unique within the namespace. + schema: + type: string - name: skipDrainage in: query description: |- @@ -4706,8 +4780,8 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata: - post: + ? /namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}/update-metadata + : post: tags: - WorkflowService description: |- @@ -4720,9 +4794,13 @@ paths: required: true schema: type: string - - name: version + - name: deployment_version.deployment_name + in: path + required: true + schema: + type: string + - name: deployment_version.build_id in: path - description: Deployment Version identifier in the form ".". required: true schema: type: string @@ -4782,84 +4860,82 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/{deploymentName}: - get: + /namespaces/{namespace}/worker-deployments/set-current-version: + post: tags: - WorkflowService description: |- - Describes a Worker Deployment. + Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping + Version if it is the Version being set as Current. Experimental. This API might significantly change or be removed in a future release. - operationId: DescribeWorkerDeployment + operationId: SetWorkerDeploymentCurrentVersion parameters: - name: namespace in: path required: true schema: type: string - - name: deploymentName - in: path - required: true - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - delete: + /namespaces/{namespace}/worker-deployments/set-ramping-version: + post: tags: - WorkflowService description: |- - Deletes records of (an old) Deployment. A deployment can only be deleted if - it has no Version in it. + Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for + gradual ramp to unversioned workers too. Experimental. This API might significantly change or be removed in a future release. - operationId: DeleteWorkerDeployment + operationId: SetWorkerDeploymentRampingVersion parameters: - name: namespace in: path required: true schema: type: string - - name: deploymentName - in: path - required: true - schema: - type: string - - name: identity - in: query - description: Optional. The identity of the client who initiated this request. - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version: - post: + /namespaces/{namespace}/worker-deployments/{deploymentName}: + get: tags: - WorkflowService description: |- - Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping - Version if it is the Version being set as Current. + Describes a Worker Deployment. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentCurrentVersion + operationId: DescribeWorkerDeployment parameters: - name: namespace in: path @@ -4871,34 +4947,27 @@ paths: required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' - required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' + $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version: - post: + delete: tags: - WorkflowService description: |- - Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for - gradual ramp to unversioned workers too. + Deletes records of (an old) Deployment. A deployment can only be deleted if + it has no Version in it. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentRampingVersion + operationId: DeleteWorkerDeployment parameters: - name: namespace in: path @@ -4910,19 +4979,18 @@ paths: required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' - required: true + - name: identity + in: query + description: Optional. The identity of the client who initiated this request. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' + $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' default: description: Default error response content: @@ -7054,7 +7122,8 @@ components: type: object properties: version: - type: string + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- Required. The target Version of the transition. May be `__unversioned__` which means a so-far-versioned workflow is transitioning to unversioned workers. @@ -8972,18 +9041,6 @@ components: attempt: type: integer format: int32 - PinnedOverrideBehavior: - type: object - properties: - type: - enum: - - PINNED_BEHAVIOR_OVERRIDE_UNSPECIFIED - - PINNED_BEHAVIOR_OVERRIDE_PIN_RUN - - PINNED_BEHAVIOR_OVERRIDE_PIN_EXECUTION - type: string - format: enum - version: - type: string PollWorkflowTaskQueueResponse: type: object properties: @@ -9938,28 +9995,16 @@ components: RoutingConfig: type: object properties: - currentVersion: - type: string - description: |- - Always present. Specifies which Deployment Version should should receive new workflow - executions and tasks of existing unversioned or AutoUpgrade workflows. - Can be one of the following: - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - is set (see `ramping_version`.) - rampingVersion: - type: string - description: |- - When present, it means the traffic is being shifted from the Current Version to the Ramping - Version. - Must always be different from Current Version. Can be one of the following: - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note that it is possible to ramp from one Version to another Version, or from unversioned - workers to a particular Version, or from a particular Version to unversioned workers. + currentDeploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + currentUnversioned: + type: boolean + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + rampingDeploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + rampingUnversioned: + type: boolean + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) rampingVersionPercentage: type: number description: |- @@ -10379,15 +10424,10 @@ components: properties: namespace: type: string - deploymentName: - type: string - version: + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + unversionedDeploymentName: type: string - description: |- - Required. Can be one of the following: - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) conflictToken: type: string description: |- @@ -10426,26 +10466,19 @@ components: that write to the Worker Deployment state to ensure that the state did not change between this API call and a future write. format: bytes - previousVersion: - type: string - description: |- - The version that was current before executing this operation, in the form - ".". Can also be the `__unversioned__` special value. + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + unversioned: + type: boolean SetWorkerDeploymentRampingVersionRequest: type: object properties: namespace: type: string - deploymentName: - type: string - version: + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + unversionedDeploymentName: type: string - description: |- - Can be one of the following: - - Absent/empty value to unset the Ramping Version. Must be paired with `percentage=0`. - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) percentage: type: number description: 'Ramp percentage to set. Valid range: [0,100].' @@ -10491,11 +10524,10 @@ components: that write to the Worker Deployment state to ensure that the state did not change between this API call and a future write. format: bytes - previousVersion: - type: string - description: |- - The version that was ramping before executing this operation, in the form - ".". Can also be the `__unversioned__` special value. + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + unversioned: + type: boolean previousPercentage: type: number description: The ramping version percentage before executing this operation. @@ -11286,28 +11318,16 @@ components: TaskQueueVersioningInfo: type: object properties: - currentVersion: - type: string - description: |- - Always present. Specifies which Deployment Version should receive new workflow - executions and tasks of existing unversioned or AutoUpgrade workflows. - Can be one of the following: - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - is set (see `ramping_version`.) - rampingVersion: - type: string - description: |- - When present, it means the traffic is being shifted from the Current Version to the Ramping - Version. - Must always be different from `current_version`. Can be one of the following: - - A Deployment Version identifier in the form ".". - - Or, the "__unversioned__" special value, to represent all the unversioned workers (those - with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note that it is possible to ramp from one Version to another Version, or from unversioned - workers to a particular Version, or from a particular Version to unversioned workers. + currentDeploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + currentUnversioned: + type: boolean + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + rampingDeploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + rampingUnversioned: + type: boolean + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) rampingVersionPercentage: type: number description: |- @@ -11676,9 +11696,8 @@ components: properties: namespace: type: string - version: - type: string - description: Deployment Version identifier in the form ".". + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' upsertEntries: type: object additionalProperties: @@ -11877,9 +11896,14 @@ components: type: object properties: pinned: - $ref: '#/components/schemas/PinnedOverrideBehavior' + allOf: + - $ref: '#/components/schemas/VersioningOverride_PinnedOverride' + description: Send the next workflow task to the Version specified in the override. autoUpgrade: type: boolean + description: |- + Send the next workflow task to the Current Deployment Version + of its Task Queue when the next workflow task is dispatched. behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED @@ -11888,7 +11912,7 @@ components: type: string description: |- Required. - Deprecated. Use `type`. + Deprecated. Use `override`. format: enum deployment: allOf: @@ -11896,20 +11920,32 @@ components: description: |- Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. Identifies the worker deployment to pin the workflow to. - Deprecated. Use `type.pinned.version`. + Deprecated. Use `override.pinned.version`. pinnedVersion: type: string description: |- Required if behavior is `PINNED`. Must be absent if behavior is not `PINNED`. Identifies the worker deployment version to pin the workflow to, in the format ".". - Deprecated. Use `type.pinned.version`. + Deprecated. Use `override.pinned.version`. description: |- Used to override the versioning behavior (and pinned deployment version, if applicable) of a specific workflow execution. If set, takes precedence over the worker-sent values. See `WorkflowExecutionInfo.VersioningInfo` for more information. To remove the override, call `UpdateWorkflowExecutionOptions` with a null `VersioningOverride`, and use the `update_mask` to indicate that it should be mutated. + VersioningOverride_PinnedOverride: + type: object + properties: + type: + enum: + - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED + - PINNED_OVERRIDE_BEHAVIOR_PINNED + - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW + type: string + format: enum + version: + $ref: '#/components/schemas/WorkerDeploymentVersion' WaitPolicy: type: object properties: @@ -11954,9 +11990,8 @@ components: WorkerDeploymentInfo_WorkerDeploymentVersionSummary: type: object properties: - version: - type: string - description: The fully-qualified string representation of the version, in the form ".". + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' createTime: type: string format: date-time @@ -11993,12 +12028,32 @@ components: description: |- Worker Deployment options set in SDK that need to be sent to server in every poll. Experimental. Worker Deployments are experimental and might significantly change in the future. - WorkerDeploymentVersionInfo: + WorkerDeploymentVersion: type: object properties: - version: + buildId: + type: string + description: |- + A unique identifier for this Version within the Deployment it is a part of. + Not necessarily unique within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies + this Version within the namespace. + deploymentName: type: string - description: The fully-qualified string representation of the version, in the form ".". + description: |- + Identifies the Worker Deployment this Version is part of. + Must be unique within the namespace. + description: |- + A Worker Deployment Version (Version, for short) represents a different + version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo) + Version records are created in Temporal server automatically when their + first poller arrives to the server. + Experimental. Worker Deployment Versions are experimental and might significantly change in the future. + WorkerDeploymentVersionInfo: + type: object + properties: + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' deploymentName: type: string createTime: @@ -12909,10 +12964,10 @@ components: Note that `deployment` is overridden by `versioning_override` if the latter is present. Deprecated. Use `version`. version: - type: string + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- - The Worker Deployment Version that completed the last workflow task of this workflow - execution, in the form ".". + The Worker Deployment Version that completed the last workflow task of this workflow execution. Must be present if and only if `behavior` is set. An absent value means no workflow task is completed, or the workflow is unversioned. For child workflows of Pinned parents, this will be set to parent's Pinned Version when the diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 40f0db7f2..d9917230c 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -857,11 +857,11 @@ service WorkflowService { // Version if it is the Version being set as Current. // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentCurrentVersion (SetWorkerDeploymentCurrentVersionRequest) returns (SetWorkerDeploymentCurrentVersionResponse) { - option (google.api.http) = { // TODO(carlydf): replace deployment_name with appropriate thing here (how to handle one-of?) - post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-current-version" + option (google.api.http) = { + post: "/namespaces/{namespace}/worker-deployments/set-current-version" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/worker-deployments/{deployment_name}/set-current-version" + post: "/api/v1/namespaces/{namespace}/worker-deployments/set-current-version" body: "*" } }; @@ -900,9 +900,9 @@ service WorkflowService { // Experimental. This API might significantly change or be removed in a future release. rpc DeleteWorkerDeploymentVersion (DeleteWorkerDeploymentVersionRequest) returns (DeleteWorkerDeploymentVersionResponse) { option (google.api.http) = { - delete: "/namespaces/{namespace}/worker-deployment-versions/{version}" + delete: "/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}" additional_bindings { - delete: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{version}" + delete: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}" } }; } @@ -911,11 +911,11 @@ service WorkflowService { // gradual ramp to unversioned workers too. // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentRampingVersion (SetWorkerDeploymentRampingVersionRequest) returns (SetWorkerDeploymentRampingVersionResponse) { - option (google.api.http) = { // TODO(carlydf): replace deployment_name with appropriate thing here (how to handle one-of?) - post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-ramping-version" + option (google.api.http) = { + post: "/namespaces/{namespace}/worker-deployments/set-ramping-version" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/worker-deployments/{deployment_name}/set-ramping-version" + post: "/api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version" body: "*" } }; @@ -936,10 +936,10 @@ service WorkflowService { // Experimental. This API might significantly change or be removed in a future release. rpc UpdateWorkerDeploymentVersionMetadata (UpdateWorkerDeploymentVersionMetadataRequest) returns (UpdateWorkerDeploymentVersionMetadataResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata" + post: "/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}/update-metadata" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{version}/update-metadata" + post: "/api/v1/namespaces/{namespace}/worker-deployment-versions/{deployment_version.deployment_name}/{deployment_version.build_id}/update-metadata" body: "*" } }; From 7e3392d345d23327e4a4ca5f4eea65fc4a51c5b3 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:30:36 -0700 Subject: [PATCH 07/31] deprecate old fields instead of deleting --- openapi/openapiv2.json | 94 ++++++++++++++++++- openapi/openapiv3.yaml | 74 ++++++++++++++- temporal/api/deployment/v1/message.proto | 17 ++-- temporal/api/history/v1/message.proto | 2 +- temporal/api/taskqueue/v1/message.proto | 9 +- temporal/api/workflow/v1/message.proto | 18 +++- .../workflowservice/v1/request_response.proto | 44 ++++----- 7 files changed, 206 insertions(+), 52 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 5647e3fec..049d12e16 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1770,6 +1770,13 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "version", + "description": "Deprecated. Use `deployment_version`.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -1814,6 +1821,13 @@ "required": true, "type": "string" }, + { + "name": "version", + "description": "Deprecated. Use `deployment_version`.", + "in": "query", + "required": false, + "type": "string" + }, { "name": "skipDrainage", "description": "Pass to force deletion even if the Version is draining. In this case the open pinned\nworkflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions.", @@ -5253,6 +5267,13 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "version", + "description": "Deprecated. Use `deployment_version`.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5297,6 +5318,13 @@ "required": true, "type": "string" }, + { + "name": "version", + "description": "Deprecated. Use `deployment_version`.", + "in": "query", + "required": false, + "type": "string" + }, { "name": "skipDrainage", "description": "Pass to force deletion even if the Version is draining. In this case the open pinned\nworkflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions.", @@ -6998,6 +7026,10 @@ "WorkerDeploymentInfoWorkerDeploymentVersionSummary": { "type": "object", "properties": { + "version": { + "type": "string", + "description": "Deprecated. Use `deployment_version`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -7550,6 +7582,14 @@ "WorkflowServiceSetWorkerDeploymentCurrentVersionBody": { "type": "object", "properties": { + "deploymentName": { + "type": "string", + "description": "Deprecated. Use `current`." + }, + "version": { + "type": "string", + "description": "Deprecated. Use `current`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -7575,6 +7615,14 @@ "WorkflowServiceSetWorkerDeploymentRampingVersionBody": { "type": "object", "properties": { + "deploymentName": { + "type": "string", + "description": "Deprecated. Use `ramping`." + }, + "version": { + "type": "string", + "description": "Deprecated. Use `ramping`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -8085,6 +8133,10 @@ "WorkflowServiceUpdateWorkerDeploymentVersionMetadataBody": { "type": "object", "properties": { + "version": { + "type": "string", + "description": "Deprecated. Use `deployment_version`." + }, "deploymentVersion": { "type": "object", "description": "A Worker Deployment Version (Version, for short) represents a different\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." @@ -9746,8 +9798,14 @@ "type": "object", "properties": { "version": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Required. The target Version of the transition. May be `__unversioned__` which means a\nso-far-versioned workflow is transitioning to unversioned workers." + "type": "string", + "description": "Deprecated. Use `target`." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion" + }, + "unversioned": { + "type": "boolean" } }, "description": "Holds information about ongoing transition of a workflow execution from one worker\ndeployment version to another.\nExperimental. Might change in the future." @@ -12776,6 +12834,10 @@ "type": "boolean", "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, + "currentVersion": { + "type": "string", + "description": "Deprecated. Use `current`." + }, "rampingDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -12783,6 +12845,10 @@ "type": "boolean", "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, + "rampingVersion": { + "type": "string", + "description": "Deprecated. Use `ramping`." + }, "rampingVersionPercentage": { "type": "number", "format": "float", @@ -13270,6 +13336,10 @@ "format": "byte", "description": "This value is returned so that it can be optionally passed to APIs\nthat write to the Worker Deployment state to ensure that the state\ndid not change between this API call and a future write." }, + "previousVersion": { + "type": "string", + "description": "Deprecated. Use `previous_current`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -13286,6 +13356,10 @@ "format": "byte", "description": "This value is returned so that it can be optionally passed to APIs\nthat write to the Worker Deployment state to ensure that the state\ndid not change between this API call and a future write." }, + "previousVersion": { + "type": "string", + "description": "Deprecated. Use `previous_ramping`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -14139,6 +14213,10 @@ "type": "boolean", "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, + "currentVersion": { + "type": "string", + "description": "Deprecated. Use `current`." + }, "rampingDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -14146,6 +14224,10 @@ "type": "boolean", "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, + "rampingVersion": { + "type": "string", + "description": "Deprecated. Use `ramping`." + }, "rampingVersionPercentage": { "type": "number", "format": "float", @@ -14728,6 +14810,10 @@ "v1WorkerDeploymentVersionInfo": { "type": "object", "properties": { + "version": { + "type": "string", + "description": "Deprecated. Use `deployment_version`." + }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" }, @@ -15469,6 +15555,10 @@ "description": "The worker deployment that completed the last workflow task of this workflow execution. Must\nbe present if `behavior` is set. Absent value means no workflow task is completed, or the\nlast workflow task was completed by an unversioned worker. Unversioned workers may still send\na deployment value which will be stored here, so the right way to check if an execution is\nversioned if an execution is versioned or not is via the `behavior` field.\nNote that `deployment` is overridden by `versioning_override` if the latter is present.\nDeprecated. Use `version`." }, "version": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Deprecated. Use `deployment_version`." + }, + "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", "description": "The Worker Deployment Version that completed the last workflow task of this workflow execution.\nMust be present if and only if `behavior` is set. An absent value means no workflow task is\ncompleted, or the workflow is unversioned.\nFor child workflows of Pinned parents, this will be set to parent's Pinned Version when the\nthe child starts so that child's first workflow task goes to the same Version as the parent.\nNote that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version`\nwill override this value." }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index c27019d7b..5ba617540 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1561,6 +1561,11 @@ paths: required: true schema: type: string + - name: version + in: query + description: Deprecated. Use `deployment_version`. + schema: + type: string - name: deploymentVersion.buildId in: query description: |- @@ -1618,6 +1623,11 @@ paths: required: true schema: type: string + - name: version + in: query + description: Deprecated. Use `deployment_version`. + schema: + type: string - name: deploymentVersion.buildId in: query description: |- @@ -4682,6 +4692,11 @@ paths: required: true schema: type: string + - name: version + in: query + description: Deprecated. Use `deployment_version`. + schema: + type: string - name: deploymentVersion.buildId in: query description: |- @@ -4739,6 +4754,11 @@ paths: required: true schema: type: string + - name: version + in: query + description: Deprecated. Use `deployment_version`. + schema: + type: string - name: deploymentVersion.buildId in: query description: |- @@ -7122,11 +7142,12 @@ components: type: object properties: version: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - Required. The target Version of the transition. May be `__unversioned__` which means a - so-far-versioned workflow is transitioning to unversioned workers. + type: string + description: Deprecated. Use `target`. + deploymentVersion: + $ref: '#/components/schemas/WorkerDeploymentVersion' + unversioned: + type: boolean description: |- Holds information about ongoing transition of a workflow execution from one worker deployment version to another. @@ -10000,11 +10021,17 @@ components: currentUnversioned: type: boolean description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + currentVersion: + type: string + description: Deprecated. Use `current`. rampingDeploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' rampingUnversioned: type: boolean description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + rampingVersion: + type: string + description: Deprecated. Use `ramping`. rampingVersionPercentage: type: number description: |- @@ -10424,6 +10451,12 @@ components: properties: namespace: type: string + deploymentName: + type: string + description: Deprecated. Use `current`. + version: + type: string + description: Deprecated. Use `current`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: @@ -10466,6 +10499,9 @@ components: that write to the Worker Deployment state to ensure that the state did not change between this API call and a future write. format: bytes + previousVersion: + type: string + description: Deprecated. Use `previous_current`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversioned: @@ -10475,6 +10511,12 @@ components: properties: namespace: type: string + deploymentName: + type: string + description: Deprecated. Use `ramping`. + version: + type: string + description: Deprecated. Use `ramping`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: @@ -10524,6 +10566,9 @@ components: that write to the Worker Deployment state to ensure that the state did not change between this API call and a future write. format: bytes + previousVersion: + type: string + description: Deprecated. Use `previous_ramping`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversioned: @@ -11323,11 +11368,17 @@ components: currentUnversioned: type: boolean description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + currentVersion: + type: string + description: Deprecated. Use `current`. rampingDeploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' rampingUnversioned: type: boolean description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + rampingVersion: + type: string + description: Deprecated. Use `ramping`. rampingVersionPercentage: type: number description: |- @@ -11696,6 +11747,9 @@ components: properties: namespace: type: string + version: + type: string + description: Deprecated. Use `deployment_version`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' upsertEntries: @@ -11990,6 +12044,9 @@ components: WorkerDeploymentInfo_WorkerDeploymentVersionSummary: type: object properties: + version: + type: string + description: Deprecated. Use `deployment_version`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' createTime: @@ -12052,6 +12109,9 @@ components: WorkerDeploymentVersionInfo: type: object properties: + version: + type: string + description: Deprecated. Use `deployment_version`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' deploymentName: @@ -12964,6 +13024,10 @@ components: Note that `deployment` is overridden by `versioning_override` if the latter is present. Deprecated. Use `version`. version: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Deprecated. Use `deployment_version`. + deploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 8bf9adb90..f92fe2577 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -117,8 +117,8 @@ message DeploymentListInfo { // their first poller arrives to the server. // Experimental. Worker Deployments are experimental and might significantly change in the future. message WorkerDeploymentVersionInfo { - reserved 1; - reserved "version"; + // Deprecated. Use `deployment_version`. + string version = 1 [deprecated = true]; WorkerDeploymentVersion deployment_version = 11; string deployment_name = 2; @@ -209,8 +209,8 @@ message WorkerDeploymentInfo { string last_modifier_identity = 5; message WorkerDeploymentVersionSummary { - reserved 1; - reserved "version"; + // Deprecated. Use `deployment_version`. + string version = 1 [deprecated = true]; WorkerDeploymentVersion deployment_version = 4; google.protobuf.Timestamp create_time = 2; @@ -241,11 +241,6 @@ message VersionMetadata { } message RoutingConfig { - reserved 1; - reserved "current_version"; - reserved 2; - reserved "ramping_version"; - // Always present. Specifies which Deployment Version should should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp @@ -255,6 +250,8 @@ message RoutingConfig { // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool current_unversioned = 8; } + // Deprecated. Use `current`. + string current_version = 1 [deprecated = true]; // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. // Must always be different from Current Version. // Note that it is possible to ramp from one Version to another Version, or from unversioned @@ -264,6 +261,8 @@ message RoutingConfig { // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool ramping_unversioned = 10; } + // Deprecated. Use `ramping`. + string ramping_version = 2 [deprecated = true]; // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 51ba620c4..2a310467b 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -258,7 +258,7 @@ message WorkflowTaskCompletedEventAttributes { // within is also used as `binary_checksum`, which may be omitted in that case (it may also be // populated to preserve compatibility). // Deprecated. Use `deployment` and `versioning_behavior` instead. - temporal.api.common.v1.WorkerVersionStamp worker_version = 5; + temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; // Data the SDK wishes to record for itself, but server need not interpret, and does not // directly impact workflow state. temporal.api.sdk.v1.WorkflowTaskCompletedMetadata sdk_metadata = 6; diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index e46344588..30c9a3aee 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -57,11 +57,6 @@ message TaskQueueMetadata { // Experimental. Worker Deployments are experimental and might significantly change in the future. message TaskQueueVersioningInfo { - reserved 1; - reserved "current_version"; - reserved 2; - reserved "ramping_version"; - // Always present. Specifies which Deployment Version should receive new workflow // executions and tasks of existing unversioned or AutoUpgrade workflows. // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp @@ -71,6 +66,8 @@ message TaskQueueVersioningInfo { // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool current_unversioned = 8; } + // Deprecated. Use `current`. + string current_version = 1 [deprecated = true]; // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. // Must always be different from `current_version`. // Note that it is possible to ramp from one Version to another Version, or from unversioned @@ -80,6 +77,8 @@ message TaskQueueVersioningInfo { // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) bool ramping_unversioned = 10; } + // Deprecated. Use `ramping`. + string ramping_version = 2 [deprecated = true]; // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index bd789b474..290a5c76e 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -171,6 +171,8 @@ message WorkflowExecutionVersioningInfo { // Note that `deployment` is overridden by `versioning_override` if the latter is present. // Deprecated. Use `version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; + // Deprecated. Use `deployment_version`. + temporal.api.deployment.v1.WorkerDeploymentVersion version = 5 [deprecated = true]; // The Worker Deployment Version that completed the last workflow task of this workflow execution. // Must be present if and only if `behavior` is set. An absent value means no workflow task is // completed, or the workflow is unversioned. @@ -178,7 +180,7 @@ message WorkflowExecutionVersioningInfo { // the child starts so that child's first workflow task goes to the same Version as the parent. // Note that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version` // will override this value. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 5; + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; // Present if user has set an execution-specific versioning override. This override takes // precedence over SDK-sent `behavior` (and `version` when override is PINNED). An // override can be set when starting a new execution, as well as afterwards by calling the @@ -239,9 +241,15 @@ message DeploymentTransition { // deployment version to another. // Experimental. Might change in the future. message DeploymentVersionTransition { - // Required. The target Version of the transition. May be `__unversioned__` which means a + // Deprecated. Use `target`. + string version = 1 [deprecated = true]; + + // Required. The target Version of the transition. If `unversioned`, a // so-far-versioned workflow is transitioning to unversioned workers. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 1; + oneof target { + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 2; + bool unversioned = 3; + } // Later: safe transition info } @@ -551,7 +559,7 @@ message VersioningOverride { } // Required. // Deprecated. Use `override`. - temporal.api.enums.v1.VersioningBehavior behavior = 1; + temporal.api.enums.v1.VersioningBehavior behavior = 1 [deprecated = true]; // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. // Identifies the worker deployment to pin the workflow to. @@ -562,7 +570,7 @@ message VersioningOverride { // Identifies the worker deployment version to pin the workflow to, in the format // ".". // Deprecated. Use `override.pinned.version`. - string pinned_version = 9; + string pinned_version = 9 [deprecated = true]; message PinnedOverride { PinnedOverrideBehavior type = 1; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 6bb69373a..01dea064a 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1965,10 +1965,9 @@ message DescribeDeploymentResponse { } message DescribeWorkerDeploymentVersionRequest { - reserved 2; - reserved "version"; - string namespace = 1; + // Deprecated. Use `deployment_version`. + string version = 2 [deprecated = true]; temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; } @@ -2024,12 +2023,12 @@ message SetCurrentDeploymentResponse { // Set/unset the Current Version of a Worker Deployment. message SetWorkerDeploymentCurrentVersionRequest { - reserved 2; - reserved "deployment_name"; - reserved 3; - reserved "version"; - string namespace = 1; + // Deprecated. Use `current`. + string deployment_name = 2 [deprecated = true]; + // Deprecated. Use `current`. + string version = 3 [deprecated = true]; + // Required. oneof current { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; @@ -2059,13 +2058,12 @@ message SetWorkerDeploymentCurrentVersionRequest { } message SetWorkerDeploymentCurrentVersionResponse { - reserved 2; - reserved "previous_version"; - // This value is returned so that it can be optionally passed to APIs // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; + // Deprecated. Use `previous_current`. + string previous_version = 2 [deprecated = true]; // The version that was current before executing this operation. oneof previous_current { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; @@ -2075,12 +2073,11 @@ message SetWorkerDeploymentCurrentVersionResponse { // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. message SetWorkerDeploymentRampingVersionRequest { - reserved 2; - reserved "deployment_name"; - reserved 3; - reserved "version"; - string namespace = 1; + // Deprecated. Use `ramping`. + string deployment_name = 2 [deprecated = true]; + // Deprecated. Use `ramping`. + string version = 3 [deprecated = true]; // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. oneof ramping { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8; @@ -2116,13 +2113,12 @@ message SetWorkerDeploymentRampingVersionRequest { } message SetWorkerDeploymentRampingVersionResponse { - reserved 2; - reserved "previous_version"; - // This value is returned so that it can be optionally passed to APIs // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; + // Deprecated. Use `previous_ramping`. + string previous_version = 2 [deprecated = true]; // The version that was ramping before executing this operation. oneof previous_ramping { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4; @@ -2159,10 +2155,9 @@ message ListWorkerDeploymentsResponse { // - It is not draining (see WorkerDeploymentVersionInfo.drainage_info). This condition // can be skipped by passing `skip-drainage=true`. message DeleteWorkerDeploymentVersionRequest { - reserved 2; - reserved "version"; - string namespace = 1; + // Deprecated. Use `deployment_version`. + string version = 2 [deprecated = true]; temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; // Pass to force deletion even if the Version is draining. In this case the open pinned // workflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions. @@ -2188,10 +2183,9 @@ message DeleteWorkerDeploymentResponse { // Used to update the user-defined metadata of a Worker Deployment Version. message UpdateWorkerDeploymentVersionMetadataRequest { - reserved 2; - reserved "version"; - string namespace = 1; + // Deprecated. Use `deployment_version`. + string version = 2 [deprecated = true]; temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; map upsert_entries = 3; // List of keys to remove from the metadata. From 7829554e8e5ba9c477671e43b43e0e6c1035c162 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:38:04 -0700 Subject: [PATCH 08/31] restore deleted comments about meaning of unversioned --- openapi/openapiv2.json | 6 ++++-- openapi/openapiv3.yaml | 2 ++ temporal/api/workflowservice/v1/request_response.proto | 2 ++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 049d12e16..d971fe893 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7594,7 +7594,8 @@ "$ref": "#/definitions/v1WorkerDeploymentVersion" }, "unversionedDeploymentName": { - "type": "string" + "type": "string", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "conflictToken": { "type": "string", @@ -7627,7 +7628,8 @@ "$ref": "#/definitions/v1WorkerDeploymentVersion" }, "unversionedDeploymentName": { - "type": "string" + "type": "string", + "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "percentage": { "type": "number", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 5ba617540..a57935002 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10461,6 +10461,7 @@ components: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: type: string + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) conflictToken: type: string description: |- @@ -10521,6 +10522,7 @@ components: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: type: string + description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) percentage: type: number description: 'Ramp percentage to set. Valid range: [0,100].' diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 01dea064a..98b73da8c 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2032,6 +2032,7 @@ message SetWorkerDeploymentCurrentVersionRequest { // Required. oneof current { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string unversioned_deployment_name = 8; }; // Optional. This can be the value of conflict_token from a Describe, or another Worker @@ -2081,6 +2082,7 @@ message SetWorkerDeploymentRampingVersionRequest { // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. oneof ramping { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8; + // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string unversioned_deployment_name = 9; }; // Ramp percentage to set. Valid range: [0,100]. From b808ee1d1f34b2e1371d54584cc7547fab907e76 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:44:24 -0700 Subject: [PATCH 09/31] Update temporal/api/deployment/v1/message.proto Co-authored-by: Spencer Judge --- temporal/api/deployment/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index f92fe2577..3b6a43939 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -218,7 +218,7 @@ message WorkerDeploymentInfo { } } -// A Worker Deployment Version (Version, for short) represents a different +// A Worker Deployment Version (Version, for short) represents a // version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo) // Version records are created in Temporal server automatically when their // first poller arrives to the server. From 8f677794c437a203c2cbb2fcfeb95d6f595b8746 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:44:38 -0700 Subject: [PATCH 10/31] Update temporal/api/workflow/v1/message.proto Co-authored-by: Spencer Judge --- temporal/api/workflow/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 290a5c76e..e408c43f5 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -573,7 +573,7 @@ message VersioningOverride { string pinned_version = 9 [deprecated = true]; message PinnedOverride { - PinnedOverrideBehavior type = 1; + PinnedOverrideBehavior behavior = 1; temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } From 273d580fd2bb17170ee18ba3234fdb4410f6b431 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:44:55 -0700 Subject: [PATCH 11/31] Update temporal/api/workflowservice/v1/request_response.proto Co-authored-by: Spencer Judge --- temporal/api/workflowservice/v1/request_response.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 98b73da8c..cad8d2713 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2066,7 +2066,7 @@ message SetWorkerDeploymentCurrentVersionResponse { // Deprecated. Use `previous_current`. string previous_version = 2 [deprecated = true]; // The version that was current before executing this operation. - oneof previous_current { + oneof replaced_version { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; bool unversioned = 4; }; From 16fa15a5ce1e9984f170e20a30f0dcd1db51907b Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:45:10 -0700 Subject: [PATCH 12/31] Update temporal/api/workflowservice/v1/request_response.proto Co-authored-by: Spencer Judge --- temporal/api/workflowservice/v1/request_response.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index cad8d2713..3f251877c 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2122,7 +2122,7 @@ message SetWorkerDeploymentRampingVersionResponse { // Deprecated. Use `previous_ramping`. string previous_version = 2 [deprecated = true]; // The version that was ramping before executing this operation. - oneof previous_ramping { + oneof replaced_ramping { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4; bool unversioned = 5; }; From 5f1baff7f634312c2f89b48cb45af419e23a329e Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:50:08 -0700 Subject: [PATCH 13/31] explain field --- temporal/api/workflowservice/v1/request_response.proto | 2 ++ 1 file changed, 2 insertions(+) diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 98b73da8c..64249e07a 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2032,6 +2032,7 @@ message SetWorkerDeploymentCurrentVersionRequest { // Required. oneof current { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; + // The name of the Deployment where you want to set Current Version to unversioned. // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string unversioned_deployment_name = 8; }; @@ -2082,6 +2083,7 @@ message SetWorkerDeploymentRampingVersionRequest { // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. oneof ramping { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8; + // The name of the Deployment where you want to set Ramping Version to unversioned. // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string unversioned_deployment_name = 9; }; From 3cd94cb0fa1dfc8648fc4cb12e2b8ef4700978a8 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Tue, 29 Apr 2025 14:55:00 -0700 Subject: [PATCH 14/31] address comments --- openapi/openapiv2.json | 22 +++++++++------- openapi/openapiv3.yaml | 26 +++++++++++++------ temporal/api/workflow/v1/message.proto | 10 ++++--- .../workflowservice/v1/request_response.proto | 6 ++--- 4 files changed, 41 insertions(+), 23 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index d971fe893..cc304e637 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7005,7 +7005,7 @@ "VersioningOverridePinnedOverride": { "type": "object", "properties": { - "type": { + "behavior": { "$ref": "#/definitions/VersioningOverridePinnedOverrideBehavior" }, "version": { @@ -7595,7 +7595,7 @@ }, "unversionedDeploymentName": { "type": "string", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The name of the Deployment where you want to set Current Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "conflictToken": { "type": "string", @@ -7629,7 +7629,7 @@ }, "unversionedDeploymentName": { "type": "string", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The name of the Deployment where you want to set Ramping Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "percentage": { "type": "number", @@ -8141,7 +8141,7 @@ }, "deploymentVersion": { "type": "object", - "description": "A Worker Deployment Version (Version, for short) represents a different\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." + "description": "A Worker Deployment Version (Version, for short) represents a\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." }, "upsertEntries": { "type": "object", @@ -11798,10 +11798,14 @@ }, "lastDeployment": { "$ref": "#/definitions/v1Deployment", - "description": "The deployment this activity was dispatched to most recently. Present only if the activity\nwas dispatched to a versioned worker.\nDeprecated. Use `last_worker_deployment_version`." + "description": "The deployment this activity was dispatched to most recently. Present only if the activity\nwas dispatched to a versioned worker.\nDeprecated. Use `last_deployment_version`." }, "lastWorkerDeploymentVersion": { "type": "string", + "description": "The Worker Deployment Version this activity was dispatched to most recently.\nDeprecated. Use `last_deployment_version`." + }, + "lastDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", "description": "The Worker Deployment Version this activity was dispatched to most recently." }, "priority": { @@ -13340,7 +13344,7 @@ }, "previousVersion": { "type": "string", - "description": "Deprecated. Use `previous_current`." + "description": "Deprecated. Use `replaced_version`." }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" @@ -13360,7 +13364,7 @@ }, "previousVersion": { "type": "string", - "description": "Deprecated. Use `previous_ramping`." + "description": "Deprecated. Use `replaced_version`." }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion" @@ -14807,7 +14811,7 @@ "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace." } }, - "description": "A Worker Deployment Version (Version, for short) represents a different\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." + "description": "A Worker Deployment Version (Version, for short) represents a\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." }, "v1WorkerDeploymentVersionInfo": { "type": "object", @@ -15554,7 +15558,7 @@ }, "deployment": { "$ref": "#/definitions/v1Deployment", - "description": "The worker deployment that completed the last workflow task of this workflow execution. Must\nbe present if `behavior` is set. Absent value means no workflow task is completed, or the\nlast workflow task was completed by an unversioned worker. Unversioned workers may still send\na deployment value which will be stored here, so the right way to check if an execution is\nversioned if an execution is versioned or not is via the `behavior` field.\nNote that `deployment` is overridden by `versioning_override` if the latter is present.\nDeprecated. Use `version`." + "description": "The worker deployment that completed the last workflow task of this workflow execution. Must\nbe present if `behavior` is set. Absent value means no workflow task is completed, or the\nlast workflow task was completed by an unversioned worker. Unversioned workers may still send\na deployment value which will be stored here, so the right way to check if an execution is\nversioned if an execution is versioned or not is via the `behavior` field.\nNote that `deployment` is overridden by `versioning_override` if the latter is present.\nDeprecated. Use `deployment_version`." }, "version": { "$ref": "#/definitions/v1WorkerDeploymentVersion", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index a57935002..5a5d5a20b 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -8917,9 +8917,15 @@ components: description: |- The deployment this activity was dispatched to most recently. Present only if the activity was dispatched to a versioned worker. - Deprecated. Use `last_worker_deployment_version`. + Deprecated. Use `last_deployment_version`. lastWorkerDeploymentVersion: type: string + description: |- + The Worker Deployment Version this activity was dispatched to most recently. + Deprecated. Use `last_deployment_version`. + lastDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' description: The Worker Deployment Version this activity was dispatched to most recently. priority: allOf: @@ -10461,7 +10467,9 @@ components: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: type: string - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + description: |- + The name of the Deployment where you want to set Current Version to unversioned. + Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) conflictToken: type: string description: |- @@ -10502,7 +10510,7 @@ components: format: bytes previousVersion: type: string - description: Deprecated. Use `previous_current`. + description: Deprecated. Use `replaced_version`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversioned: @@ -10522,7 +10530,9 @@ components: $ref: '#/components/schemas/WorkerDeploymentVersion' unversionedDeploymentName: type: string - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + description: |- + The name of the Deployment where you want to set Ramping Version to unversioned. + Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) percentage: type: number description: 'Ramp percentage to set. Valid range: [0,100].' @@ -10570,7 +10580,7 @@ components: format: bytes previousVersion: type: string - description: Deprecated. Use `previous_ramping`. + description: Deprecated. Use `replaced_version`. deploymentVersion: $ref: '#/components/schemas/WorkerDeploymentVersion' unversioned: @@ -11993,7 +12003,7 @@ components: VersioningOverride_PinnedOverride: type: object properties: - type: + behavior: enum: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED @@ -12103,7 +12113,7 @@ components: Identifies the Worker Deployment this Version is part of. Must be unique within the namespace. description: |- - A Worker Deployment Version (Version, for short) represents a different + A Worker Deployment Version (Version, for short) represents a version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo) Version records are created in Temporal server automatically when their first poller arrives to the server. @@ -13024,7 +13034,7 @@ components: a deployment value which will be stored here, so the right way to check if an execution is versioned if an execution is versioned or not is via the `behavior` field. Note that `deployment` is overridden by `versioning_override` if the latter is present. - Deprecated. Use `version`. + Deprecated. Use `deployment_version`. version: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index e408c43f5..67bdf9969 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -169,7 +169,7 @@ message WorkflowExecutionVersioningInfo { // a deployment value which will be stored here, so the right way to check if an execution is // versioned if an execution is versioned or not is via the `behavior` field. // Note that `deployment` is overridden by `versioning_override` if the latter is present. - // Deprecated. Use `version`. + // Deprecated. Use `deployment_version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; // Deprecated. Use `deployment_version`. temporal.api.deployment.v1.WorkerDeploymentVersion version = 5 [deprecated = true]; @@ -311,10 +311,14 @@ message PendingActivityInfo { // The deployment this activity was dispatched to most recently. Present only if the activity // was dispatched to a versioned worker. - // Deprecated. Use `last_worker_deployment_version`. + // Deprecated. Use `last_deployment_version`. temporal.api.deployment.v1.Deployment last_deployment = 20 [deprecated = true]; // The Worker Deployment Version this activity was dispatched to most recently. - string last_worker_deployment_version = 21; + // Deprecated. Use `last_deployment_version`. + string last_worker_deployment_version = 21 [deprecated = true]; + // The Worker Deployment Version this activity was dispatched to most recently. + temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 24; + // Priority metadata temporal.api.common.v1.Priority priority = 22; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 55317e3db..6602e9d82 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2064,7 +2064,7 @@ message SetWorkerDeploymentCurrentVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // Deprecated. Use `previous_current`. + // Deprecated. Use `replaced_version`. string previous_version = 2 [deprecated = true]; // The version that was current before executing this operation. oneof replaced_version { @@ -2121,10 +2121,10 @@ message SetWorkerDeploymentRampingVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // Deprecated. Use `previous_ramping`. + // Deprecated. Use `replaced_version`. string previous_version = 2 [deprecated = true]; // The version that was ramping before executing this operation. - oneof replaced_ramping { + oneof replaced_version { temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4; bool unversioned = 5; }; From 73148ccd5cf3b408c4aa2d5238eda340899e07e0 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 2 May 2025 11:39:16 -0700 Subject: [PATCH 15/31] save --- temporal/api/deployment/v1/message.proto | 27 +++++----- temporal/api/taskqueue/v1/message.proto | 27 +++++----- .../workflowservice/v1/request_response.proto | 49 +++++++------------ temporal/api/workflowservice/v1/service.proto | 8 +-- 4 files changed, 47 insertions(+), 64 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 3b6a43939..6ccecf90f 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -241,31 +241,28 @@ message VersionMetadata { } message RoutingConfig { - // Always present. Specifies which Deployment Version should should receive new workflow - // executions and tasks of existing unversioned or AutoUpgrade workflows. + // Specifies which Deployment Version should should receive new workflow executions and tasks of + // existing unversioned or AutoUpgrade workflows. + // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - // is set (see `ramping_version`.) - oneof current { - temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool current_unversioned = 8; - } - // Deprecated. Use `current`. + // is set and ramp percentage is non-zero (see `ramping_deployment_version`.) + temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; + // Deprecated. Use `current_deployment_version`. string current_version = 1 [deprecated = true]; - // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. + + // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. // Must always be different from Current Version. + // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - oneof ramping { - temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool ramping_unversioned = 10; - } + temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Deprecated. Use `ramping`. string ramping_version = 2 [deprecated = true]; + // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. + // A 0% value means the Ramping Version is receiving no traffic. float ramping_version_percentage = 3; // Last time current version was changed. google.protobuf.Timestamp current_version_changed_time = 4; diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 30c9a3aee..0262613e9 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -57,31 +57,28 @@ message TaskQueueMetadata { // Experimental. Worker Deployments are experimental and might significantly change in the future. message TaskQueueVersioningInfo { - // Always present. Specifies which Deployment Version should receive new workflow - // executions and tasks of existing unversioned or AutoUpgrade workflows. + // Specifies which Deployment Version should receive new workflow executions and tasks of + // existing unversioned or AutoUpgrade workflows. + // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp // is set (see `ramping_version`.) - oneof current { - temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool current_unversioned = 8; - } - // Deprecated. Use `current`. + temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; + // Deprecated. Use `current_deployment_version`. string current_version = 1 [deprecated = true]; - // When present, it means the traffic is being shifted from the Current Version to the Ramping Version. - // Must always be different from `current_version`. + + // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. + // Must always be different from `current_deployment_version`. + // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. - oneof ramping { - temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - bool ramping_unversioned = 10; - } + temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; // Deprecated. Use `ramping`. string ramping_version = 2 [deprecated = true]; + // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. // Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but // not yet "promoted" to be the Current Version, likely due to pending validations. + // A 0% value means the Ramping Version is receiving no traffic. float ramping_version_percentage = 3; // Last time versioning information of this Task Queue changed. google.protobuf.Timestamp update_time = 4; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 6602e9d82..fca894116 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2024,18 +2024,15 @@ message SetCurrentDeploymentResponse { // Set/unset the Current Version of a Worker Deployment. message SetWorkerDeploymentCurrentVersionRequest { string namespace = 1; - // Deprecated. Use `current`. - string deployment_name = 2 [deprecated = true]; - // Deprecated. Use `current`. + string deployment_name = 2; + // Deprecated. Use `build_id`. string version = 3 [deprecated = true]; - // Required. - oneof current { - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; - // The name of the Deployment where you want to set Current Version to unversioned. - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - string unversioned_deployment_name = 8; - }; + // The build id of the version that you want to set as Current. + // Pass an empty value to set the Current Version to nil. + // A nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + string build_id = 7; + // Optional. This can be the value of conflict_token from a Describe, or another Worker // Deployment API. Passing a non-nil conflict token will cause this request to fail if the // Deployment's configuration has been modified between the API call that generated the @@ -2064,29 +2061,24 @@ message SetWorkerDeploymentCurrentVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // Deprecated. Use `replaced_version`. + // Deprecated. Use `previous_deployment_version`. string previous_version = 2 [deprecated = true]; // The version that was current before executing this operation. - oneof replaced_version { - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; - bool unversioned = 4; - }; + temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 3; } // Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. message SetWorkerDeploymentRampingVersionRequest { string namespace = 1; - // Deprecated. Use `ramping`. - string deployment_name = 2 [deprecated = true]; - // Deprecated. Use `ramping`. + string deployment_name = 2; + // Deprecated. Use `build_id`. string version = 3 [deprecated = true]; - // Pass an empty value to unset the Ramping Version. Must be paired with `percentage=0`. - oneof ramping { - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 8; - // The name of the Deployment where you want to set Ramping Version to unversioned. - // Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - string unversioned_deployment_name = 9; - }; + + // The build id of the version that you want to ramp traffic to. + // Pass an empty value to set the Ramping Version to nil. + // A nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + string build_id = 8; + // Ramp percentage to set. Valid range: [0,100]. float percentage = 4; @@ -2121,13 +2113,10 @@ message SetWorkerDeploymentRampingVersionResponse { // that write to the Worker Deployment state to ensure that the state // did not change between this API call and a future write. bytes conflict_token = 1; - // Deprecated. Use `replaced_version`. + // Deprecated. Use `previous_deployment_version`. string previous_version = 2 [deprecated = true]; // The version that was ramping before executing this operation. - oneof replaced_version { - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 4; - bool unversioned = 5; - }; + temporal.api.deployment.v1.WorkerDeploymentVersion previous_deployment_version = 4; // The ramping version percentage before executing this operation. float previous_percentage = 3; } diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index d9917230c..37e5a4abd 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -858,10 +858,10 @@ service WorkflowService { // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentCurrentVersion (SetWorkerDeploymentCurrentVersionRequest) returns (SetWorkerDeploymentCurrentVersionResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/worker-deployments/set-current-version" + post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-current-version" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/worker-deployments/set-current-version" + post: "/api/v1/namespaces/{namespace}/worker-deployments/{deployment_name}/set-current-version" body: "*" } }; @@ -912,10 +912,10 @@ service WorkflowService { // Experimental. This API might significantly change or be removed in a future release. rpc SetWorkerDeploymentRampingVersion (SetWorkerDeploymentRampingVersionRequest) returns (SetWorkerDeploymentRampingVersionResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/worker-deployments/set-ramping-version" + post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-ramping-version" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version" + post: "/api/v1/namespaces/{namespace}/worker-deployments/{deployment_name}/set-ramping-version" body: "*" } }; From 9ab5def92fca7072b82546f7e947d49d38b9289f Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 2 May 2025 11:39:45 -0700 Subject: [PATCH 16/31] make proto --- openapi/openapiv2.json | 254 +++++++++++++++++++------------------- openapi/openapiv3.yaml | 274 +++++++++++++++++++++++------------------ 2 files changed, 278 insertions(+), 250 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 5bc225f41..971b1fb0a 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1946,15 +1946,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployments/set-current-version": { - "post": { - "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentCurrentVersion2", + "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}": { + "get": { + "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeWorkerDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" + "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" } }, "default": { @@ -1972,28 +1972,24 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "deploymentName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" - } + "type": "string" } ], "tags": [ "WorkflowService" ] - } - }, - "/api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version": { - "post": { - "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentRampingVersion2", + }, + "delete": { + "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DeleteWorkerDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" + "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" } }, "default": { @@ -2011,12 +2007,17 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "deploymentName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" - } + "type": "string" + }, + { + "name": "identity", + "description": "Optional. The identity of the client who initiated this request.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -2024,15 +2025,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}": { - "get": { - "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DescribeWorkerDeployment2", + "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version": { + "post": { + "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentCurrentVersion2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" } }, "default": { @@ -2054,20 +2055,30 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" + } } ], "tags": [ "WorkflowService" ] - }, - "delete": { - "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DeleteWorkerDeployment2", + } + }, + "/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": { + "post": { + "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentRampingVersion2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" } }, "default": { @@ -2091,11 +2102,12 @@ "type": "string" }, { - "name": "identity", - "description": "Optional. The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" + } } ], "tags": [ @@ -5443,15 +5455,15 @@ ] } }, - "/namespaces/{namespace}/worker-deployments/set-current-version": { - "post": { - "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentCurrentVersion", + "/namespaces/{namespace}/worker-deployments/{deploymentName}": { + "get": { + "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeWorkerDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" + "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" } }, "default": { @@ -5469,28 +5481,24 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "deploymentName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" - } + "type": "string" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/worker-deployments/set-ramping-version": { - "post": { - "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "SetWorkerDeploymentRampingVersion", + }, + "delete": { + "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DeleteWorkerDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" + "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" } }, "default": { @@ -5508,12 +5516,17 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "deploymentName", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" - } + "type": "string" + }, + { + "name": "identity", + "description": "Optional. The identity of the client who initiated this request.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -5521,15 +5534,15 @@ ] } }, - "/namespaces/{namespace}/worker-deployments/{deploymentName}": { - "get": { - "summary": "Describes a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DescribeWorkerDeployment", + "/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version": { + "post": { + "summary": "Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping\nVersion if it is the Version being set as Current.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentCurrentVersion", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentCurrentVersionResponse" } }, "default": { @@ -5551,20 +5564,30 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentCurrentVersionBody" + } } ], "tags": [ "WorkflowService" ] - }, - "delete": { - "summary": "Deletes records of (an old) Deployment. A deployment can only be deleted if\nit has no Version in it.\nExperimental. This API might significantly change or be removed in a future release.", - "operationId": "DeleteWorkerDeployment", + } + }, + "/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": { + "post": { + "summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetWorkerDeploymentRampingVersion", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteWorkerDeploymentResponse" + "$ref": "#/definitions/v1SetWorkerDeploymentRampingVersionResponse" } }, "default": { @@ -5588,11 +5611,12 @@ "type": "string" }, { - "name": "identity", - "description": "Optional. The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentRampingVersionBody" + } } ], "tags": [ @@ -7582,20 +7606,13 @@ "WorkflowServiceSetWorkerDeploymentCurrentVersionBody": { "type": "object", "properties": { - "deploymentName": { - "type": "string", - "description": "Deprecated. Use `current`." - }, "version": { "type": "string", - "description": "Deprecated. Use `current`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "description": "Deprecated. Use `build_id`." }, - "unversionedDeploymentName": { + "buildId": { "type": "string", - "title": "The name of the Deployment where you want to set Current Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The build id of the version that you want to set as Current.\nPass an empty value to set the Current Version to nil.\nA nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "conflictToken": { "type": "string", @@ -7616,20 +7633,13 @@ "WorkflowServiceSetWorkerDeploymentRampingVersionBody": { "type": "object", "properties": { - "deploymentName": { - "type": "string", - "description": "Deprecated. Use `ramping`." - }, "version": { "type": "string", - "description": "Deprecated. Use `ramping`." + "description": "Deprecated. Use `build_id`." }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "unversionedDeploymentName": { + "buildId": { "type": "string", - "title": "The name of the Deployment where you want to set Ramping Version to unversioned.\nRepresents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The build id of the version that you want to ramp traffic to.\nPass an empty value to set the Ramping Version to nil.\nA nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "percentage": { "type": "number", @@ -12851,22 +12861,16 @@ "type": "object", "properties": { "currentDeploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "currentUnversioned": { - "type": "boolean", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "title": "Specifies which Deployment Version should should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set and ramp percentage is non-zero (see `ramping_deployment_version`.)" }, "currentVersion": { "type": "string", - "description": "Deprecated. Use `current`." + "description": "Deprecated. Use `current_deployment_version`." }, "rampingDeploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "rampingUnversioned": { - "type": "boolean", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from Current Version.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." }, "rampingVersion": { "type": "string", @@ -12875,7 +12879,7 @@ "rampingVersionPercentage": { "type": "number", "format": "float", - "description": "Percentage of tasks that are routed to the Ramping Version instead of the Current Version.\nValid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but\nnot yet \"promoted\" to be the Current Version, likely due to pending validations." + "description": "Percentage of tasks that are routed to the Ramping Version instead of the Current Version.\nValid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but\nnot yet \"promoted\" to be the Current Version, likely due to pending validations.\nA 0% value means the Ramping Version is receiving no traffic." }, "currentVersionChangedTime": { "type": "string", @@ -13361,13 +13365,11 @@ }, "previousVersion": { "type": "string", - "description": "Deprecated. Use `replaced_version`." + "description": "Deprecated. Use `previous_deployment_version`." }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "unversioned": { - "type": "boolean" + "previousDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The version that was current before executing this operation." } } }, @@ -13381,13 +13383,11 @@ }, "previousVersion": { "type": "string", - "description": "Deprecated. Use `replaced_version`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "description": "Deprecated. Use `previous_deployment_version`." }, - "unversioned": { - "type": "boolean" + "previousDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The version that was ramping before executing this operation." }, "previousPercentage": { "type": "number", @@ -14234,22 +14234,16 @@ "type": "object", "properties": { "currentDeploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "currentUnversioned": { - "type": "boolean", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "title": "Specifies which Deployment Version should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set (see `ramping_version`.)" }, "currentVersion": { "type": "string", - "description": "Deprecated. Use `current`." + "description": "Deprecated. Use `current_deployment_version`." }, "rampingDeploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" - }, - "rampingUnversioned": { - "type": "boolean", - "title": "Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from `current_deployment_version`.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." }, "rampingVersion": { "type": "string", @@ -14258,7 +14252,7 @@ "rampingVersionPercentage": { "type": "number", "format": "float", - "description": "Percentage of tasks that are routed to the Ramping Version instead of the Current Version.\nValid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but\nnot yet \"promoted\" to be the Current Version, likely due to pending validations." + "description": "Percentage of tasks that are routed to the Ramping Version instead of the Current Version.\nValid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but\nnot yet \"promoted\" to be the Current Version, likely due to pending validations.\nA 0% value means the Ramping Version is receiving no traffic." }, "updateTime": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 8cad42311..f7578d71f 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1749,82 +1749,84 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/set-current-version: - post: + /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}: + get: tags: - WorkflowService description: |- - Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping - Version if it is the Version being set as Current. + Describes a Worker Deployment. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentCurrentVersion + operationId: DescribeWorkerDeployment parameters: - name: namespace in: path required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' - required: true + - name: deploymentName + in: path + required: true + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' + $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/set-ramping-version: - post: + delete: tags: - WorkflowService description: |- - Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for - gradual ramp to unversioned workers too. + Deletes records of (an old) Deployment. A deployment can only be deleted if + it has no Version in it. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentRampingVersion + operationId: DeleteWorkerDeployment parameters: - name: namespace in: path required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' - required: true + - name: deploymentName + in: path + required: true + schema: + type: string + - name: identity + in: query + description: Optional. The identity of the client who initiated this request. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' + $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}: - get: + /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version: + post: tags: - WorkflowService description: |- - Describes a Worker Deployment. + Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping + Version if it is the Version being set as Current. Experimental. This API might significantly change or be removed in a future release. - operationId: DescribeWorkerDeployment + operationId: SetWorkerDeploymentCurrentVersion parameters: - name: namespace in: path @@ -1836,27 +1838,34 @@ paths: required: true schema: type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - delete: + /api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version: + post: tags: - WorkflowService description: |- - Deletes records of (an old) Deployment. A deployment can only be deleted if - it has no Version in it. + Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for + gradual ramp to unversioned workers too. Experimental. This API might significantly change or be removed in a future release. - operationId: DeleteWorkerDeployment + operationId: SetWorkerDeploymentRampingVersion parameters: - name: namespace in: path @@ -1868,18 +1877,19 @@ paths: required: true schema: type: string - - name: identity - in: query - description: Optional. The identity of the client who initiated this request. - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' default: description: Default error response content: @@ -4880,82 +4890,84 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/set-current-version: - post: + /namespaces/{namespace}/worker-deployments/{deploymentName}: + get: tags: - WorkflowService description: |- - Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping - Version if it is the Version being set as Current. + Describes a Worker Deployment. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentCurrentVersion + operationId: DescribeWorkerDeployment parameters: - name: namespace in: path required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' - required: true + - name: deploymentName + in: path + required: true + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' + $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/set-ramping-version: - post: + delete: tags: - WorkflowService description: |- - Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for - gradual ramp to unversioned workers too. + Deletes records of (an old) Deployment. A deployment can only be deleted if + it has no Version in it. Experimental. This API might significantly change or be removed in a future release. - operationId: SetWorkerDeploymentRampingVersion + operationId: DeleteWorkerDeployment parameters: - name: namespace in: path required: true schema: type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' - required: true + - name: deploymentName + in: path + required: true + schema: + type: string + - name: identity + in: query + description: Optional. The identity of the client who initiated this request. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' + $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/worker-deployments/{deploymentName}: - get: + /namespaces/{namespace}/worker-deployments/{deploymentName}/set-current-version: + post: tags: - WorkflowService description: |- - Describes a Worker Deployment. + Set/unset the Current Version of a Worker Deployment. Automatically unsets the Ramping + Version if it is the Version being set as Current. Experimental. This API might significantly change or be removed in a future release. - operationId: DescribeWorkerDeployment + operationId: SetWorkerDeploymentCurrentVersion parameters: - name: namespace in: path @@ -4967,27 +4979,34 @@ paths: required: true schema: type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DescribeWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentCurrentVersionResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' - delete: + /namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version: + post: tags: - WorkflowService description: |- - Deletes records of (an old) Deployment. A deployment can only be deleted if - it has no Version in it. + Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for + gradual ramp to unversioned workers too. Experimental. This API might significantly change or be removed in a future release. - operationId: DeleteWorkerDeployment + operationId: SetWorkerDeploymentRampingVersion parameters: - name: namespace in: path @@ -4999,18 +5018,19 @@ paths: required: true schema: type: string - - name: identity - in: query - description: Optional. The identity of the client who initiated this request. - schema: - type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionRequest' + required: true responses: "200": description: OK content: application/json: schema: - $ref: '#/components/schemas/DeleteWorkerDeploymentResponse' + $ref: '#/components/schemas/SetWorkerDeploymentRampingVersionResponse' default: description: Default error response content: @@ -10047,18 +10067,26 @@ components: type: object properties: currentDeploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - currentUnversioned: - type: boolean - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + Specifies which Deployment Version should should receive new workflow executions and tasks of + existing unversioned or AutoUpgrade workflows. + Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp + is set and ramp percentage is non-zero (see `ramping_deployment_version`.) currentVersion: type: string - description: Deprecated. Use `current`. + description: Deprecated. Use `current_deployment_version`. rampingDeploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - rampingUnversioned: - type: boolean - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. + Must always be different from Current Version. + Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + Note that it is possible to ramp from one Version to another Version, or from unversioned + workers to a particular Version, or from a particular Version to unversioned workers. rampingVersion: type: string description: Deprecated. Use `ramping`. @@ -10068,6 +10096,7 @@ components: Percentage of tasks that are routed to the Ramping Version instead of the Current Version. Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but not yet "promoted" to be the Current Version, likely due to pending validations. + A 0% value means the Ramping Version is receiving no traffic. format: float currentVersionChangedTime: type: string @@ -10483,17 +10512,15 @@ components: type: string deploymentName: type: string - description: Deprecated. Use `current`. version: type: string - description: Deprecated. Use `current`. - deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - unversionedDeploymentName: + description: Deprecated. Use `build_id`. + buildId: type: string description: |- - The name of the Deployment where you want to set Current Version to unversioned. - Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + The build id of the version that you want to set as Current. + Pass an empty value to set the Current Version to nil. + A nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) conflictToken: type: string description: |- @@ -10534,11 +10561,11 @@ components: format: bytes previousVersion: type: string - description: Deprecated. Use `replaced_version`. - deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - unversioned: - type: boolean + description: Deprecated. Use `previous_deployment_version`. + previousDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: The version that was current before executing this operation. SetWorkerDeploymentRampingVersionRequest: type: object properties: @@ -10546,17 +10573,15 @@ components: type: string deploymentName: type: string - description: Deprecated. Use `ramping`. version: type: string - description: Deprecated. Use `ramping`. - deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - unversionedDeploymentName: + description: Deprecated. Use `build_id`. + buildId: type: string description: |- - The name of the Deployment where you want to set Ramping Version to unversioned. - Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + The build id of the version that you want to ramp traffic to. + Pass an empty value to set the Ramping Version to nil. + A nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) percentage: type: number description: 'Ramp percentage to set. Valid range: [0,100].' @@ -10604,11 +10629,11 @@ components: format: bytes previousVersion: type: string - description: Deprecated. Use `replaced_version`. - deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - unversioned: - type: boolean + description: Deprecated. Use `previous_deployment_version`. + previousDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: The version that was ramping before executing this operation. previousPercentage: type: number description: The ramping version percentage before executing this operation. @@ -11415,18 +11440,26 @@ components: type: object properties: currentDeploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - currentUnversioned: - type: boolean - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + Specifies which Deployment Version should receive new workflow executions and tasks of + existing unversioned or AutoUpgrade workflows. + Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp + is set (see `ramping_version`.) currentVersion: type: string - description: Deprecated. Use `current`. + description: Deprecated. Use `current_deployment_version`. rampingDeploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - rampingUnversioned: - type: boolean - description: Represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. + Must always be different from `current_deployment_version`. + Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + Note that it is possible to ramp from one Version to another Version, or from unversioned + workers to a particular Version, or from a particular Version to unversioned workers. rampingVersion: type: string description: Deprecated. Use `ramping`. @@ -11436,6 +11469,7 @@ components: Percentage of tasks that are routed to the Ramping Version instead of the Current Version. Valid range: [0, 100]. A 100% value means the Ramping Version is receiving full traffic but not yet "promoted" to be the Current Version, likely due to pending validations. + A 0% value means the Ramping Version is receiving no traffic. format: float updateTime: type: string From 3df497a8528d116cec9693260e06f2c458d43e16 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 2 May 2025 11:48:54 -0700 Subject: [PATCH 17/31] address comments --- openapi/openapiv2.json | 48 +++++++------- openapi/openapiv3.yaml | 63 +++++++++---------- temporal/api/deployment/v1/message.proto | 7 +-- temporal/api/taskqueue/v1/message.proto | 2 +- temporal/api/workflow/v1/message.proto | 14 ++--- .../workflowservice/v1/request_response.proto | 2 + 6 files changed, 67 insertions(+), 69 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 971b1fb0a..0bf8e2e9e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -1759,14 +1759,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -1809,14 +1809,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -1875,14 +1875,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -5268,14 +5268,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -5318,14 +5318,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -5384,14 +5384,14 @@ }, { "name": "deploymentVersion.deploymentName", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace.", + "description": "Identifies the Worker Deployment this Version is part of.", "in": "path", "required": true, "type": "string" }, { "name": "deploymentVersion.buildId", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace.", + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace.", "in": "path", "required": true, "type": "string" @@ -7030,10 +7030,12 @@ "type": "object", "properties": { "behavior": { - "$ref": "#/definitions/VersioningOverridePinnedOverrideBehavior" + "$ref": "#/definitions/VersioningOverridePinnedOverrideBehavior", + "description": "Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED.\nSee `PinnedOverrideBehavior` for details." }, "version": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Required." } } }, @@ -9819,13 +9821,11 @@ "properties": { "version": { "type": "string", - "description": "Deprecated. Use `target`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "description": "Deprecated. Use `target_deployment_version`." }, - "unversioned": { - "type": "boolean" + "targetDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The target Version of the transition.\nIf nil, a so-far-versioned workflow is transitioning to unversioned workers." } }, "description": "Holds information about ongoing transition of a workflow execution from one worker\ndeployment version to another.\nExperimental. Might change in the future." @@ -12874,7 +12874,7 @@ }, "rampingVersion": { "type": "string", - "description": "Deprecated. Use `ramping`." + "description": "Deprecated. Use `ramping_deployment_version`." }, "rampingVersionPercentage": { "type": "number", @@ -14247,7 +14247,7 @@ }, "rampingVersion": { "type": "string", - "description": "Deprecated. Use `ramping`." + "description": "Deprecated. Use `ramping_deployment_version`." }, "rampingVersionPercentage": { "type": "number", @@ -14819,11 +14819,11 @@ "properties": { "buildId": { "type": "string", - "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies\nthis Version within the namespace." + "description": "A unique identifier for this Version within the Deployment it is a part of.\nNot necessarily unique within the namespace.\nThe combination of `deployment_name` and `build_id` uniquely identifies this\nVersion within the namespace, because Deployment names are unique within a namespace." }, "deploymentName": { "type": "string", - "description": "Identifies the Worker Deployment this Version is part of.\nMust be unique within the namespace." + "description": "Identifies the Worker Deployment this Version is part of." } }, "description": "A Worker Deployment Version (Version, for short) represents a\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index f7578d71f..a3ca45bca 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -1571,15 +1571,13 @@ paths: description: |- A unique identifier for this Version within the Deployment it is a part of. Not necessarily unique within the namespace. - The combination of `deployment_name` and `build_id` uniquely identifies - this Version within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies this + Version within the namespace, because Deployment names are unique within a namespace. schema: type: string - name: deploymentVersion.deploymentName in: query - description: |- - Identifies the Worker Deployment this Version is part of. - Must be unique within the namespace. + description: Identifies the Worker Deployment this Version is part of. schema: type: string responses: @@ -1633,15 +1631,13 @@ paths: description: |- A unique identifier for this Version within the Deployment it is a part of. Not necessarily unique within the namespace. - The combination of `deployment_name` and `build_id` uniquely identifies - this Version within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies this + Version within the namespace, because Deployment names are unique within a namespace. schema: type: string - name: deploymentVersion.deploymentName in: query - description: |- - Identifies the Worker Deployment this Version is part of. - Must be unique within the namespace. + description: Identifies the Worker Deployment this Version is part of. schema: type: string - name: skipDrainage @@ -4712,15 +4708,13 @@ paths: description: |- A unique identifier for this Version within the Deployment it is a part of. Not necessarily unique within the namespace. - The combination of `deployment_name` and `build_id` uniquely identifies - this Version within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies this + Version within the namespace, because Deployment names are unique within a namespace. schema: type: string - name: deploymentVersion.deploymentName in: query - description: |- - Identifies the Worker Deployment this Version is part of. - Must be unique within the namespace. + description: Identifies the Worker Deployment this Version is part of. schema: type: string responses: @@ -4774,15 +4768,13 @@ paths: description: |- A unique identifier for this Version within the Deployment it is a part of. Not necessarily unique within the namespace. - The combination of `deployment_name` and `build_id` uniquely identifies - this Version within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies this + Version within the namespace, because Deployment names are unique within a namespace. schema: type: string - name: deploymentVersion.deploymentName in: query - description: |- - Identifies the Worker Deployment this Version is part of. - Must be unique within the namespace. + description: Identifies the Worker Deployment this Version is part of. schema: type: string - name: skipDrainage @@ -7170,11 +7162,13 @@ components: properties: version: type: string - description: Deprecated. Use `target`. - deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' - unversioned: - type: boolean + description: Deprecated. Use `target_deployment_version`. + targetDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The target Version of the transition. + If nil, a so-far-versioned workflow is transitioning to unversioned workers. description: |- Holds information about ongoing transition of a workflow execution from one worker deployment version to another. @@ -10089,7 +10083,7 @@ components: workers to a particular Version, or from a particular Version to unversioned workers. rampingVersion: type: string - description: Deprecated. Use `ramping`. + description: Deprecated. Use `ramping_deployment_version`. rampingVersionPercentage: type: number description: |- @@ -11462,7 +11456,7 @@ components: workers to a particular Version, or from a particular Version to unversioned workers. rampingVersion: type: string - description: Deprecated. Use `ramping`. + description: Deprecated. Use `ramping_deployment_version`. rampingVersionPercentage: type: number description: |- @@ -12082,9 +12076,14 @@ components: - PINNED_OVERRIDE_BEHAVIOR_PINNED - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string + description: |- + Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. + See `PinnedOverrideBehavior` for details. format: enum version: - $ref: '#/components/schemas/WorkerDeploymentVersion' + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. WaitPolicy: type: object properties: @@ -12178,13 +12177,11 @@ components: description: |- A unique identifier for this Version within the Deployment it is a part of. Not necessarily unique within the namespace. - The combination of `deployment_name` and `build_id` uniquely identifies - this Version within the namespace. + The combination of `deployment_name` and `build_id` uniquely identifies this + Version within the namespace, because Deployment names are unique within a namespace. deploymentName: type: string - description: |- - Identifies the Worker Deployment this Version is part of. - Must be unique within the namespace. + description: Identifies the Worker Deployment this Version is part of. description: |- A Worker Deployment Version (Version, for short) represents a version of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 6ccecf90f..6b4fe272f 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -226,12 +226,11 @@ message WorkerDeploymentInfo { message WorkerDeploymentVersion { // A unique identifier for this Version within the Deployment it is a part of. // Not necessarily unique within the namespace. - // The combination of `deployment_name` and `build_id` uniquely identifies - // this Version within the namespace. + // The combination of `deployment_name` and `build_id` uniquely identifies this + // Version within the namespace, because Deployment names are unique within a namespace. string build_id = 1; // Identifies the Worker Deployment this Version is part of. - // Must be unique within the namespace. string deployment_name = 2; } @@ -256,7 +255,7 @@ message RoutingConfig { // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; - // Deprecated. Use `ramping`. + // Deprecated. Use `ramping_deployment_version`. string ramping_version = 2 [deprecated = true]; // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index 0262613e9..e1ba75cbe 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -72,7 +72,7 @@ message TaskQueueVersioningInfo { // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. temporal.api.deployment.v1.WorkerDeploymentVersion ramping_deployment_version = 9; - // Deprecated. Use `ramping`. + // Deprecated. Use `ramping_deployment_version`. string ramping_version = 2 [deprecated = true]; // Percentage of tasks that are routed to the Ramping Version instead of the Current Version. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 67bdf9969..63eb97a4f 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -241,15 +241,12 @@ message DeploymentTransition { // deployment version to another. // Experimental. Might change in the future. message DeploymentVersionTransition { - // Deprecated. Use `target`. + // Deprecated. Use `target_deployment_version`. string version = 1 [deprecated = true]; - // Required. The target Version of the transition. If `unversioned`, a - // so-far-versioned workflow is transitioning to unversioned workers. - oneof target { - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 2; - bool unversioned = 3; - } + // The target Version of the transition. + // If nil, a so-far-versioned workflow is transitioning to unversioned workers. + temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 2; // Later: safe transition info } @@ -577,7 +574,10 @@ message VersioningOverride { string pinned_version = 9 [deprecated = true]; message PinnedOverride { + // Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. + // See `PinnedOverrideBehavior` for details. PinnedOverrideBehavior behavior = 1; + // Required. temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 297dc09a5..95637c225 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1985,6 +1985,7 @@ message DescribeWorkerDeploymentVersionRequest { string namespace = 1; // Deprecated. Use `deployment_version`. string version = 2 [deprecated = true]; + // Required. temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 3; } @@ -2168,6 +2169,7 @@ message DeleteWorkerDeploymentVersionRequest { string namespace = 1; // Deprecated. Use `deployment_version`. string version = 2 [deprecated = true]; + // Required. temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; // Pass to force deletion even if the Version is draining. In this case the open pinned // workflows will be stuck until manually moved to another version by UpdateWorkflowExecutionOptions. From dd4300efa61ed810402867817bc58018807a9b2e Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 2 May 2025 11:56:49 -0700 Subject: [PATCH 18/31] clarify comments --- openapi/openapiv2.json | 14 +++++++------- openapi/openapiv3.yaml | 19 +++++++++---------- temporal/api/deployment/v1/message.proto | 6 +++--- temporal/api/taskqueue/v1/message.proto | 6 +++--- temporal/api/workflow/v1/message.proto | 2 +- .../workflowservice/v1/request_response.proto | 4 ++-- 6 files changed, 25 insertions(+), 26 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0bf8e2e9e..9f782691d 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7614,7 +7614,7 @@ }, "buildId": { "type": "string", - "title": "The build id of the version that you want to set as Current.\nPass an empty value to set the Current Version to nil.\nA nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The build id of the Version that you want to set as Current.\nPass an empty value to set the Current Version to nil.\nA nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "conflictToken": { "type": "string", @@ -7641,7 +7641,7 @@ }, "buildId": { "type": "string", - "title": "The build id of the version that you want to ramp traffic to.\nPass an empty value to set the Ramping Version to nil.\nA nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" + "title": "The build id of the Version that you want to ramp traffic to.\nPass an empty value to set the Ramping Version to nil.\nA nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)" }, "percentage": { "type": "number", @@ -12862,7 +12862,7 @@ "properties": { "currentDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "title": "Specifies which Deployment Version should should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set and ramp percentage is non-zero (see `ramping_deployment_version`.)" + "description": "Specifies which Deployment Version should should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage\nis non-zero (see `ramping_deployment_version` and `ramping_version_percentage`)." }, "currentVersion": { "type": "string", @@ -12870,7 +12870,7 @@ }, "rampingDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from Current Version.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." + "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from `current_deployment_version` unless both are nil.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." }, "rampingVersion": { "type": "string", @@ -14235,7 +14235,7 @@ "properties": { "currentDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "title": "Specifies which Deployment Version should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp\nis set (see `ramping_version`.)" + "description": "Specifies which Deployment Version should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage\nis non-zero (see `ramping_deployment_version` and `ramping_version_percentage`)." }, "currentVersion": { "type": "string", @@ -14243,7 +14243,7 @@ }, "rampingDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from `current_deployment_version`.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." + "description": "When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version.\nMust always be different from `current_deployment_version` unless both are nil.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote that it is possible to ramp from one Version to another Version, or from unversioned\nworkers to a particular Version, or from a particular Version to unversioned workers." }, "rampingVersion": { "type": "string", @@ -15576,7 +15576,7 @@ "description": "The worker deployment that completed the last workflow task of this workflow execution. Must\nbe present if `behavior` is set. Absent value means no workflow task is completed, or the\nlast workflow task was completed by an unversioned worker. Unversioned workers may still send\na deployment value which will be stored here, so the right way to check if an execution is\nversioned if an execution is versioned or not is via the `behavior` field.\nNote that `deployment` is overridden by `versioning_override` if the latter is present.\nDeprecated. Use `deployment_version`." }, "version": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", + "type": "string", "description": "Deprecated. Use `deployment_version`." }, "deploymentVersion": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index a3ca45bca..7d95e5937 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10067,8 +10067,8 @@ components: Specifies which Deployment Version should should receive new workflow executions and tasks of existing unversioned or AutoUpgrade workflows. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - is set and ramp percentage is non-zero (see `ramping_deployment_version`.) + Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage + is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). currentVersion: type: string description: Deprecated. Use `current_deployment_version`. @@ -10077,7 +10077,7 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. - Must always be different from Current Version. + Must always be different from `current_deployment_version` unless both are nil. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) Note that it is possible to ramp from one Version to another Version, or from unversioned workers to a particular Version, or from a particular Version to unversioned workers. @@ -10512,7 +10512,7 @@ components: buildId: type: string description: |- - The build id of the version that you want to set as Current. + The build id of the Version that you want to set as Current. Pass an empty value to set the Current Version to nil. A nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) conflictToken: @@ -10573,7 +10573,7 @@ components: buildId: type: string description: |- - The build id of the version that you want to ramp traffic to. + The build id of the Version that you want to ramp traffic to. Pass an empty value to set the Ramping Version to nil. A nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) percentage: @@ -11440,8 +11440,8 @@ components: Specifies which Deployment Version should receive new workflow executions and tasks of existing unversioned or AutoUpgrade workflows. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - is set (see `ramping_version`.) + Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage + is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). currentVersion: type: string description: Deprecated. Use `current_deployment_version`. @@ -11450,7 +11450,7 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. - Must always be different from `current_deployment_version`. + Must always be different from `current_deployment_version` unless both are nil. Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) Note that it is possible to ramp from one Version to another Version, or from unversioned workers to a particular Version, or from a particular Version to unversioned workers. @@ -13106,8 +13106,7 @@ components: Note that `deployment` is overridden by `versioning_override` if the latter is present. Deprecated. Use `deployment_version`. version: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' + type: string description: Deprecated. Use `deployment_version`. deploymentVersion: allOf: diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 6b4fe272f..ac7788e64 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -243,14 +243,14 @@ message RoutingConfig { // Specifies which Deployment Version should should receive new workflow executions and tasks of // existing unversioned or AutoUpgrade workflows. // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - // is set and ramp percentage is non-zero (see `ramping_deployment_version`.) + // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage + // is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Deprecated. Use `current_deployment_version`. string current_version = 1 [deprecated = true]; // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. - // Must always be different from Current Version. + // Must always be different from `current_deployment_version` unless both are nil. // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. diff --git a/temporal/api/taskqueue/v1/message.proto b/temporal/api/taskqueue/v1/message.proto index e1ba75cbe..80e506db0 100644 --- a/temporal/api/taskqueue/v1/message.proto +++ b/temporal/api/taskqueue/v1/message.proto @@ -60,14 +60,14 @@ message TaskQueueVersioningInfo { // Specifies which Deployment Version should receive new workflow executions and tasks of // existing unversioned or AutoUpgrade workflows. // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - // Note: Current Version is overridden by the Ramping Version for a portion of traffic when a ramp - // is set (see `ramping_version`.) + // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage + // is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; // Deprecated. Use `current_deployment_version`. string current_version = 1 [deprecated = true]; // When ramp percentage is non-zero, that portion of traffic is shifted from the Current Version to the Ramping Version. - // Must always be different from `current_deployment_version`. + // Must always be different from `current_deployment_version` unless both are nil. // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note that it is possible to ramp from one Version to another Version, or from unversioned // workers to a particular Version, or from a particular Version to unversioned workers. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 63eb97a4f..72aa8c7f7 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -172,7 +172,7 @@ message WorkflowExecutionVersioningInfo { // Deprecated. Use `deployment_version`. temporal.api.deployment.v1.Deployment deployment = 2 [deprecated = true]; // Deprecated. Use `deployment_version`. - temporal.api.deployment.v1.WorkerDeploymentVersion version = 5 [deprecated = true]; + string version = 5 [deprecated = true]; // The Worker Deployment Version that completed the last workflow task of this workflow execution. // Must be present if and only if `behavior` is set. An absent value means no workflow task is // completed, or the workflow is unversioned. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 95637c225..7762a4117 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2046,7 +2046,7 @@ message SetWorkerDeploymentCurrentVersionRequest { // Deprecated. Use `build_id`. string version = 3 [deprecated = true]; - // The build id of the version that you want to set as Current. + // The build id of the Version that you want to set as Current. // Pass an empty value to set the Current Version to nil. // A nil Current Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string build_id = 7; @@ -2092,7 +2092,7 @@ message SetWorkerDeploymentRampingVersionRequest { // Deprecated. Use `build_id`. string version = 3 [deprecated = true]; - // The build id of the version that you want to ramp traffic to. + // The build id of the Version that you want to ramp traffic to. // Pass an empty value to set the Ramping Version to nil. // A nil Ramping Version represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) string build_id = 8; From e87bbe3eb99c5f619023c8ae14e13279a1f17e70 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 2 May 2025 12:01:53 -0700 Subject: [PATCH 19/31] more clarifying comments --- openapi/openapiv2.json | 11 +++++++---- openapi/openapiv3.yaml | 16 ++++++++++++---- temporal/api/deployment/v1/message.proto | 2 ++ temporal/api/workflow/v1/message.proto | 1 + .../workflowservice/v1/request_response.proto | 1 + 5 files changed, 23 insertions(+), 8 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 9f782691d..ad7d876a8 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7057,7 +7057,8 @@ "description": "Deprecated. Use `deployment_version`." }, "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Required." }, "createTime": { "type": "string", @@ -8153,7 +8154,8 @@ }, "deploymentVersion": { "type": "object", - "description": "A Worker Deployment Version (Version, for short) represents a\nversion of workers within a Worker Deployment. (see documentation of WorkerDeploymentVersionInfo)\nVersion records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployment Versions are experimental and might significantly change in the future." + "description": "Required.", + "title": "Required." }, "upsertEntries": { "type": "object", @@ -11825,7 +11827,7 @@ }, "lastDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version this activity was dispatched to most recently." + "description": "The Worker Deployment Version this activity was dispatched to most recently.\nIf nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker." }, "priority": { "$ref": "#/definitions/v1Priority", @@ -14836,7 +14838,8 @@ "description": "Deprecated. Use `deployment_version`." }, "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion" + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Required." }, "deploymentName": { "type": "string" diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 7d95e5937..84389b07b 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -8954,7 +8954,9 @@ components: lastDeploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: The Worker Deployment Version this activity was dispatched to most recently. + description: |- + The Worker Deployment Version this activity was dispatched to most recently. + If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -11830,7 +11832,9 @@ components: type: string description: Deprecated. Use `deployment_version`. deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. upsertEntries: type: object additionalProperties: @@ -12132,7 +12136,9 @@ components: type: string description: Deprecated. Use `deployment_version`. deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. createTime: type: string format: date-time @@ -12195,7 +12201,9 @@ components: type: string description: Deprecated. Use `deployment_version`. deploymentVersion: - $ref: '#/components/schemas/WorkerDeploymentVersion' + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. deploymentName: type: string createTime: diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index ac7788e64..efec689d1 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -120,6 +120,7 @@ message WorkerDeploymentVersionInfo { // Deprecated. Use `deployment_version`. string version = 1 [deprecated = true]; + // Required. WorkerDeploymentVersion deployment_version = 11; string deployment_name = 2; google.protobuf.Timestamp create_time = 3; @@ -212,6 +213,7 @@ message WorkerDeploymentInfo { // Deprecated. Use `deployment_version`. string version = 1 [deprecated = true]; + // Required. WorkerDeploymentVersion deployment_version = 4; google.protobuf.Timestamp create_time = 2; enums.v1.VersionDrainageStatus drainage_status = 3; diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 72aa8c7f7..24f67ea21 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -314,6 +314,7 @@ message PendingActivityInfo { // Deprecated. Use `last_deployment_version`. string last_worker_deployment_version = 21 [deprecated = true]; // The Worker Deployment Version this activity was dispatched to most recently. + // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 24; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 7762a4117..80bd3114f 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -2198,6 +2198,7 @@ message UpdateWorkerDeploymentVersionMetadataRequest { string namespace = 1; // Deprecated. Use `deployment_version`. string version = 2 [deprecated = true]; + // Required. temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 5; map upsert_entries = 3; // List of keys to remove from the metadata. From 73e8b048da4ce1b604e641e28cc3af01ca4a1c10 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 4 May 2025 23:50:20 -0700 Subject: [PATCH 20/31] Update temporal/api/deployment/v1/message.proto Co-authored-by: Shahab Tajik --- temporal/api/deployment/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index efec689d1..903e924eb 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -242,7 +242,7 @@ message VersionMetadata { } message RoutingConfig { - // Specifies which Deployment Version should should receive new workflow executions and tasks of + // Specifies which Deployment Version should receive new workflow executions and tasks of // existing unversioned or AutoUpgrade workflows. // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage From 8261c830050e87a2da7291c1d0873b0ef4d512d7 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 4 May 2025 23:50:51 -0700 Subject: [PATCH 21/31] Update temporal/api/deployment/v1/message.proto Co-authored-by: Shahab Tajik --- temporal/api/deployment/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 903e924eb..24af9fcaa 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -244,7 +244,7 @@ message VersionMetadata { message RoutingConfig { // Specifies which Deployment Version should receive new workflow executions and tasks of // existing unversioned or AutoUpgrade workflows. - // Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) + // Nil value means no Version in this Deployment (except Ramping Version, if present) receives traffic other than tasks of previously Pinned workflows. In absence of a Current Version, remaining traffic after any ramp (if set) goes to unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.). // Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage // is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). temporal.api.deployment.v1.WorkerDeploymentVersion current_deployment_version = 7; From 0968d3b1c19a35d65659d6d5d77589b5940f41b9 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Sun, 4 May 2025 23:57:57 -0700 Subject: [PATCH 22/31] add 'not yet supported' notes on reserved but unsupported protos --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 7 +------ temporal/api/workflow/v1/message.proto | 2 ++ 3 files changed, 5 insertions(+), 8 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ad7d876a8..3e922641e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7047,7 +7047,7 @@ "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": " - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior.\nIf original behavior is AutoUpgrade, override behavior to Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Override workflow behavior to be PinnedUntilContinueAsNew." + "description": " - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior.\nIf original behavior is AutoUpgrade, override behavior to Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Not yet supported. Reserved for future use.\nOverride workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Not yet supported. Reserved for future use.\nOverride workflow behavior to be PinnedUntilContinueAsNew." }, "WorkerDeploymentInfoWorkerDeploymentVersionSummary": { "type": "object", @@ -12864,7 +12864,7 @@ "properties": { "currentDeploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "Specifies which Deployment Version should should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.)\nNote: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage\nis non-zero (see `ramping_deployment_version` and `ramping_version_percentage`)." + "description": "Specifies which Deployment Version should receive new workflow executions and tasks of\nexisting unversioned or AutoUpgrade workflows.\nNil value means no Version in this Deployment (except Ramping Version, if present) receives traffic other than tasks of previously Pinned workflows. In absence of a Current Version, remaining traffic after any ramp (if set) goes to unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.). \nNote: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage\nis non-zero (see `ramping_deployment_version` and `ramping_version_percentage`)." }, "currentVersion": { "type": "string", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 84389b07b..722af6e79 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -10065,12 +10065,7 @@ components: currentDeploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - Specifies which Deployment Version should should receive new workflow executions and tasks of - existing unversioned or AutoUpgrade workflows. - Nil value represents all the unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.) - Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage - is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`). + description: "Specifies which Deployment Version should receive new workflow executions and tasks of\n existing unversioned or AutoUpgrade workflows.\n Nil value means no Version in this Deployment (except Ramping Version, if present) receives traffic other than tasks of previously Pinned workflows. In absence of a Current Version, remaining traffic after any ramp (if set) goes to unversioned workers (those with `UNVERSIONED` (or unspecified) `WorkerVersioningMode`.). \n Note: Current Version is overridden by the Ramping Version for a portion of traffic when ramp percentage\n is non-zero (see `ramping_deployment_version` and `ramping_version_percentage`)." currentVersion: type: string description: Deprecated. Use `current_deployment_version`. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 24f67ea21..00628a470 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -586,8 +586,10 @@ message VersioningOverride { // If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior. // If original behavior is AutoUpgrade, override behavior to Pinned. PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; + // Not yet supported. Reserved for future use. // Override workflow behavior to be Pinned. PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; + // Not yet supported. Reserved for future use. // Override workflow behavior to be PinnedUntilContinueAsNew. PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; } From 26b922eb73f4c9f3c1beaebf54c89bbe9a824716 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Mon, 5 May 2025 12:23:42 -0700 Subject: [PATCH 23/31] remove unsupported enum fields --- openapi/openapiv2.json | 5 ++--- openapi/openapiv3.yaml | 1 - temporal/api/workflow/v1/message.proto | 8 ++------ 3 files changed, 4 insertions(+), 10 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3e922641e..d9bb544f2 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7043,11 +7043,10 @@ "type": "string", "enum": [ "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "PINNED_OVERRIDE_BEHAVIOR_PINNED", - "PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW" + "PINNED_OVERRIDE_BEHAVIOR_PINNED" ], "default": "PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED", - "description": " - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior.\nIf original behavior is AutoUpgrade, override behavior to Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Not yet supported. Reserved for future use.\nOverride workflow behavior to be Pinned.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW: Not yet supported. Reserved for future use.\nOverride workflow behavior to be PinnedUntilContinueAsNew." + "description": "Used to specify different sub-types of Pinned override that we plan to add in the future.\n\n - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED: Unspecified.\n - PINNED_OVERRIDE_BEHAVIOR_PINNED: Override workflow behavior to be Pinned." }, "WorkerDeploymentInfoWorkerDeploymentVersionSummary": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 722af6e79..e7d5ce318 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -12073,7 +12073,6 @@ components: enum: - PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED - PINNED_OVERRIDE_BEHAVIOR_PINNED - - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW type: string description: |- Defaults to PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 00628a470..deedfe8ab 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -582,16 +582,12 @@ message VersioningOverride { temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } + // Used to specify different sub-types of Pinned override that we plan to add in the future. enum PinnedOverrideBehavior { - // If original behavior is Pinned or PinnedUntilContinueAsNew, keep that behavior. - // If original behavior is AutoUpgrade, override behavior to Pinned. + // Unspecified. PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; - // Not yet supported. Reserved for future use. // Override workflow behavior to be Pinned. PINNED_OVERRIDE_BEHAVIOR_PINNED = 1; - // Not yet supported. Reserved for future use. - // Override workflow behavior to be PinnedUntilContinueAsNew. - PINNED_OVERRIDE_BEHAVIOR_PINNED_UNTIL_CONTINUE_AS_NEW = 2; } } From d24144e2905c646076d4af6cfbb02396f78a3705 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 15:14:36 -0700 Subject: [PATCH 24/31] deprecate binary checksum, build id, version stamp and replace with version and deployment options --- temporal/api/deployment/v1/message.proto | 5 +- temporal/api/history/v1/message.proto | 67 +++++++++++++------ temporal/api/workflow/v1/message.proto | 22 +++--- .../workflowservice/v1/request_response.proto | 30 +++++---- 4 files changed, 80 insertions(+), 44 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 24af9fcaa..284c4213b 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -43,12 +43,11 @@ message WorkerDeploymentOptions { // Required. Worker Deployment name. string deployment_name = 1; // The Build ID of the worker. Required when `worker_versioning_mode==VERSIONED`, in which case, - // the worker will be part of a Deployment Version identified by ".". + // the worker will be part of a Deployment Version. string build_id = 2; // Required. Versioning Mode for this worker. Must be the same for all workers with the // same `deployment_name` and `build_id` combination, across all Task Queues. - // When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version - // identified by ".". + // When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version. temporal.api.enums.v1.WorkerVersioningMode worker_versioning_mode = 3; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 2a310467b..d527cfbab 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -147,7 +147,15 @@ message WorkflowExecutionStartedEventAttributes { // of starting on the Current Version of its Task Queue. // This is set only if the child workflow is starting on a Task Queue belonging to the same // Worker Deployment Version. - string parent_pinned_worker_deployment_version = 34; + // Deprecated. Use `parent_pinned_deployment_version`. + string parent_pinned_worker_deployment_version = 34 [deprecated = true]; + + // When present, it means this is a child workflow of a parent that is Pinned to this Worker + // Deployment Version. In this case, child workflow will start as Pinned to this Version instead + // of starting on the Current Version of its Task Queue. + // This is set only if the child workflow is starting on a Task Queue belonging to the same + // Worker Deployment Version. + temporal.api.deployment.v1.WorkerDeploymentVersion parent_pinned_deployment_version = 36; // Priority metadata temporal.api.common.v1.Priority priority = 35; @@ -238,11 +246,11 @@ message WorkflowTaskStartedEventAttributes { int64 history_size_bytes = 5; // Version info of the worker to whom this task was dispatched. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - temporal.api.common.v1.WorkerVersionStamp worker_version = 6; + temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; // Used by server internally to properly reapply build ID redirects to an execution // when rebuilding it from events. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - int64 build_id_redirect_counter = 7; + int64 build_id_redirect_counter = 7 [deprecated = true]; } message WorkflowTaskCompletedEventAttributes { @@ -253,11 +261,12 @@ message WorkflowTaskCompletedEventAttributes { // Identity of the worker who completed this task string identity = 3; // Binary ID of the worker who completed this task - string binary_checksum = 4; + // Deprecated. Replaced with `deployment_version`. + string binary_checksum = 4 [deprecated = true]; // Version info of the worker who processed this workflow task. If present, the `build_id` field // within is also used as `binary_checksum`, which may be omitted in that case (it may also be // populated to preserve compatibility). - // Deprecated. Use `deployment` and `versioning_behavior` instead. + // Deprecated. Use `deployment_version` and `versioning_behavior` instead. temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; // Data the SDK wishes to record for itself, but server need not interpret, and does not // directly impact workflow state. @@ -269,7 +278,7 @@ message WorkflowTaskCompletedEventAttributes { // The deployment that completed this task. May or may not be set for unversioned workers, // depending on whether a value is sent by the SDK. This value updates workflow execution's // `versioning_info.deployment`. - // Deprecated. Replaced with `worker_deployment_version`. + // Deprecated. Replaced with `deployment_version`. temporal.api.deployment.v1.Deployment deployment = 7 [deprecated = true]; // Versioning behavior sent by the worker that completed this task for this particular workflow // execution. UNSPECIFIED means the task was completed by an unversioned worker. This value @@ -278,11 +287,17 @@ message WorkflowTaskCompletedEventAttributes { // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` // is set. This value updates workflow execution's `versioning_info.version`. // Experimental. Worker Deployments are experimental and might significantly change in the future. - string worker_deployment_version = 9; + // Deprecated. Replaced with `deployment_version`. + string worker_deployment_version = 9 [deprecated = true]; // The name of Worker Deployment that completed this task. Must be set if `versioning_behavior` // is set. This value updates workflow execution's `worker_deployment_name`. // Experimental. Worker Deployments are experimental and might significantly change in the future. - string worker_deployment_name = 10; + // Deprecated. Use `deployment_version`. + string worker_deployment_name = 10 [deprecated = true]; + // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` + // is set. This value updates workflow execution's `versioning_info.worker_deployment_version`. + // Experimental. Worker Deployments are experimental and might significantly change in the future. + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 11; } message WorkflowTaskTimedOutEventAttributes { @@ -309,14 +324,17 @@ message WorkflowTaskFailedEventAttributes { string new_run_id = 7; // TODO: ? int64 fork_event_version = 8; - // DEPRECATED since 1.21 - use `worker_version` instead. // If a worker explicitly failed this task, its binary id - string binary_checksum = 9; + // Deprecated since 1.21. Use `deployment_version`. + string binary_checksum = 9 [deprecated = true]; // Version info of the worker who processed this workflow task. If present, the `build_id` field // within is also used as `binary_checksum`, which may be omitted in that case (it may also be // populated to preserve compatibility). - // Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent - temporal.api.common.v1.WorkerVersionStamp worker_version = 10; + // Deprecated. Use `deployment_version` instead. + temporal.api.common.v1.WorkerVersionStamp worker_version = 10 [deprecated = true]; + // If a worker explicitly failed this task, its Worker Deployment Version. + // Experimental. Worker Deployments are experimental and might significantly change in the future. + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 11; } message ActivityTaskScheduledEventAttributes { @@ -379,11 +397,11 @@ message ActivityTaskStartedEventAttributes { temporal.api.failure.v1.Failure last_failure = 5; // Version info of the worker to whom this task was dispatched. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - temporal.api.common.v1.WorkerVersionStamp worker_version = 6; + temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; // Used by server internally to properly reapply build ID redirects to an execution // when rebuilding it from events. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - int64 build_id_redirect_counter = 7; + int64 build_id_redirect_counter = 7 [deprecated = true]; } message ActivityTaskCompletedEventAttributes { @@ -396,8 +414,11 @@ message ActivityTaskCompletedEventAttributes { // id of the worker that completed this task string identity = 4; // Version info of the worker who processed this workflow task. - // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent - temporal.api.common.v1.WorkerVersionStamp worker_version = 5; + // Deprecated. Use `deployment_version`. + temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; + // The Worker Deployment Version that completed this task. + // Experimental. Worker Deployments are experimental and might significantly change in the future. + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 6; } message ActivityTaskFailedEventAttributes { @@ -411,8 +432,11 @@ message ActivityTaskFailedEventAttributes { string identity = 4; temporal.api.enums.v1.RetryState retry_state = 5; // Version info of the worker who processed this workflow task. - // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent - temporal.api.common.v1.WorkerVersionStamp worker_version = 6; + // Deprecated. Use `deployment_version`. + temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; + // The Worker Deployment Version that failed this task. + // Experimental. Worker Deployments are experimental and might significantly change in the future. + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; } message ActivityTaskTimedOutEventAttributes { @@ -446,8 +470,11 @@ message ActivityTaskCanceledEventAttributes { // id of the worker who canceled this activity string identity = 5; // Version info of the worker who processed this workflow task. - // Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent - temporal.api.common.v1.WorkerVersionStamp worker_version = 6; + // Deprecated. Use `deployment_version`. + temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; + // The Worker Deployment Version that processed this task. + // Experimental. Worker Deployments are experimental and might significantly change in the future. + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; } message TimerStartedEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index deedfe8ab..e0e2b27bd 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -94,11 +94,11 @@ message WorkflowExecutionInfo { // Assigned build ID can also change in the middle of a execution if Compatible Redirect Rules are applied to // this execution. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - string assigned_build_id = 19; + string assigned_build_id = 19 [deprecated = true]; // Build ID inherited from a previous/parent execution. If present, assigned_build_id will be set to this, instead // of using the assignment rules. // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - string inherited_build_id = 20; + string inherited_build_id = 20 [deprecated = true]; // The first run ID in the execution chain. // Executions created via the following operations are considered to be in the same chain // - ContinueAsNew @@ -114,7 +114,8 @@ message WorkflowExecutionInfo { // The name of Worker Deployment that completed the most recent workflow task. // Experimental. Worker Deployments are experimental and might change in the future. - string worker_deployment_name = 23; + // Deprecated. Replaced with `versioning_info.deployment_version`. + string worker_deployment_name = 23 [deprecated = true]; // Priority metadata temporal.api.common.v1.Priority priority = 24; @@ -174,10 +175,12 @@ message WorkflowExecutionVersioningInfo { // Deprecated. Use `deployment_version`. string version = 5 [deprecated = true]; // The Worker Deployment Version that completed the last workflow task of this workflow execution. - // Must be present if and only if `behavior` is set. An absent value means no workflow task is - // completed, or the workflow is unversioned. - // For child workflows of Pinned parents, this will be set to parent's Pinned Version when the - // the child starts so that child's first workflow task goes to the same Version as the parent. + // An absent value means no workflow task is completed, or the workflow is unversioned. + // If present, and `behavior` is UNSPECIFIED, the last task of this workflow execution was completed + // by a worker that is not using versioning but _is_ passing Deployment Name and Build ID. + // + // For child workflows of Pinned parents, this will be set to the parent's Pinned Version when + // the child starts, so that the child's first workflow task goes to the same Version as the parent. // Note that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version` // will override this value. temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; @@ -246,7 +249,7 @@ message DeploymentVersionTransition { // The target Version of the transition. // If nil, a so-far-versioned workflow is transitioning to unversioned workers. - temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 2; + temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 2; // Later: safe transition info } @@ -384,9 +387,10 @@ message ResetPoints { // checksum changes (although in general only one or the other will be used at a time). message ResetPointInfo { // Worker build id. + // todo carly string build_id = 7; // A worker binary version identifier (deprecated). - string binary_checksum = 1; + string binary_checksum = 1 [deprecated = true]; // The first run ID in the execution chain that was touched by this worker build. string run_id = 2; // Event ID of the first WorkflowTaskCompleted event processed by this worker build. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 80bd3114f..c2f84b91c 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -276,10 +276,10 @@ message PollWorkflowTaskQueueRequest { temporal.api.taskqueue.v1.TaskQueue task_queue = 2; // The identity of the worker/client who is polling this task queue string identity = 3; - // DEPRECATED since 1.21 - use `worker_version_capabilities` instead. + // DEPRECATED since 1.21 - use `deployment_option` instead. // Each worker process should provide an ID unique to the specific set of code it is running // "checksum" in this field name isn't very accurate, it should be though of as an id. - string binary_checksum = 4; + string binary_checksum = 4 [deprecated = true]; // Information about this worker's build identifier and if it is choosing to use the versioning // feature. See the `WorkerVersionCapabilities` docstring for more. // Deprecated. Replaced by deployment_options. @@ -361,16 +361,16 @@ message RespondWorkflowTaskCompletedRequest { // something useful, but cannot complete it within the workflow task timeout. Local activities // which run for longer than the task timeout being the prime example. bool force_create_new_workflow_task = 6; - // DEPRECATED since 1.21 - use `worker_version_stamp` instead. + // DEPRECATED since 1.21 - use `deployment_options` instead. // Worker process' unique binary id - string binary_checksum = 7; + string binary_checksum = 7 [deprecated = true]; // Responses to the `queries` field in the task being responded to map query_results = 8; string namespace = 9; // Version info of the worker who processed this task. This message's `build_id` field should // always be set by SDKs. Workers opting into versioning will also set the `use_versioning` // field to true. See message docstrings for more. - // Deprecated. Use `deployment` and `versioning_behavior` instead. + // Deprecated. Use `deployment_options` and `versioning_behavior` instead. temporal.api.common.v1.WorkerVersionStamp worker_version_stamp = 10 [deprecated = true]; // Protocol messages piggybacking on a WFT as a transport repeated temporal.api.protocol.v1.Message messages = 11; @@ -424,21 +424,21 @@ message RespondWorkflowTaskFailedRequest { temporal.api.failure.v1.Failure failure = 3; // The identity of the worker/client string identity = 4; - // DEPRECATED since 1.21 - use `worker_version_stamp` instead. + // DEPRECATED since 1.21 - use `deployment_options` instead. // Worker process' unique binary id - string binary_checksum = 5; + string binary_checksum = 5 [deprecated = true]; string namespace = 6; // Protocol messages piggybacking on a WFT as a transport repeated temporal.api.protocol.v1.Message messages = 7; // Version info of the worker who processed this task. This message's `build_id` field should // always be set by SDKs. Workers opting into versioning will also set the `use_versioning` // field to true. See message docstrings for more. - // Deprecated. Use `deployment` instead. + // Deprecated. Use `deployment_options` instead. temporal.api.common.v1.WorkerVersionStamp worker_version = 8 [deprecated = true]; // Deployment info of the worker that completed this task. Must be present if user has set // `WorkerDeploymentOptions` regardless of versioning being enabled or not. // Deprecated. Replaced with `deployment_options`. - temporal.api.deployment.v1.Deployment deployment = 9; + temporal.api.deployment.v1.Deployment deployment = 9 [deprecated = true]; // Worker deployment options that user has set in the worker. temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 10; } @@ -574,7 +574,7 @@ message RespondActivityTaskCompletedRequest { // Version info of the worker who processed this task. This message's `build_id` field should // always be set by SDKs. Workers opting into versioning will also set the `use_versioning` // field to true. See message docstrings for more. - // Deprecated. Use `deployment` instead. + // Deprecated. Use `deployment_options` instead. temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; // Deployment info of the worker that completed this task. Must be present if user has set // `WorkerDeploymentOptions` regardless of versioning being enabled or not. @@ -600,6 +600,8 @@ message RespondActivityTaskCompletedByIdRequest { temporal.api.common.v1.Payloads result = 5; // The identity of the worker/client string identity = 6; + // Worker deployment options that user has set in the worker. + temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 7; } message RespondActivityTaskCompletedByIdResponse { @@ -618,7 +620,7 @@ message RespondActivityTaskFailedRequest { // Version info of the worker who processed this task. This message's `build_id` field should // always be set by SDKs. Workers opting into versioning will also set the `use_versioning` // field to true. See message docstrings for more. - // Deprecated. Use `deployment` instead. + // Deprecated. Use `deployment_options` instead. temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; // Deployment info of the worker that completed this task. Must be present if user has set // `WorkerDeploymentOptions` regardless of versioning being enabled or not. @@ -649,6 +651,8 @@ message RespondActivityTaskFailedByIdRequest { string identity = 6; // Additional details to be stored as last activity heartbeat temporal.api.common.v1.Payloads last_heartbeat_details = 7; + // Worker deployment options that user has set in the worker. + temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 8; } message RespondActivityTaskFailedByIdResponse { @@ -668,7 +672,7 @@ message RespondActivityTaskCanceledRequest { // Version info of the worker who processed this task. This message's `build_id` field should // always be set by SDKs. Workers opting into versioning will also set the `use_versioning` // field to true. See message docstrings for more. - // Deprecated. Use `deployment` instead. + // Deprecated. Use `deployment_options` instead. temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; // Deployment info of the worker that completed this task. Must be present if user has set // `WorkerDeploymentOptions` regardless of versioning being enabled or not. @@ -694,6 +698,8 @@ message RespondActivityTaskCanceledByIdRequest { temporal.api.common.v1.Payloads details = 5; // The identity of the worker/client string identity = 6; + // Worker deployment options that user has set in the worker. + temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 7; } message RespondActivityTaskCanceledByIdResponse { From eb890b4a33b711498c7a3f8082f7bcf9aa96a661 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 15:15:30 -0700 Subject: [PATCH 25/31] make proto --- openapi/openapiv2.json | 74 +++++++++++++++++++++-------- openapi/openapiv3.yaml | 103 ++++++++++++++++++++++++++++++++--------- 2 files changed, 137 insertions(+), 40 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 058604bbe..338b73fc2 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7474,7 +7474,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment` instead." + "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment_options` instead." }, "deployment": { "$ref": "#/definitions/v1Deployment", @@ -7508,6 +7508,10 @@ "identity": { "type": "string", "title": "The identity of the worker/client" + }, + "deploymentOptions": { + "$ref": "#/definitions/v1WorkerDeploymentOptions", + "description": "Worker deployment options that user has set in the worker." } } }, @@ -7529,7 +7533,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment` instead." + "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment_options` instead." }, "deployment": { "$ref": "#/definitions/v1Deployment", @@ -7563,6 +7567,10 @@ "identity": { "type": "string", "title": "The identity of the worker/client" + }, + "deploymentOptions": { + "$ref": "#/definitions/v1WorkerDeploymentOptions", + "description": "Worker deployment options that user has set in the worker." } } }, @@ -7588,7 +7596,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment` instead." + "description": "Version info of the worker who processed this task. This message's `build_id` field should\nalways be set by SDKs. Workers opting into versioning will also set the `use_versioning`\nfield to true. See message docstrings for more.\nDeprecated. Use `deployment_options` instead." }, "deployment": { "$ref": "#/definitions/v1Deployment", @@ -7626,6 +7634,10 @@ "lastHeartbeatDetails": { "$ref": "#/definitions/v1Payloads", "title": "Additional details to be stored as last activity heartbeat" + }, + "deploymentOptions": { + "$ref": "#/definitions/v1WorkerDeploymentOptions", + "description": "Worker deployment options that user has set in the worker." } } }, @@ -8574,7 +8586,11 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "title": "Version info of the worker who processed this workflow task.\nDeprecated. Use the info inside the corresponding ActivityTaskStartedEvent" + "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version that processed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, @@ -8601,7 +8617,11 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "title": "Version info of the worker who processed this workflow task.\nDeprecated. Use the info inside the corresponding ActivityTaskStartedEvent" + "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version that completed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, @@ -8631,7 +8651,11 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "title": "Version info of the worker who processed this workflow task.\nDeprecated. Use the info inside the corresponding ActivityTaskStartedEvent" + "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version that failed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, @@ -9882,7 +9906,7 @@ "type": "string", "description": "Deprecated. Use `target_deployment_version`." }, - "targetDeploymentVersion": { + "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", "description": "The target Version of the transition.\nIf nil, a so-far-versioned workflow is transitioning to unversioned workers." } @@ -12706,7 +12730,7 @@ "properties": { "buildId": { "type": "string", - "description": "Worker build id." + "title": "Worker build id.\ntodo carly" }, "binaryChecksum": { "type": "string", @@ -14876,11 +14900,11 @@ }, "buildId": { "type": "string", - "description": "The Build ID of the worker. Required when `worker_versioning_mode==VERSIONED`, in which case,\nthe worker will be part of a Deployment Version identified by \".\"." + "description": "The Build ID of the worker. Required when `worker_versioning_mode==VERSIONED`, in which case,\nthe worker will be part of a Deployment Version." }, "workerVersioningMode": { "$ref": "#/definitions/v1WorkerVersioningMode", - "description": "Required. Versioning Mode for this worker. Must be the same for all workers with the\nsame `deployment_name` and `build_id` combination, across all Task Queues.\nWhen `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version\nidentified by \".\"." + "description": "Required. Versioning Mode for this worker. Must be the same for all workers with the\nsame `deployment_name` and `build_id` combination, across all Task Queues.\nWhen `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version." } }, "description": "Worker Deployment options set in SDK that need to be sent to server in every poll.\nExperimental. Worker Deployments are experimental and might significantly change in the future." @@ -15299,7 +15323,7 @@ }, "workerDeploymentName": { "type": "string", - "description": "The name of Worker Deployment that completed the most recent workflow task.\nExperimental. Worker Deployments are experimental and might change in the future." + "description": "The name of Worker Deployment that completed the most recent workflow task.\nExperimental. Worker Deployments are experimental and might change in the future.\nDeprecated. Replaced with `versioning_info.deployment_version`." }, "priority": { "$ref": "#/definitions/v1Priority", @@ -15505,6 +15529,10 @@ }, "parentPinnedWorkerDeploymentVersion": { "type": "string", + "description": "When present, it means this is a child workflow of a parent that is Pinned to this Worker\nDeployment Version. In this case, child workflow will start as Pinned to this Version instead\nof starting on the Current Version of its Task Queue.\nThis is set only if the child workflow is starting on a Task Queue belonging to the same\nWorker Deployment Version.\nDeprecated. Use `parent_pinned_deployment_version`." + }, + "parentPinnedDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", "description": "When present, it means this is a child workflow of a parent that is Pinned to this Worker\nDeployment Version. In this case, child workflow will start as Pinned to this Version instead\nof starting on the Current Version of its Task Queue.\nThis is set only if the child workflow is starting on a Task Queue belonging to the same\nWorker Deployment Version." }, "priority": { @@ -15653,7 +15681,7 @@ }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version that completed the last workflow task of this workflow execution.\nMust be present if and only if `behavior` is set. An absent value means no workflow task is\ncompleted, or the workflow is unversioned.\nFor child workflows of Pinned parents, this will be set to parent's Pinned Version when the\nthe child starts so that child's first workflow task goes to the same Version as the parent.\nNote that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version`\nwill override this value." + "description": "The Worker Deployment Version that completed the last workflow task of this workflow execution.\nAn absent value means no workflow task is completed, or the workflow is unversioned.\nIf present, and `behavior` is UNSPECIFIED, the last task of this workflow execution was completed\nby a worker that is not using versioning but _is_ passing Deployment Name and Build ID.\n\nFor child workflows of Pinned parents, this will be set to the parent's Pinned Version when\nthe child starts, so that the child's first workflow task goes to the same Version as the parent.\nNote that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version`\nwill override this value." }, "versioningOverride": { "$ref": "#/definitions/v1VersioningOverride", @@ -15852,11 +15880,11 @@ }, "binaryChecksum": { "type": "string", - "title": "Binary ID of the worker who completed this task" + "description": "Binary ID of the worker who completed this task\nDeprecated. Replaced with `deployment_version`." }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use `deployment` and `versioning_behavior` instead." + "description": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use `deployment_version` and `versioning_behavior` instead." }, "sdkMetadata": { "$ref": "#/definitions/v1WorkflowTaskCompletedMetadata", @@ -15868,7 +15896,7 @@ }, "deployment": { "$ref": "#/definitions/v1Deployment", - "description": "The deployment that completed this task. May or may not be set for unversioned workers,\ndepending on whether a value is sent by the SDK. This value updates workflow execution's\n`versioning_info.deployment`.\nDeprecated. Replaced with `worker_deployment_version`." + "description": "The deployment that completed this task. May or may not be set for unversioned workers,\ndepending on whether a value is sent by the SDK. This value updates workflow execution's\n`versioning_info.deployment`.\nDeprecated. Replaced with `deployment_version`." }, "versioningBehavior": { "$ref": "#/definitions/v1VersioningBehavior", @@ -15876,11 +15904,15 @@ }, "workerDeploymentVersion": { "type": "string", - "description": "The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `versioning_info.version`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "description": "The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `versioning_info.version`.\nExperimental. Worker Deployments are experimental and might significantly change in the future.\nDeprecated. Replaced with `deployment_version`." }, "workerDeploymentName": { "type": "string", - "description": "The name of Worker Deployment that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `worker_deployment_name`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "description": "The name of Worker Deployment that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `worker_deployment_name`.\nExperimental. Worker Deployments are experimental and might significantly change in the future.\nDeprecated. Use `deployment_version`." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `versioning_info.worker_deployment_version`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, @@ -15996,11 +16028,15 @@ }, "binaryChecksum": { "type": "string", - "title": "DEPRECATED since 1.21 - use `worker_version` instead.\nIf a worker explicitly failed this task, its binary id" + "description": "If a worker explicitly failed this task, its binary id\nDeprecated since 1.21. Use `deployment_version`." }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "title": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use the info inside the corresponding WorkflowTaskStartedEvent" + "description": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use `deployment_version` instead." + }, + "deploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "If a worker explicitly failed this task, its Worker Deployment Version.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index d8847c0a1..17828d0bf 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6063,7 +6063,13 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent + Deprecated. Use `deployment_version`. + deploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version that processed this task. + Experimental. Worker Deployments are experimental and might significantly change in the future. ActivityTaskCompletedEventAttributes: type: object properties: @@ -6085,7 +6091,13 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent + Deprecated. Use `deployment_version`. + deploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version that completed this task. + Experimental. Worker Deployments are experimental and might significantly change in the future. ActivityTaskFailedEventAttributes: type: object properties: @@ -6119,7 +6131,13 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use the info inside the corresponding ActivityTaskStartedEvent + Deprecated. Use `deployment_version`. + deploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version that failed this task. + Experimental. Worker Deployments are experimental and might significantly change in the future. ActivityTaskScheduledEventAttributes: type: object properties: @@ -7171,7 +7189,7 @@ components: version: type: string description: Deprecated. Use `target_deployment_version`. - targetDeploymentVersion: + deploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- @@ -9779,7 +9797,9 @@ components: properties: buildId: type: string - description: Worker build id. + description: |- + Worker build id. + todo carly binaryChecksum: type: string description: A worker binary version identifier (deprecated). @@ -9898,6 +9918,10 @@ components: identity: type: string description: The identity of the worker/client + deploymentOptions: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentOptions' + description: Worker deployment options that user has set in the worker. RespondActivityTaskCanceledByIdResponse: type: object properties: {} @@ -9924,7 +9948,7 @@ components: Version info of the worker who processed this task. This message's `build_id` field should always be set by SDKs. Workers opting into versioning will also set the `use_versioning` field to true. See message docstrings for more. - Deprecated. Use `deployment` instead. + Deprecated. Use `deployment_options` instead. deployment: allOf: - $ref: '#/components/schemas/Deployment' @@ -9961,6 +9985,10 @@ components: identity: type: string description: The identity of the worker/client + deploymentOptions: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentOptions' + description: Worker deployment options that user has set in the worker. RespondActivityTaskCompletedByIdResponse: type: object properties: {} @@ -9987,7 +10015,7 @@ components: Version info of the worker who processed this task. This message's `build_id` field should always be set by SDKs. Workers opting into versioning will also set the `use_versioning` field to true. See message docstrings for more. - Deprecated. Use `deployment` instead. + Deprecated. Use `deployment_options` instead. deployment: allOf: - $ref: '#/components/schemas/Deployment' @@ -10028,6 +10056,10 @@ components: allOf: - $ref: '#/components/schemas/Payloads' description: Additional details to be stored as last activity heartbeat + deploymentOptions: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentOptions' + description: Worker deployment options that user has set in the worker. RespondActivityTaskFailedByIdResponse: type: object properties: @@ -10065,7 +10097,7 @@ components: Version info of the worker who processed this task. This message's `build_id` field should always be set by SDKs. Workers opting into versioning will also set the `use_versioning` field to true. See message docstrings for more. - Deprecated. Use `deployment` instead. + Deprecated. Use `deployment_options` instead. deployment: allOf: - $ref: '#/components/schemas/Deployment' @@ -12223,7 +12255,7 @@ components: type: string description: |- The Build ID of the worker. Required when `worker_versioning_mode==VERSIONED`, in which case, - the worker will be part of a Deployment Version identified by ".". + the worker will be part of a Deployment Version. workerVersioningMode: enum: - WORKER_VERSIONING_MODE_UNSPECIFIED @@ -12233,8 +12265,7 @@ components: description: |- Required. Versioning Mode for this worker. Must be the same for all workers with the same `deployment_name` and `build_id` combination, across all Task Queues. - When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version - identified by ".". + When `worker_versioning_mode==VERSIONED`, the worker will be part of a Deployment Version. format: enum description: |- Worker Deployment options set in SDK that need to be sent to server in every poll. @@ -12810,6 +12841,7 @@ components: description: |- The name of Worker Deployment that completed the most recent workflow task. Experimental. Worker Deployments are experimental and might change in the future. + Deprecated. Replaced with `versioning_info.deployment_version`. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -13030,6 +13062,16 @@ components: description: Versioning override applied to this workflow when it was started. parentPinnedWorkerDeploymentVersion: type: string + description: |- + When present, it means this is a child workflow of a parent that is Pinned to this Worker + Deployment Version. In this case, child workflow will start as Pinned to this Version instead + of starting on the Current Version of its Task Queue. + This is set only if the child workflow is starting on a Task Queue belonging to the same + Worker Deployment Version. + Deprecated. Use `parent_pinned_deployment_version`. + parentPinnedDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- When present, it means this is a child workflow of a parent that is Pinned to this Worker Deployment Version. In this case, child workflow will start as Pinned to this Version instead @@ -13185,10 +13227,12 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- The Worker Deployment Version that completed the last workflow task of this workflow execution. - Must be present if and only if `behavior` is set. An absent value means no workflow task is - completed, or the workflow is unversioned. - For child workflows of Pinned parents, this will be set to parent's Pinned Version when the - the child starts so that child's first workflow task goes to the same Version as the parent. + An absent value means no workflow task is completed, or the workflow is unversioned. + If present, and `behavior` is UNSPECIFIED, the last task of this workflow execution was completed + by a worker that is not using versioning but _is_ passing Deployment Name and Build ID. + + For child workflows of Pinned parents, this will be set to the parent's Pinned Version when + the child starts, so that the child's first workflow task goes to the same Version as the parent. Note that if `versioning_override.behavior` is PINNED then `versioning_override.pinned_version` will override this value. versioningOverride: @@ -13398,7 +13442,9 @@ components: description: Identity of the worker who completed this task binaryChecksum: type: string - description: Binary ID of the worker who completed this task + description: |- + Binary ID of the worker who completed this task + Deprecated. Replaced with `deployment_version`. workerVersion: allOf: - $ref: '#/components/schemas/WorkerVersionStamp' @@ -13406,7 +13452,7 @@ components: Version info of the worker who processed this workflow task. If present, the `build_id` field within is also used as `binary_checksum`, which may be omitted in that case (it may also be populated to preserve compatibility). - Deprecated. Use `deployment` and `versioning_behavior` instead. + Deprecated. Use `deployment_version` and `versioning_behavior` instead. sdkMetadata: allOf: - $ref: '#/components/schemas/WorkflowTaskCompletedMetadata' @@ -13424,7 +13470,7 @@ components: The deployment that completed this task. May or may not be set for unversioned workers, depending on whether a value is sent by the SDK. This value updates workflow execution's `versioning_info.deployment`. - Deprecated. Replaced with `worker_deployment_version`. + Deprecated. Replaced with `deployment_version`. versioningBehavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED @@ -13442,12 +13488,21 @@ components: The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` is set. This value updates workflow execution's `versioning_info.version`. Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. Replaced with `deployment_version`. workerDeploymentName: type: string description: |- The name of Worker Deployment that completed this task. Must be set if `versioning_behavior` is set. This value updates workflow execution's `worker_deployment_name`. Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. Use `deployment_version`. + deploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` + is set. This value updates workflow execution's `versioning_info.worker_deployment_version`. + Experimental. Worker Deployments are experimental and might significantly change in the future. WorkflowTaskCompletedMetadata: type: object properties: @@ -13571,8 +13626,8 @@ components: binaryChecksum: type: string description: |- - DEPRECATED since 1.21 - use `worker_version` instead. - If a worker explicitly failed this task, its binary id + If a worker explicitly failed this task, its binary id + Deprecated since 1.21. Use `deployment_version`. workerVersion: allOf: - $ref: '#/components/schemas/WorkerVersionStamp' @@ -13580,7 +13635,13 @@ components: Version info of the worker who processed this workflow task. If present, the `build_id` field within is also used as `binary_checksum`, which may be omitted in that case (it may also be populated to preserve compatibility). - Deprecated. Use the info inside the corresponding WorkflowTaskStartedEvent + Deprecated. Use `deployment_version` instead. + deploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + If a worker explicitly failed this task, its Worker Deployment Version. + Experimental. Worker Deployments are experimental and might significantly change in the future. WorkflowTaskScheduledEventAttributes: type: object properties: From 36ccde38f089651ec95be5280cf3edf011f40fc9 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 15:58:08 -0700 Subject: [PATCH 26/31] Use correct new field names in deprecation comments --- temporal/api/history/v1/message.proto | 2 +- temporal/api/workflow/v1/message.proto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 3ad21153b..3133a1d03 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -273,7 +273,7 @@ message WorkflowTaskCompletedEventAttributes { // Deprecated. Use `deployment_version`. string worker_deployment_name = 10 [deprecated = true]; // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` - // is set. This value updates workflow execution's `versioning_info.worker_deployment_version`. + // is set. This value updates workflow execution's `versioning_info.deployment_version`. // Experimental. Worker Deployments are experimental and might significantly change in the future. temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 11; } diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index b875c1886..b64d1352f 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -223,7 +223,7 @@ message DeploymentTransition { // deployment version to another. // Experimental. Might change in the future. message DeploymentVersionTransition { - // Deprecated. Use `target_deployment_version`. + // Deprecated. Use `deployment_version`. string version = 1 [deprecated = true]; // The target Version of the transition. From 8d28e6eafe2bd7726aae0df78cab52d163cb2ea0 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 15:59:11 -0700 Subject: [PATCH 27/31] make proto --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 338b73fc2..39896d861 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -9904,7 +9904,7 @@ "properties": { "version": { "type": "string", - "description": "Deprecated. Use `target_deployment_version`." + "description": "Deprecated. Use `deployment_version`." }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", @@ -15912,7 +15912,7 @@ }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `versioning_info.worker_deployment_version`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "description": "The Worker Deployment Version that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `versioning_info.deployment_version`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 17828d0bf..b51c58368 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -7188,7 +7188,7 @@ components: properties: version: type: string - description: Deprecated. Use `target_deployment_version`. + description: Deprecated. Use `deployment_version`. deploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' @@ -13501,7 +13501,7 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: |- The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` - is set. This value updates workflow execution's `versioning_info.worker_deployment_version`. + is set. This value updates workflow execution's `versioning_info.deployment_version`. Experimental. Worker Deployments are experimental and might significantly change in the future. WorkflowTaskCompletedMetadata: type: object From e4f7d7da21c05fa929b51d5db6c227399d9925e9 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 20:41:32 -0700 Subject: [PATCH 28/31] don't put completed version in activity events --- openapi/openapiv2.json | 24 +++++-------------- openapi/openapiv3.yaml | 33 ++++++-------------------- temporal/api/history/v1/message.proto | 20 +++++----------- temporal/api/workflow/v1/message.proto | 1 - 4 files changed, 19 insertions(+), 59 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 39896d861..9063ef033 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -8617,11 +8617,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version that completed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "title": "Version info of the worker who processed this workflow task.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" } } }, @@ -8651,11 +8647,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version that failed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "title": "Version info of the worker who processed this workflow task.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" } } }, @@ -8705,7 +8697,7 @@ }, "useWorkflowBuildId": { "type": "boolean", - "description": "If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,\nAssignment rules of the activity's Task Queue will be used to determine the Build ID." + "title": "If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise,\nAssignment rules of the activity's Task Queue will be used to determine the Build ID.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" }, "priority": { "$ref": "#/definitions/v1Priority", @@ -12730,7 +12722,7 @@ "properties": { "buildId": { "type": "string", - "title": "Worker build id.\ntodo carly" + "description": "Worker build id." }, "binaryChecksum": { "type": "string", @@ -16028,15 +16020,11 @@ }, "binaryChecksum": { "type": "string", - "description": "If a worker explicitly failed this task, its binary id\nDeprecated since 1.21. Use `deployment_version`." + "title": "DEPRECATED since 1.21 - This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]\nIf a worker explicitly failed this task, its binary id" }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. Use `deployment_version` instead." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "If a worker explicitly failed this task, its Worker Deployment Version.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "title": "Version info of the worker who processed this workflow task. If present, the `build_id` field\nwithin is also used as `binary_checksum`, which may be omitted in that case (it may also be\npopulated to preserve compatibility).\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b51c58368..3b3e27084 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6091,13 +6091,7 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use `deployment_version`. - deploymentVersion: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - The Worker Deployment Version that completed this task. - Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] ActivityTaskFailedEventAttributes: type: object properties: @@ -6131,13 +6125,7 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use `deployment_version`. - deploymentVersion: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - The Worker Deployment Version that failed this task. - Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] ActivityTaskScheduledEventAttributes: type: object properties: @@ -6201,6 +6189,7 @@ components: description: |- If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise, Assignment rules of the activity's Task Queue will be used to determine the Build ID. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] priority: allOf: - $ref: '#/components/schemas/Priority' @@ -9797,9 +9786,7 @@ components: properties: buildId: type: string - description: |- - Worker build id. - todo carly + description: Worker build id. binaryChecksum: type: string description: A worker binary version identifier (deprecated). @@ -13626,8 +13613,8 @@ components: binaryChecksum: type: string description: |- - If a worker explicitly failed this task, its binary id - Deprecated since 1.21. Use `deployment_version`. + DEPRECATED since 1.21 - This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] + If a worker explicitly failed this task, its binary id workerVersion: allOf: - $ref: '#/components/schemas/WorkerVersionStamp' @@ -13635,13 +13622,7 @@ components: Version info of the worker who processed this workflow task. If present, the `build_id` field within is also used as `binary_checksum`, which may be omitted in that case (it may also be populated to preserve compatibility). - Deprecated. Use `deployment_version` instead. - deploymentVersion: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - If a worker explicitly failed this task, its Worker Deployment Version. - Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] WorkflowTaskScheduledEventAttributes: type: object properties: diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 3133a1d03..429f16e07 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -302,17 +302,14 @@ message WorkflowTaskFailedEventAttributes { string new_run_id = 7; // TODO: ? int64 fork_event_version = 8; + // DEPRECATED since 1.21 - This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] // If a worker explicitly failed this task, its binary id - // Deprecated since 1.21. Use `deployment_version`. string binary_checksum = 9 [deprecated = true]; // Version info of the worker who processed this workflow task. If present, the `build_id` field // within is also used as `binary_checksum`, which may be omitted in that case (it may also be // populated to preserve compatibility). - // Deprecated. Use `deployment_version` instead. + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] temporal.api.common.v1.WorkerVersionStamp worker_version = 10 [deprecated = true]; - // If a worker explicitly failed this task, its Worker Deployment Version. - // Experimental. Worker Deployments are experimental and might significantly change in the future. - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 11; } message ActivityTaskScheduledEventAttributes { @@ -355,7 +352,8 @@ message ActivityTaskScheduledEventAttributes { temporal.api.common.v1.RetryPolicy retry_policy = 12; // If this is set, the activity would be assigned to the Build ID of the workflow. Otherwise, // Assignment rules of the activity's Task Queue will be used to determine the Build ID. - bool use_workflow_build_id = 13; + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] + bool use_workflow_build_id = 13 [deprecated = true]; // Priority metadata. If this message is not present, or any fields are not // present, they inherit the values from the workflow. temporal.api.common.v1.Priority priority = 14; @@ -392,11 +390,8 @@ message ActivityTaskCompletedEventAttributes { // id of the worker that completed this task string identity = 4; // Version info of the worker who processed this workflow task. - // Deprecated. Use `deployment_version`. + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] temporal.api.common.v1.WorkerVersionStamp worker_version = 5 [deprecated = true]; - // The Worker Deployment Version that completed this task. - // Experimental. Worker Deployments are experimental and might significantly change in the future. - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 6; } message ActivityTaskFailedEventAttributes { @@ -410,11 +405,8 @@ message ActivityTaskFailedEventAttributes { string identity = 4; temporal.api.enums.v1.RetryState retry_state = 5; // Version info of the worker who processed this workflow task. - // Deprecated. Use `deployment_version`. + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; - // The Worker Deployment Version that failed this task. - // Experimental. Worker Deployments are experimental and might significantly change in the future. - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; } message ActivityTaskTimedOutEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index b64d1352f..05b313ed2 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -366,7 +366,6 @@ message ResetPoints { // checksum changes (although in general only one or the other will be used at a time). message ResetPointInfo { // Worker build id. - // todo carly string build_id = 7; // A worker binary version identifier (deprecated). string binary_checksum = 1 [deprecated = true]; From 4556b72e794011eb6f880ead348d6588ffc3cb67 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Wed, 7 May 2025 21:37:00 -0700 Subject: [PATCH 29/31] more minor cleanup, making things consistent --- openapi/openapiv2.json | 14 +------------- openapi/openapiv3.yaml | 16 +--------------- temporal/api/history/v1/message.proto | 7 ++----- temporal/api/workflow/v1/message.proto | 6 +++--- .../workflowservice/v1/request_response.proto | 6 +----- 5 files changed, 8 insertions(+), 41 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 9063ef033..0c778c409 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -7567,10 +7567,6 @@ "identity": { "type": "string", "title": "The identity of the worker/client" - }, - "deploymentOptions": { - "$ref": "#/definitions/v1WorkerDeploymentOptions", - "description": "Worker deployment options that user has set in the worker." } } }, @@ -7634,10 +7630,6 @@ "lastHeartbeatDetails": { "$ref": "#/definitions/v1Payloads", "title": "Additional details to be stored as last activity heartbeat" - }, - "deploymentOptions": { - "$ref": "#/definitions/v1WorkerDeploymentOptions", - "description": "Worker deployment options that user has set in the worker." } } }, @@ -8586,11 +8578,7 @@ }, "workerVersion": { "$ref": "#/definitions/v1WorkerVersionStamp", - "description": "Version info of the worker who processed this workflow task.\nDeprecated. Use `deployment_version`." - }, - "deploymentVersion": { - "$ref": "#/definitions/v1WorkerDeploymentVersion", - "description": "The Worker Deployment Version that processed this task.\nExperimental. Worker Deployments are experimental and might significantly change in the future." + "title": "Version info of the worker who processed this workflow task.\nDeprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv]" } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 3b3e27084..dffdd5995 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -6063,13 +6063,7 @@ components: - $ref: '#/components/schemas/WorkerVersionStamp' description: |- Version info of the worker who processed this workflow task. - Deprecated. Use `deployment_version`. - deploymentVersion: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentVersion' - description: |- - The Worker Deployment Version that processed this task. - Experimental. Worker Deployments are experimental and might significantly change in the future. + Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] ActivityTaskCompletedEventAttributes: type: object properties: @@ -9972,10 +9966,6 @@ components: identity: type: string description: The identity of the worker/client - deploymentOptions: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentOptions' - description: Worker deployment options that user has set in the worker. RespondActivityTaskCompletedByIdResponse: type: object properties: {} @@ -10043,10 +10033,6 @@ components: allOf: - $ref: '#/components/schemas/Payloads' description: Additional details to be stored as last activity heartbeat - deploymentOptions: - allOf: - - $ref: '#/components/schemas/WorkerDeploymentOptions' - description: Worker deployment options that user has set in the worker. RespondActivityTaskFailedByIdResponse: type: object properties: diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 429f16e07..ee2a6c5bb 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -440,11 +440,8 @@ message ActivityTaskCanceledEventAttributes { // id of the worker who canceled this activity string identity = 5; // Version info of the worker who processed this workflow task. - // Deprecated. Use `deployment_version`. - temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true]; - // The Worker Deployment Version that processed this task. - // Experimental. Worker Deployments are experimental and might significantly change in the future. - temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 7; + // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] + temporal.api.common.v1.WorkerVersionStamp worker_version = 6 [deprecated = true];; } message TimerStartedEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 05b313ed2..566264461 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -261,16 +261,16 @@ message PendingActivityInfo { // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] oneof assigned_build_id { // When present, it means this activity is assigned to the build ID of its workflow. - google.protobuf.Empty use_workflow_build_id = 13; + google.protobuf.Empty use_workflow_build_id = 13 [deprecated = true]; // This means the activity is independently versioned and not bound to the build ID of its workflow. // The activity will use the build id in this field instead. // If the task fails and is scheduled again, the assigned build ID may change according to the latest versioning // rules. - string last_independently_assigned_build_id = 14; + string last_independently_assigned_build_id = 14 [deprecated = true]; } // The version stamp of the worker to whom this activity was most recently dispatched // Deprecated. This field should be cleaned up when versioning-2 API is removed. [cleanup-experimental-wv] - temporal.api.common.v1.WorkerVersionStamp last_worker_version_stamp = 15; + temporal.api.common.v1.WorkerVersionStamp last_worker_version_stamp = 15 [deprecated = true]; // The time activity will wait until the next retry. // If activity is currently running it will be next retry interval if activity failed. diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 76582d7a9..43993e246 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -254,7 +254,7 @@ message PollWorkflowTaskQueueRequest { temporal.api.taskqueue.v1.TaskQueue task_queue = 2; // The identity of the worker/client who is polling this task queue string identity = 3; - // DEPRECATED since 1.21 - use `deployment_option` instead. + // DEPRECATED since 1.21 - use `deployment_options` instead. // Each worker process should provide an ID unique to the specific set of code it is running // "checksum" in this field name isn't very accurate, it should be though of as an id. string binary_checksum = 4 [deprecated = true]; @@ -578,8 +578,6 @@ message RespondActivityTaskCompletedByIdRequest { temporal.api.common.v1.Payloads result = 5; // The identity of the worker/client string identity = 6; - // Worker deployment options that user has set in the worker. - temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 7; } message RespondActivityTaskCompletedByIdResponse { @@ -629,8 +627,6 @@ message RespondActivityTaskFailedByIdRequest { string identity = 6; // Additional details to be stored as last activity heartbeat temporal.api.common.v1.Payloads last_heartbeat_details = 7; - // Worker deployment options that user has set in the worker. - temporal.api.deployment.v1.WorkerDeploymentOptions deployment_options = 8; } message RespondActivityTaskFailedByIdResponse { From 8826845c180584a449f9618f21ec7bb34c94d607 Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Thu, 8 May 2025 00:39:12 -0700 Subject: [PATCH 30/31] revert deployment_name deprecation --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 2 -- temporal/api/history/v1/message.proto | 3 +-- temporal/api/workflow/v1/message.proto | 3 +-- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 0c778c409..22afd6c08 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -15303,7 +15303,7 @@ }, "workerDeploymentName": { "type": "string", - "description": "The name of Worker Deployment that completed the most recent workflow task.\nExperimental. Worker Deployments are experimental and might change in the future.\nDeprecated. Replaced with `versioning_info.deployment_version`." + "description": "The name of Worker Deployment that completed the most recent workflow task.\nExperimental. Worker Deployments are experimental and might change in the future." }, "priority": { "$ref": "#/definitions/v1Priority", @@ -15888,7 +15888,7 @@ }, "workerDeploymentName": { "type": "string", - "description": "The name of Worker Deployment that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `worker_deployment_name`.\nExperimental. Worker Deployments are experimental and might significantly change in the future.\nDeprecated. Use `deployment_version`." + "description": "The name of Worker Deployment that completed this task. Must be set if `versioning_behavior`\nis set. This value updates workflow execution's `worker_deployment_name`.\nExperimental. Worker Deployments are experimental and might significantly change in the future." }, "deploymentVersion": { "$ref": "#/definitions/v1WorkerDeploymentVersion", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index dffdd5995..fbfcb8dbb 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -12814,7 +12814,6 @@ components: description: |- The name of Worker Deployment that completed the most recent workflow task. Experimental. Worker Deployments are experimental and might change in the future. - Deprecated. Replaced with `versioning_info.deployment_version`. priority: allOf: - $ref: '#/components/schemas/Priority' @@ -13468,7 +13467,6 @@ components: The name of Worker Deployment that completed this task. Must be set if `versioning_behavior` is set. This value updates workflow execution's `worker_deployment_name`. Experimental. Worker Deployments are experimental and might significantly change in the future. - Deprecated. Use `deployment_version`. deploymentVersion: allOf: - $ref: '#/components/schemas/WorkerDeploymentVersion' diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index ee2a6c5bb..9c77ae452 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -270,8 +270,7 @@ message WorkflowTaskCompletedEventAttributes { // The name of Worker Deployment that completed this task. Must be set if `versioning_behavior` // is set. This value updates workflow execution's `worker_deployment_name`. // Experimental. Worker Deployments are experimental and might significantly change in the future. - // Deprecated. Use `deployment_version`. - string worker_deployment_name = 10 [deprecated = true]; + string worker_deployment_name = 10; // The Worker Deployment Version that completed this task. Must be set if `versioning_behavior` // is set. This value updates workflow execution's `versioning_info.deployment_version`. // Experimental. Worker Deployments are experimental and might significantly change in the future. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 566264461..3c3582c16 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -93,8 +93,7 @@ message WorkflowExecutionInfo { // The name of Worker Deployment that completed the most recent workflow task. // Experimental. Worker Deployments are experimental and might change in the future. - // Deprecated. Replaced with `versioning_info.deployment_version`. - string worker_deployment_name = 23 [deprecated = true]; + string worker_deployment_name = 23; // Priority metadata temporal.api.common.v1.Priority priority = 24; From 4a4cf62a6b65909b751e9eab0f90e962b960990d Mon Sep 17 00:00:00 2001 From: Carly de Frondeville Date: Fri, 9 May 2025 15:39:16 -0700 Subject: [PATCH 31/31] merge main --- temporal/api/workflow/v1/message.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 4ebfc6f2d..98134eb14 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -297,7 +297,7 @@ message PendingActivityInfo { string last_worker_deployment_version = 21 [deprecated = true]; // The Worker Deployment Version this activity was dispatched to most recently. // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. - temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 24; + temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 25; // Priority metadata