Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Use string values for deployment version #547

Merged
merged 7 commits into from
Feb 3, 2025
Merged

Use string values for deployment version #547

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1d8affa
Use string values for deployment version
ShahabT Feb 3, 2025
f568e3a
Add skip-drainage flag for DeleteVersion
ShahabT Feb 3, 2025
8f16501
address comments
ShahabT Feb 3, 2025
821a99a
address comments
ShahabT Feb 3, 2025
b1ec4f5
Apply suggestions from code review
ShahabT Feb 3, 2025
022a853
Merge remote-tracking branch 'origin/shahab/build-id' into shahab/bui…
ShahabT Feb 3, 2025
7769dc5
address comments
ShahabT Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
560 changes: 260 additions & 300 deletions openapi/openapiv2.json
View file
Open in desktop

Large diffs are not rendered by default.

660 changes: 303 additions & 357 deletions openapi/openapiv3.yaml
View file
Open in desktop

Large diffs are not rendered by default.

50 changes: 18 additions & 32 deletions temporal/api/deployment/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,14 @@ import "temporal/api/common/v1/message.proto";
message WorkerDeploymentOptions {
// Required. Worker Deployment name.
string deployment_name = 1;
// Required. Build ID of the worker. `deployment_name` and `build_id` together identify this
// Worker Deployment Version.
// 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 "<deployment_name>/<build_id>".
string build_id = 2;
// Required. Workflow versioning mode for this Deployment Version. Must be the same for all
// pollers in a given Deployment Version, across all Task Queues.
temporal.api.enums.v1.WorkflowVersioningMode workflow_versioning_mode = 3;
// 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 "<deployment_name>/<build_id>".
temporal.api.enums.v1.WorkerVersioningMode worker_versioning_mode = 3;
}

// `Deployment` identifies a deployment of Temporal workers. The combination of deployment series
Expand All @@ -65,16 +67,6 @@ message Deployment {
string build_id = 2;
}

// Identifies a Worker Deployment Version. The combination of `deployment_name` and `build_id`
// serve as the identifier.
message WorkerDeploymentVersion {
// The name of the Deployment this version belongs too.
string deployment_name = 1;
// Build ID uniquely identifies the Deployment Version within a Deployment, but the same Build
// ID can be used in multiple Deployments.
string build_id = 2;
}

// `DeploymentInfo` holds information about a deployment. Deployment information is tracked
// automatically by server as soon as the first poll from that deployment reaches the server. There
// can be multiple task queue workers in a single deployment which are listed in this message.
Expand Down Expand Up @@ -122,11 +114,10 @@ message DeploymentListInfo {
// non-determinism issues.
// Worker Deployment Versions are created in Temporal server automatically when
// their first poller arrives to the server.
// Each Version has a Workflow Versioning Mode which is chosen by the app
// developer. (see WorkflowVersioningMode enum documentation)
message WorkerDeploymentVersionInfo {
WorkerDeploymentVersion version = 1;
temporal.api.enums.v1.WorkflowVersioningMode workflow_versioning_mode = 2;
// The fully-qualified string representation of the version, in the form "<deployment_name>/<build_id>".
string version = 1;
string deployment_name = 2;
google.protobuf.Timestamp create_time = 3;

// Last time `current_since_time`, `ramping_since_time, or `ramp_percentage` of this version changed.
Expand Down Expand Up @@ -204,7 +195,7 @@ message WorkerDeploymentInfo {

google.protobuf.Timestamp create_time = 3;

RoutingInfo routing_info = 4;
RoutingConfig routing_config = 4;

// Identity of the last client who modified the configuration of this Deployment. Set to the
// `identity` value sent by APIs such as `SetWorkerDeploymentCurrentVersion` and
Expand All @@ -216,9 +207,8 @@ message WorkerDeploymentInfo {
message WorkerDeploymentVersionSummary {
// The fully-qualified string representation of the version, in the form "<deployment_name>/<build_id>".
string version = 1;
temporal.api.enums.v1.WorkflowVersioningMode workflow_versioning_mode = 2;
google.protobuf.Timestamp create_time = 3;
enums.v1.VersionDrainageStatus drainage_status = 4;
google.protobuf.Timestamp create_time = 2;
enums.v1.VersionDrainageStatus drainage_status = 3;
}
}

Expand All @@ -227,26 +217,22 @@ message VersionMetadata {
map<string, temporal.api.common.v1.Payload> entries = 1;
}

message RoutingInfo {
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:
// - The fully-qualified string representation of a Version of this Deployment that supports
// Versioning Behaviors (i.e. has `WorkflowVersioningMode==VERSIONING_BEHAVIORS`). In the
// format "<deployment_name>/<build_id>".
// - A Deployment Version identifier in the form "<deployment_name>/<build_id>".
// - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
// with `UNVERSIONED` (or unspecified) `WorkflowVersioningMode`.)
// 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:
// - The fully-qualified string representation of a Version of this Deployment that supports
// Versioning Behaviors (i.e. has `WorkflowVersioningMode==VERSIONING_BEHAVIORS`). In the
// format "<deployment_name>/<build_id>".
// - A Deployment Version identifier in the form "<deployment_name>/<build_id>".
// - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
// with `UNVERSIONED` (or unspecified) `WorkflowVersioningMode`.)
// 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.
string ramping_version = 2;
Expand Down
47 changes: 26 additions & 21 deletions temporal/api/enums/v1/deployment.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,25 +65,30 @@ enum VersionDrainageStatus {
VERSION_DRAINAGE_STATUS_DRAINED = 2;
}

// Workflow Versioning Mode for a particular Worker Deployment Version. This value is
// configured by the app developer in the worker code.
enum WorkflowVersioningMode {
WORKFLOW_VERSIONING_MODE_UNSPECIFIED = 0;
// Workflows processed by this Deployment Version will be unversioned and user
// needs to use Patching to keep the new code compatible with prior versions.
// This mode is recommended to be used along with Rolling Upgrade deployment
// strategies.
// Deployment Versions with this mode can not be set as the Current or Ramping
// Version of their Deployment, and are not distinguished from each other for
// task routing.
WORKFLOW_VERSIONING_MODE_UNVERSIONED = 1;
// Workflow Versioning Behaviors are enabled in this Deployment Version. Each
// workflow type must choose between the Pinned and AutoUpgrade behaviors.
// Depending on the chosen behavior user may or may not need to use Patching
// to keep the new code compatible with prior versions. (see VersioningBehavior
// enum.)
// Deployment Versions with this mode can be set as the Current or Ramping
// Version of their Deployment and hence are the best option for Blue/Green
// and Rainbow strategies (but typically not suitable for Rolling upgrades.)
WORKFLOW_VERSIONING_MODE_VERSIONING_BEHAVIORS = 2;
// Versioning Mode of a worker is set by the app developer in the worker code, and specifies the
// behavior of the system in the following related aspects:
// - Whether or not Temporal Server considers this worker's version (Build ID) when dispatching
// tasks to it.
// - Whether or not the workflows processed by this worker are versioned using the worker's version.
enum WorkerVersioningMode {
WORKER_VERSIONING_MODE_UNSPECIFIED = 0;
// Workers with this mode are not distinguished from each other for task routing, even if they
// have different Build IDs.
// Workflows processed by this worker will be unversioned and user needs to use Patching to keep
// the new code compatible with prior versions.
// This mode is recommended to be used along with Rolling Upgrade deployment strategies.
// Workers with this mode are represented by the special string `__unversioned__` in the APIs.
WORKER_VERSIONING_MODE_UNVERSIONED = 1;
// Workers with this mode are part of a Worker Deployment Version which is identified as
// "<deployment_name>/<build_id>". Such workers are called "versioned" as opposed to
// "unversioned".
// Each Deployment Version is distinguished from other Versions for task routing and users can
// configure Temporal Server to send tasks to a particular Version (see
// `WorkerDeploymentInfo.routing_config`). This mode is the best option for Blue/Green and
// Rainbow strategies (but typically not suitable for Rolling upgrades.)
// Workflow Versioning Behaviors are enabled in this mode: each workflow type must choose
// between the Pinned and AutoUpgrade behaviors. Depending on the chosen behavior, the user may
// or may not need to use Patching to keep the new code compatible with prior versions. (see
// VersioningBehavior enum.)
WORKER_VERSIONING_MODE_VERSIONED = 2;
}
11 changes: 5 additions & 6 deletions temporal/api/enums/v1/workflow.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,15 +145,14 @@ enum TimeoutType {
// existing workflows (see VersioningOverride).
enum VersioningBehavior {
// Workflow execution does not have a Versioning Behavior and is called Unversioned. This is the
// legacy behavior. An Unversioned workflow's task may go to any worker who is polling for the
// Task Queue and has WorkflowVersioningMode == UNVERSIONED (or has not specified a
// WorkflowVersioningMode).
// legacy behavior. An Unversioned workflow's task can go to any Unversioned worker (see
// `WorkerVersioningMode`.)
// User needs to use Patching to keep the new code compatible with prior versions when dealing
// with Unversioned workflows.
VERSIONING_BEHAVIOR_UNSPECIFIED = 0;
// Workflow will start on the Current Deployment Version of its Task Queue, and then
// will be pinned to that same Deployment Version until completion (the version that
// a Workflow is pinned to is specified in `versioning_info.deployment_version`).
// will be pinned to that same Deployment Version until completion (the Version that
// this Workflow is pinned to is specified in `versioning_info.version`).
// This behavior eliminates most of compatibility concerns users face when changing their code.
// Patching is not needed when pinned workflows code change.
// Can be overridden explicitly via `UpdateWorkflowExecutionOptions` API to move the
Expand All @@ -169,7 +168,7 @@ enum VersioningBehavior {
// latest Deployment Version, but the user still needs to use Patching to keep the new code
// compatible with prior versions for changed workflow types.
// Activities of `AUTO_UPGRADE` workflows are sent to the Deployment Version of the workflow
// execution (as specified in versioning_info.deployment_version based on the last completed
// execution (as specified in versioning_info.version based on the last completed
// workflow task). Exception to this would be when the activity Task Queue workers are not
// present in the workflow's Deployment Version, in which case, the activity will be sent to a
// different Deployment Version according to the Current Deployment Version of its own task
Expand Down
12 changes: 7 additions & 5 deletions temporal/api/history/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,16 +251,18 @@ 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 `deployment_version`.
// Deprecated. Replaced with `worker_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
// updates workflow execution's `versioning_info.behavior`.
temporal.api.enums.v1.VersioningBehavior versioning_behavior = 8;
// The deployment version of the worker that completed this task. Must be set if
// `versioning_behavior` is set. This value updates workflow execution's
// `versioning_info.deployment_version`.
temporal.api.deployment.v1.WorkerDeploymentVersion deployment_version = 9;
// 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`.
string worker_deployment_version = 9;
// 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`.
string worker_deployment_name = 10;
}

message WorkflowTaskTimedOutEventAttributes {
Expand Down
18 changes: 8 additions & 10 deletions temporal/api/taskqueue/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,26 +56,24 @@ message TaskQueueMetadata {
}

message TaskQueueVersioningInfo {
// Always present. Specifies which Deployment Version should should receive new workflow
// 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:
// - The Build ID of a Version of this Deployment that supports Versioning Behaviors (i.e. has
// `WorkflowVersioningMode==VERSIONING_BEHAVIORS`.)
// - A Deployment Version identifier in the form "<deployment_name>/<build_id>".
// - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
// with `UNVERSIONED` (or unspecified) `WorkflowVersioningMode`.)
// 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`.)
temporal.api.deployment.v1.WorkerDeploymentVersion current_version = 1;
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:
// - The Build ID of a Version of this Deployment that supports Versioning Behaviors (i.e. has
// `WorkflowVersioningMode==VERSIONING_BEHAVIORS`.)
// Must always be different from `current_version`. Can be one of the following:
// - A Deployment Version identifier in the form "<deployment_name>/<build_id>".
// - Or, the "__unversioned__" special value, to represent all the unversioned workers (those
// with `UNVERSIONED` (or unspecified) `WorkflowVersioningMode`.)
// 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.
temporal.api.deployment.v1.WorkerDeploymentVersion ramping_version = 2;
string ramping_version = 2;
// 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.
Expand Down
Loading
Loading