diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3d46f56df..2e4975596 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -747,6 +747,231 @@ ] } }, + "/api/v1/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { + "post": { + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetCurrentDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { + "get": { + "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "GetCurrentDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "seriesName", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments": { + "get": { + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "ListDeployments2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListDeploymentsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "get": { + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeDeployment2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeDeploymentResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { + "get": { + "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "GetDeploymentReachability2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/schedules": { "get": { "summary": "List all schedules in a namespace.", @@ -3122,7 +3347,277 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/activities/update-options-by-id": { + "post": { + "summary": "UpdateActivityOptionsById is called by the client to update the options of an activity", + "operationId": "UpdateActivityOptionsById", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UpdateActivityOptionsByIdResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsByIdBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/archived-workflows": { + "get": { + "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", + "operationId": "ListArchivedWorkflowExecutions", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/batch-operations": { + "get": { + "summary": "ListBatchOperations returns a list of batch operations", + "operationId": "ListBatchOperations", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListBatchOperationsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "List page size", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Next page token", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/batch-operations/{jobId}": { + "get": { + "summary": "DescribeBatchOperation returns the information about a batch operation", + "operationId": "DescribeBatchOperation", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Batch job id", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "StartBatchOperation starts a new batch operation", + "operationId": "StartBatchOperation", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StartBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "post": { + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StopBatchOperationResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "Namespace that contains the batch operation", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "jobId", + "description": "Batch job id", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" } } ], @@ -3131,15 +3626,15 @@ ] } }, - "/namespaces/{namespace}/activities/update-options-by-id": { + "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { - "summary": "UpdateActivityOptionsById is called by the client to update the options of an activity", - "operationId": "UpdateActivityOptionsById", + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "SetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsByIdResponse" + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" } }, "default": { @@ -3152,7 +3647,13 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" @@ -3162,7 +3663,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsByIdBody" + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" } } ], @@ -3171,15 +3672,15 @@ ] } }, - "/namespaces/{namespace}/archived-workflows": { + "/namespaces/{namespace}/current-deployment/{seriesName}": { "get": { - "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", - "operationId": "ListArchivedWorkflowExecutions", + "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "GetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" } }, "default": { @@ -3197,23 +3698,9 @@ "type": "string" }, { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" - }, - { - "name": "nextPageToken", - "in": "query", - "required": false, - "type": "string", - "format": "byte" - }, - { - "name": "query", - "in": "query", - "required": false, + "name": "seriesName", + "in": "path", + "required": true, "type": "string" } ], @@ -3222,15 +3709,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations": { + "/namespaces/{namespace}/deployments": { "get": { - "summary": "ListBatchOperations returns a list of batch operations", - "operationId": "ListBatchOperations", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "ListDeployments", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" + "$ref": "#/definitions/v1ListDeploymentsResponse" } }, "default": { @@ -3243,14 +3730,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { "name": "pageSize", - "description": "List page size", "in": "query", "required": false, "type": "integer", @@ -3258,11 +3743,17 @@ }, { "name": "nextPageToken", - "description": "Next page token", "in": "query", "required": false, "type": "string", "format": "byte" + }, + { + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -3270,15 +3761,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation", + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "DescribeDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1DescribeDeploymentResponse" } }, "default": { @@ -3291,62 +3782,23 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "jobId", - "description": "Batch job id", "in": "path", "required": true, "type": "string" - } - ], - "tags": [ - "WorkflowService" - ] - }, - "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation", - "responses": { - "200": { - "description": "A successful response.", - "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" - } }, - "default": { - "description": "An unexpected error response.", - "schema": { - "$ref": "#/definitions/rpcStatus" - } - } - }, - "parameters": [ { - "name": "namespace", - "description": "Namespace that contains the batch operation", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", "in": "path", "required": true, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } } ], "tags": [ @@ -3354,15 +3806,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { + "get": { + "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.", + "operationId": "GetDeploymentReachability", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" } }, "default": { @@ -3375,25 +3827,23 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" - } + "type": "string" } ], "tags": [ @@ -4868,6 +5318,22 @@ } } }, + "DeploymentInfoTaskQueueInfo": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/v1TaskQueueType" + }, + "firstPollerTime": { + "type": "string", + "format": "date-time", + "description": "When server saw the first poller for this task queue in this deployment." + } + } + }, "EndpointTargetExternal": { "type": "object", "properties": { @@ -5086,7 +5552,7 @@ "type": "object", "properties": { "deployment": { - "$ref": "#/definitions/v1WorkerDeployment", + "$ref": "#/definitions/v1Deployment", "description": "The target deployment of the redirect. Null means a so-far-versioned workflow is\nbeing redirected to unversioned workers." }, "behaviorOverride": { @@ -5112,23 +5578,19 @@ "properties": { "behavior": { "$ref": "#/definitions/v1VersioningBehavior", - "description": "Determines how server should treat this execution when workers are upgraded.\nWhen present it means that this workflow is versioned. This is not set until an execution\ncompletes its first workflow task on a versioned worker." + "description": "Determines how server should treat this execution when workers are upgraded.\nWhen present it means that this workflow is versioned. This is set after an execution\ncompletes its first workflow task on a versioned worker." }, "deployment": { - "$ref": "#/definitions/v1WorkerDeployment", + "$ref": "#/definitions/v1Deployment", "description": "The worker deployment to which this workflow is assigned currently.\nMust be present if and only if `behavior` is set." }, - "behaviorOverride": { - "$ref": "#/definitions/v1VersioningBehavior", - "description": "Manual override for execution's versioning behavior. Takes precedence over `behavior`." - }, - "deploymentOverride": { - "$ref": "#/definitions/v1WorkerDeployment", - "description": "Used to manually pin the execution to a deployment. Must be set when if and only if\n`behavior_override` is PINNED. Takes precedence over `deployment`." + "versioningOverride": { + "$ref": "#/definitions/v1VersioningOverride", + "description": "Present if user has set an execution-specific versioning override. This override takes\nprecedence over SDK-sent `behavior` and `deployment`." }, "redirectInfo": { "$ref": "#/definitions/VersioningInfoRedirectInfo", - "description": "When present, indicates the workflow is being redirected to a different deployment.\nA deployment redirect can only exist during the life time of a pending workflow task.\nIf the pending workflow task completes (at the next WorkflowTaskCompleted event), the\nredirect is considered complete and the workflow's deployment is updated. If the pending\nworkflow task fails or times out, then the redirect is canceled and workflow remains on\nthe previous deployment." + "description": "When present, indicates the workflow is being redirected to a different deployment.\nA redirect can only exist during the lifetime of a pending workflow task.\nIf the pending workflow task completes (at the next WorkflowTaskCompleted event), the\nredirect is considered complete and the workflow's deployment is updated. If the pending\nworkflow task fails or times out, then the redirect is canceled and workflow remains on\nthe previous deployment." } } }, @@ -5488,6 +5950,29 @@ } } }, + "WorkflowServiceSetCurrentDeploymentBody": { + "type": "object", + "properties": { + "deployment": { + "type": "object", + "properties": { + "buildId": { + "type": "string", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges." + } + }, + "description": "`Deployment` identifies a deployment of Temporal workers. The combination of deployment series\nname + build ID serves as the identifier. User can use `WorkerDeploymentOptions` in their worker\nprograms to specify these values." + }, + "identity": { + "type": "string", + "description": "Optional. The identity of the client who initiated this request." + }, + "updateMetadata": { + "$ref": "#/definitions/v1UpdateDeploymentMetadata", + "description": "Optional. Use to add or remove user-defined metadata entries. Metadata entries are exposed\nwhen describing a deployment. It is a good place for information such as operator name,\nlinks to internal deployment pipelines, etc." + } + } + }, "WorkflowServiceSignalWithStartWorkflowExecutionBody": { "type": "object", "properties": { @@ -7233,7 +7718,7 @@ "type": "object", "properties": { "deployment": { - "$ref": "#/definitions/v1WorkerDeployment", + "$ref": "#/definitions/v1Deployment", "description": "The target deployment of the redirect. Null means a previously versioned workflow just\ncompleted a redirect to unversioned workers." }, "versioningBehavior": { @@ -7390,6 +7875,79 @@ "v1DeleteWorkflowExecutionResponse": { "type": "object" }, + "v1Deployment": { + "type": "object", + "properties": { + "seriesName": { + "type": "string", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior." + }, + "buildId": { + "type": "string", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges." + } + }, + "description": "`Deployment` identifies a deployment of Temporal workers. The combination of deployment series\nname + build ID serves as the identifier. User can use `WorkerDeploymentOptions` in their worker\nprograms to specify these values." + }, + "v1DeploymentInfo": { + "type": "object", + "properties": { + "deployment": { + "$ref": "#/definitions/v1Deployment" + }, + "createTime": { + "type": "string", + "format": "date-time" + }, + "taskQueueInfos": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/DeploymentInfoTaskQueueInfo" + } + }, + "metadata": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/v1Payload" + }, + "description": "A user-defined set of key-values. Can be updated as part of write operations to the\ndeployment, such as `SetCurrentDeployment`." + }, + "isCurrent": { + "type": "boolean", + "description": "If this deployment is the current deployment of its deployment series." + } + }, + "description": "`DeploymentInfo` holds information about a deployment. Deployment information is tracked\nautomatically by server as soon as the first poll from that deployment reaches the server. There\ncan be multiple task queue workers in a single deployment which are listed in this message." + }, + "v1DeploymentListInfo": { + "type": "object", + "properties": { + "deployment": { + "$ref": "#/definitions/v1Deployment" + }, + "createTime": { + "type": "string", + "format": "date-time" + }, + "isCurrent": { + "type": "boolean", + "description": "If this deployment is the current deployment of its deployment series." + } + }, + "description": "DeploymentListInfo is an abbreviates set of fields from DeploymentInfo that's returned in\nListDeployments." + }, + "v1DeploymentReachability": { + "type": "string", + "enum": [ + "DEPLOYMENT_REACHABILITY_UNSPECIFIED", + "DEPLOYMENT_REACHABILITY_REACHABLE", + "DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY", + "DEPLOYMENT_REACHABILITY_UNREACHABLE" + ], + "default": "DEPLOYMENT_REACHABILITY_UNSPECIFIED", + "description": "Specify the reachability level for a deployment so users can decide if it is time to\ndecommission the deployment.\n\n - DEPLOYMENT_REACHABILITY_UNSPECIFIED: Reachability level is not specified.\n - DEPLOYMENT_REACHABILITY_REACHABLE: The deployment is reachable by new and/or open workflows. The deployment cannot be\ndecommissioned safely.\n - DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY: The deployment is not reachable by new or open workflows, but might be still needed by\nQueries sent to closed workflows. The deployment can be decommissioned safely if user does\nnot query closed workflows.\n - DEPLOYMENT_REACHABILITY_UNREACHABLE: The deployment is not reachable by any workflow because all the workflows who needed this\ndeployment went out of retention period. The deployment can be decommissioned safely." + }, "v1DeprecateNamespaceResponse": { "type": "object", "description": "Deprecated." @@ -7444,6 +8002,14 @@ } } }, + "v1DescribeDeploymentResponse": { + "type": "object", + "properties": { + "deploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo" + } + } + }, "v1DescribeNamespaceResponse": { "type": "object", "properties": { @@ -7787,7 +8353,7 @@ "type": "object", "properties": { "deployment": { - "$ref": "#/definitions/v1WorkerDeployment", + "$ref": "#/definitions/v1Deployment", "description": "The target deployment of the failed redirect attempt. Null means a versioned workflow\ntried to redirect to unversioned workers." } } @@ -7842,6 +8408,30 @@ }, "description": "GetClusterInfoResponse contains information about Temporal cluster." }, + "v1GetCurrentDeploymentResponse": { + "type": "object", + "properties": { + "currentDeploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo" + } + } + }, + "v1GetDeploymentReachabilityResponse": { + "type": "object", + "properties": { + "deploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo" + }, + "reachability": { + "$ref": "#/definitions/v1DeploymentReachability" + }, + "lastUpdateTime": { + "type": "string", + "format": "date-time", + "description": "Reachability level might come from server cache. This timestamp specifies when the value\nwas actually calculated." + } + } + }, "v1GetNexusEndpointResponse": { "type": "object", "properties": { @@ -8375,6 +8965,22 @@ } } }, + "v1ListDeploymentsResponse": { + "type": "object", + "properties": { + "nextPageToken": { + "type": "string", + "format": "byte" + }, + "deployments": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1DeploymentListInfo" + } + } + } + }, "v1ListNamespacesResponse": { "type": "object", "properties": { @@ -9134,7 +9740,7 @@ "description": "Next time when activity will be scheduled.\nIf activity is currently scheduled or started it will be null." }, "lastStartedDeployment": { - "$ref": "#/definitions/v1WorkerDeployment", + "$ref": "#/definitions/v1Deployment", "description": "The deployment this activity was dispatched to most recently. Present only if the activity\nwas dispatched to a versioned worker." } } @@ -10492,6 +11098,18 @@ } } }, + "v1SetCurrentDeploymentResponse": { + "type": "object", + "properties": { + "currentDeploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo" + }, + "previousDeploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo", + "description": "Info of the deployment that was current before executing this operation." + } + } + }, "v1Severity": { "type": "string", "enum": [ @@ -11456,6 +12074,25 @@ "default": "UPDATE_ADMITTED_EVENT_ORIGIN_UNSPECIFIED", "description": "Records why a WorkflowExecutionUpdateAdmittedEvent was written to history.\nNote that not all admitted Updates result in this event.\n\n - UPDATE_ADMITTED_EVENT_ORIGIN_REAPPLY: The UpdateAdmitted event was created when reapplying events during reset\nor replication. I.e. an accepted Update on one branch of Workflow history\nwas converted into an admitted Update on a different branch." }, + "v1UpdateDeploymentMetadata": { + "type": "object", + "properties": { + "upsertEntries": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/v1Payload" + } + }, + "removeEntries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of keys to remove from the metadata." + } + }, + "description": "Used as part of Deployment write APIs to update metadata attached to a deployment." + }, "v1UpdateNamespaceInfo": { "type": "object", "properties": { @@ -11681,21 +12318,21 @@ "VERSIONING_BEHAVIOR_AUTO_UPGRADE" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "description": " - VERSIONING_BEHAVIOR_PINNED: Workflow should be pinned to the current build ID until manually moved.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow automatically moves to the latest version (default build ID of the task queue) when the next\ntask is dispatched." + "description": " - VERSIONING_BEHAVIOR_UNSPECIFIED: Workflow is unversioned. This is the legacy behavior. An unversioned workflow's task may go\nto any worker who is polling for the task queue.\n - VERSIONING_BEHAVIOR_PINNED: Workflow should be pinned to the current deployment until completion. Can still be moved\nexplicitly via `UpdateWorkflowExecutionOptions` API.\nActivities of `PINNED` workflows are sent to the same deployment. Exception to this would be\nwhen the activity task queue workers are not present in the workflows deployment, in which\ncase, the activity will be sent to the current deployment of its own task queue.\n - VERSIONING_BEHAVIOR_AUTO_UPGRADE: Workflow automatically moves to the current deployment of its task queue when the next\nworkflow task is dispatched.\nActivities of `AUTO_UPGRADE` workflows are sent to the current deployment of the workflow\nexecution based on the last completed workflow task. Exception to this would be when the\nactivity task queue workers are not present in the workflows deployment, in which case, the\nactivity will be sent to the current deployment of its own task queue.\nWorkflows stuck on a backlogged activity will still auto-upgrade if the default deployment\nof their task queue changes, without having to wait for the backlogged activity to complete\non the old deployment." }, - "v1VersioningBehaviorOverride": { + "v1VersioningOverride": { "type": "object", "properties": { "behavior": { "$ref": "#/definitions/v1VersioningBehavior", "description": "Required." }, - "workerDeployment": { - "$ref": "#/definitions/v1WorkerDeployment", - "description": "Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`.\nIdentifies the Build ID and Deployment Name to pin the workflow to." + "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." } }, - "description": "Used in both UpdateWorkflowExecutionOptions and StartWorkflowExecution to override\nthe versioning behavior of a specific workflow execution. If set, takes precedence\nover the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on.\nTo remove the override, call UpdateWorkflowExecutionOptions with a null VersioningBehaviorOverride,\nand use the FieldMask to indicate that it should be mutated." + "description": "Used to override the versioning behavior and deployment of a specific workflow execution. If set,\ntakes precedence over the worker-sent values. See `WorkflowExecutionInfo.VersioningInfo` for more\ninformation. To remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningOverride`, and use the `update_mask` to indicate that it should be mutated." }, "v1WaitPolicy": { "type": "object", @@ -11707,18 +12344,6 @@ }, "description": "Specifies client's intent to wait for Update results." }, - "v1WorkerDeployment": { - "type": "object", - "properties": { - "deploymentName": { - "type": "string" - }, - "buildId": { - "type": "string" - } - }, - "description": "Identifies a versioned worker deployment." - }, "v1WorkerVersionCapabilities": { "type": "object", "properties": { @@ -11730,9 +12355,9 @@ "type": "boolean", "description": "If set, the worker is opting in to worker versioning, and wishes to only receive appropriate\ntasks." }, - "deploymentName": { + "deploymentSeriesName": { "type": "string", - "description": "Must be sent if user has set a deployment name (versioning-3)." + "description": "Must be sent if user has set a deployment series name (versioning-3)." } }, "description": "Identifies the version that a worker is compatible with when polling or identifying itself,\nand whether or not this worker is opting into the build-id based versioning feature. This is\nused by matching to determine which workers ought to receive what tasks." @@ -11748,9 +12373,9 @@ "type": "boolean", "description": "If set, the worker is opting in to worker versioning. Otherwise, this is used only as a\nmarker for workflow reset points and the BuildIDs search attribute." }, - "deploymentName": { + "deploymentSeriesName": { "type": "string", - "description": "Must be sent if user has set a deployment name (versioning-3)." + "description": "Must be sent if user has set a deployment series name (versioning-3)." } }, "title": "Identifies the version of a worker that received or processed a task" @@ -12018,9 +12643,9 @@ "v1WorkflowExecutionOptions": { "type": "object", "properties": { - "versioningBehaviorOverride": { - "$ref": "#/definitions/v1VersioningBehaviorOverride", - "description": "If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on." + "versioningOverride": { + "$ref": "#/definitions/v1VersioningOverride", + "description": "If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow\nExecution it is set on." } } }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index d70fc752d..dd6233866 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -635,6 +635,233 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/current-deployment/{deployment.series_name}: + post: + tags: + - WorkflowService + description: |- + Sets a deployment as the current deployment for its deployment series. Can optionally update + the metadata of the deployment as well. + Experimental. This API might significantly change or be removed in a future release. + operationId: SetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetCurrentDeploymentRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SetCurrentDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/current-deployment/{seriesName}: + get: + tags: + - WorkflowService + description: |- + Returns the current deployment (and its info) for a given deployment series. + Experimental. This API might significantly change or be removed in a future release. + operationId: GetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: seriesName + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetCurrentDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/deployments: + get: + tags: + - WorkflowService + description: |- + Lists worker deployments in the namespace. Optionally can filter based on deployment series + name. + Experimental. This API might significantly change or be removed in a future release. + operationId: ListDeployments + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + schema: + type: string + format: bytes + - name: seriesName + in: query + description: Optional. Use to filter based on exact series name match. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListDeploymentsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}: + get: + tags: + - WorkflowService + description: |- + Describes a worker deployment. + Experimental. This API might significantly change or be removed in a future release. + operationId: DescribeDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.seriesName + in: query + description: |- + Different versions of the same worker service/application are related together by having a + shared series name. + Out of all deployments of a series, one can be designated as the current deployment, which + receives new workflow executions and new tasks of workflows with + `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + schema: + type: string + - name: deployment.buildId + in: query + description: |- + Build ID changes with each version of the worker when the worker program code and/or config + changes. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability: + get: + tags: + - WorkflowService + description: |- + Returns the reachability level of a worker deployment to help users decide when it is time + to decommission a deployment. Reachability level is calculated based on the deployment's + `status` and existing workflows that depend on the given deployment for their execution. + Calculating reachability is relatively expensive. Therefore, server might return a recently + cached value. In such a case, the `last_update_time` will inform you about the actual + reachability calculation time. + Experimental. This API might significantly change or be removed in a future release. + operationId: GetDeploymentReachability + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.seriesName + in: query + description: |- + Different versions of the same worker service/application are related together by having a + shared series name. + Out of all deployments of a series, one can be designated as the current deployment, which + receives new workflow executions and new tasks of workflows with + `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + schema: + type: string + - name: deployment.buildId + in: query + description: |- + Build ID changes with each version of the worker when the worker program code and/or config + changes. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetDeploymentReachabilityResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/schedules: get: tags: @@ -2934,6 +3161,233 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/current-deployment/{deployment.series_name}: + post: + tags: + - WorkflowService + description: |- + Sets a deployment as the current deployment for its deployment series. Can optionally update + the metadata of the deployment as well. + Experimental. This API might significantly change or be removed in a future release. + operationId: SetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetCurrentDeploymentRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SetCurrentDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/current-deployment/{seriesName}: + get: + tags: + - WorkflowService + description: |- + Returns the current deployment (and its info) for a given deployment series. + Experimental. This API might significantly change or be removed in a future release. + operationId: GetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: seriesName + in: path + required: true + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetCurrentDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/deployments: + get: + tags: + - WorkflowService + description: |- + Lists worker deployments in the namespace. Optionally can filter based on deployment series + name. + Experimental. This API might significantly change or be removed in a future release. + operationId: ListDeployments + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + schema: + type: string + format: bytes + - name: seriesName + in: query + description: Optional. Use to filter based on exact series name match. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListDeploymentsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}: + get: + tags: + - WorkflowService + description: |- + Describes a worker deployment. + Experimental. This API might significantly change or be removed in a future release. + operationId: DescribeDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.seriesName + in: query + description: |- + Different versions of the same worker service/application are related together by having a + shared series name. + Out of all deployments of a series, one can be designated as the current deployment, which + receives new workflow executions and new tasks of workflows with + `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + schema: + type: string + - name: deployment.buildId + in: query + description: |- + Build ID changes with each version of the worker when the worker program code and/or config + changes. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeDeploymentResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability: + get: + tags: + - WorkflowService + description: |- + Returns the reachability level of a worker deployment to help users decide when it is time + to decommission a deployment. Reachability level is calculated based on the deployment's + `status` and existing workflows that depend on the given deployment for their execution. + Calculating reachability is relatively expensive. Therefore, server might return a recently + cached value. In such a case, the `last_update_time` will inform you about the actual + reachability calculation time. + Experimental. This API might significantly change or be removed in a future release. + operationId: GetDeploymentReachability + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.series_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.seriesName + in: query + description: |- + Different versions of the same worker service/application are related together by having a + shared series name. + Out of all deployments of a series, one can be designated as the current deployment, which + receives new workflow executions and new tasks of workflows with + `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + schema: + type: string + - name: deployment.buildId + in: query + description: |- + Build ID changes with each version of the worker when the worker program code and/or config + changes. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetDeploymentReachabilityResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/schedules: get: tags: @@ -5094,7 +5548,7 @@ components: properties: deployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- The target deployment of the redirect. Null means a previously versioned workflow just completed a redirect to unversioned workers. @@ -5217,6 +5671,83 @@ components: DeleteScheduleResponse: type: object properties: {} + Deployment: + type: object + properties: + seriesName: + type: string + description: |- + Different versions of the same worker service/application are related together by having a + shared series name. + Out of all deployments of a series, one can be designated as the current deployment, which + receives new workflow executions and new tasks of workflows with + `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + buildId: + type: string + description: |- + Build ID changes with each version of the worker when the worker program code and/or config + changes. + description: |- + `Deployment` identifies a deployment of Temporal workers. The combination of deployment series + name + build ID serves as the identifier. User can use `WorkerDeploymentOptions` in their worker + programs to specify these values. + DeploymentInfo: + type: object + properties: + deployment: + $ref: '#/components/schemas/Deployment' + createTime: + type: string + format: date-time + taskQueueInfos: + type: array + items: + $ref: '#/components/schemas/DeploymentInfo_TaskQueueInfo' + metadata: + type: object + additionalProperties: + $ref: '#/components/schemas/Payload' + description: |- + A user-defined set of key-values. Can be updated as part of write operations to the + deployment, such as `SetCurrentDeployment`. + isCurrent: + type: boolean + description: If this deployment is the current deployment of its deployment series. + description: |- + `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. + DeploymentInfo_TaskQueueInfo: + type: object + properties: + name: + type: string + type: + enum: + - TASK_QUEUE_TYPE_UNSPECIFIED + - TASK_QUEUE_TYPE_WORKFLOW + - TASK_QUEUE_TYPE_ACTIVITY + - TASK_QUEUE_TYPE_NEXUS + type: string + format: enum + firstPollerTime: + type: string + description: When server saw the first poller for this task queue in this deployment. + format: date-time + DeploymentListInfo: + type: object + properties: + deployment: + $ref: '#/components/schemas/Deployment' + createTime: + type: string + format: date-time + isCurrent: + type: boolean + description: If this deployment is the current deployment of its deployment series. + description: |- + DeploymentListInfo is an abbreviates set of fields from DeploymentInfo that's returned in + ListDeployments. DescribeBatchOperationResponse: type: object properties: @@ -5266,6 +5797,11 @@ components: reason: type: string description: Reason indicates the reason to stop a operation + DescribeDeploymentResponse: + type: object + properties: + deploymentInfo: + $ref: '#/components/schemas/DeploymentInfo' DescribeNamespaceResponse: type: object properties: @@ -5536,7 +6072,7 @@ components: properties: deployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- The target deployment of the failed redirect attempt. Null means a versioned workflow tried to redirect to unversioned workers. @@ -5626,6 +6162,30 @@ components: visibilityStore: type: string description: GetClusterInfoResponse contains information about Temporal cluster. + GetCurrentDeploymentResponse: + type: object + properties: + currentDeploymentInfo: + $ref: '#/components/schemas/DeploymentInfo' + GetDeploymentReachabilityResponse: + type: object + properties: + deploymentInfo: + $ref: '#/components/schemas/DeploymentInfo' + reachability: + enum: + - DEPLOYMENT_REACHABILITY_UNSPECIFIED + - DEPLOYMENT_REACHABILITY_REACHABLE + - DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY + - DEPLOYMENT_REACHABILITY_UNREACHABLE + type: string + format: enum + lastUpdateTime: + type: string + description: |- + Reachability level might come from server cache. This timestamp specifies when the value + was actually calculated. + format: date-time GetNexusEndpointResponse: type: object properties: @@ -6092,6 +6652,16 @@ components: nextPageToken: type: string format: bytes + ListDeploymentsResponse: + type: object + properties: + nextPageToken: + type: string + format: bytes + deployments: + type: array + items: + $ref: '#/components/schemas/DeploymentListInfo' ListNamespacesResponse: type: object properties: @@ -6714,7 +7284,7 @@ components: format: date-time lastStartedDeployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- The deployment this activity was dispatched to most recently. Present only if the activity was dispatched to a versioned worker. @@ -7894,6 +8464,32 @@ components: properties: nonRetryable: type: boolean + SetCurrentDeploymentRequest: + type: object + properties: + namespace: + type: string + deployment: + $ref: '#/components/schemas/Deployment' + identity: + type: string + description: Optional. The identity of the client who initiated this request. + updateMetadata: + allOf: + - $ref: '#/components/schemas/UpdateDeploymentMetadata' + description: |- + Optional. Use to add or remove user-defined metadata entries. Metadata entries are exposed + when describing a deployment. It is a good place for information such as operator name, + links to internal deployment pipelines, etc. + SetCurrentDeploymentResponse: + type: object + properties: + currentDeploymentInfo: + $ref: '#/components/schemas/DeploymentInfo' + previousDeploymentInfo: + allOf: + - $ref: '#/components/schemas/DeploymentInfo' + description: Info of the deployment that was current before executing this operation. SignalExternalWorkflowExecutionFailedEventAttributes: type: object properties: @@ -8800,6 +9396,19 @@ components: allOf: - $ref: '#/components/schemas/ActivityOptions' description: Activity options after an update + UpdateDeploymentMetadata: + type: object + properties: + upsertEntries: + type: object + additionalProperties: + $ref: '#/components/schemas/Payload' + removeEntries: + type: array + items: + type: string + description: List of keys to remove from the metadata. + description: Used as part of Deployment write APIs to update metadata attached to a deployment. UpdateNamespaceInfo: type: object properties: @@ -9071,35 +9680,12 @@ components: type: string format: date-time description: VersionInfo contains details about current and recommended release versions as well as alerts and upgrade instructions. - VersioningBehaviorOverride: - type: object - properties: - behavior: - enum: - - VERSIONING_BEHAVIOR_UNSPECIFIED - - VERSIONING_BEHAVIOR_PINNED - - VERSIONING_BEHAVIOR_AUTO_UPGRADE - type: string - description: Required. - format: enum - workerDeployment: - allOf: - - $ref: '#/components/schemas/WorkerDeployment' - description: |- - Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. - Identifies the Build ID and Deployment Name to pin the workflow to. - description: |- - Used in both UpdateWorkflowExecutionOptions and StartWorkflowExecution to override - the versioning behavior of a specific workflow execution. If set, takes precedence - over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on. - To remove the override, call UpdateWorkflowExecutionOptions with a null VersioningBehaviorOverride, - and use the FieldMask to indicate that it should be mutated. VersioningInfo_RedirectInfo: type: object properties: deployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- The target deployment of the redirect. Null means a so-far-versioned workflow is being redirected to unversioned workers. @@ -9114,6 +9700,28 @@ components: override. Such override is only applied to the workflow when and if the redirect successfully completes. format: enum + VersioningOverride: + type: object + properties: + behavior: + enum: + - VERSIONING_BEHAVIOR_UNSPECIFIED + - VERSIONING_BEHAVIOR_PINNED + - VERSIONING_BEHAVIOR_AUTO_UPGRADE + type: string + description: Required. + format: enum + deployment: + allOf: + - $ref: '#/components/schemas/Deployment' + description: |- + Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. + Identifies the worker deployment to pin the workflow to. + description: |- + Used to override the versioning behavior and deployment 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. WaitPolicy: type: object properties: @@ -9132,14 +9740,6 @@ components: user specified timeout, API call returns even if specified stage is not reached. format: enum description: Specifies client's intent to wait for Update results. - WorkerDeployment: - type: object - properties: - deploymentName: - type: string - buildId: - type: string - description: Identifies a versioned worker deployment. WorkerVersionCapabilities: type: object properties: @@ -9151,9 +9751,9 @@ components: description: |- If set, the worker is opting in to worker versioning, and wishes to only receive appropriate tasks. - deploymentName: + deploymentSeriesName: type: string - description: Must be sent if user has set a deployment name (versioning-3). + description: Must be sent if user has set a deployment series name (versioning-3). description: |- Identifies the version that a worker is compatible with when polling or identifying itself, and whether or not this worker is opting into the build-id based versioning feature. This is @@ -9171,9 +9771,9 @@ components: description: |- If set, the worker is opting in to worker versioning. Otherwise, this is used only as a marker for workflow reset points and the BuildIDs search attribute. - deploymentName: + deploymentSeriesName: type: string - description: Must be sent if user has set a deployment name (versioning-3). + description: Must be sent if user has set a deployment series name (versioning-3). description: Identifies the version of a worker that received or processed a task WorkflowEvent_EventReference: type: object @@ -9507,35 +10107,27 @@ components: type: string description: |- Determines how server should treat this execution when workers are upgraded. - When present it means that this workflow is versioned. This is not set until an execution + When present it means that this workflow is versioned. This is set after an execution completes its first workflow task on a versioned worker. format: enum deployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- The worker deployment to which this workflow is assigned currently. Must be present if and only if `behavior` is set. - behaviorOverride: - enum: - - VERSIONING_BEHAVIOR_UNSPECIFIED - - VERSIONING_BEHAVIOR_PINNED - - VERSIONING_BEHAVIOR_AUTO_UPGRADE - type: string - description: Manual override for execution's versioning behavior. Takes precedence over `behavior`. - format: enum - deploymentOverride: + versioningOverride: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/VersioningOverride' description: |- - Used to manually pin the execution to a deployment. Must be set when if and only if - `behavior_override` is PINNED. Takes precedence over `deployment`. + Present if user has set an execution-specific versioning override. This override takes + precedence over SDK-sent `behavior` and `deployment`. redirectInfo: allOf: - $ref: '#/components/schemas/VersioningInfo_RedirectInfo' description: |- When present, indicates the workflow is being redirected to a different deployment. - A deployment redirect can only exist during the life time of a pending workflow task. + A redirect can only exist during the lifetime of a pending workflow task. If the pending workflow task completes (at the next WorkflowTaskCompleted event), the redirect is considered complete and the workflow's deployment is updated. If the pending workflow task fails or times out, then the redirect is canceled and workflow remains on @@ -9543,10 +10135,12 @@ components: WorkflowExecutionOptions: type: object properties: - versioningBehaviorOverride: + versioningOverride: allOf: - - $ref: '#/components/schemas/VersioningBehaviorOverride' - description: If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on. + - $ref: '#/components/schemas/VersioningOverride' + description: |- + If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow + Execution it is set on. WorkflowExecutionOptionsUpdatedEventAttributes: type: object properties: diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 888b8eae6..c3c61d1f4 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -37,7 +37,6 @@ import "google/protobuf/empty.proto"; import "temporal/api/enums/v1/common.proto"; import "temporal/api/enums/v1/event_type.proto"; import "temporal/api/enums/v1/reset.proto"; -import "temporal/api/enums/v1/workflow.proto"; message DataBlob { temporal.api.enums.v1.EncodingType encoding_type = 1; @@ -134,8 +133,8 @@ message WorkerVersionStamp { // marker for workflow reset points and the BuildIDs search attribute. bool use_versioning = 3; - // Must be sent if user has set a deployment name (versioning-3). - string deployment_name = 4; + // Must be sent if user has set a deployment series name (versioning-3). + string deployment_series_name = 4; // Later, may include bundle id that could be used for WASM and/or JS dynamically loadable bundles. } @@ -151,32 +150,12 @@ message WorkerVersionCapabilities { // tasks. bool use_versioning = 2; - // Must be sent if user has set a deployment name (versioning-3). - string deployment_name = 3; + // Must be sent if user has set a deployment series name (versioning-3). + string deployment_series_name = 4; // Later, may include info like "I can process WASM and/or JS bundles" } -// Used in both UpdateWorkflowExecutionOptions and StartWorkflowExecution to override -// the versioning behavior of a specific workflow execution. If set, takes precedence -// over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on. -// To remove the override, call UpdateWorkflowExecutionOptions with a null VersioningBehaviorOverride, -// and use the FieldMask to indicate that it should be mutated. -message VersioningBehaviorOverride { - // Required. - temporal.api.enums.v1.VersioningBehavior behavior = 1; - - // Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. - // Identifies the Build ID and Deployment Name to pin the workflow to. - WorkerDeployment worker_deployment = 2; -} - -// Identifies a versioned worker deployment. -message WorkerDeployment { - string deployment_name = 1; - string build_id = 2; -} - // Describes where and how to reset a workflow, used for batch reset currently // and may be used for single-workflow reset later. message ResetOptions { diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto new file mode 100644 index 000000000..4d6ce823f --- /dev/null +++ b/temporal/api/deployment/v1/message.proto @@ -0,0 +1,89 @@ +// The MIT License +// +// Copyright (c) 2020 Temporal Technologies Inc. All rights reserved. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +// THE SOFTWARE. + +syntax = "proto3"; + +package temporal.api.deployment.v1; + +option go_package = "go.temporal.io/api/deployment/v1;deployment"; +option java_package = "io.temporal.api.deployment.v1"; +option java_multiple_files = true; +option java_outer_classname = "MessageProto"; +option ruby_package = "Temporalio::Api::Deployment::V1"; +option csharp_namespace = "Temporalio.Api.Deployment.V1"; + +import "google/protobuf/timestamp.proto"; + +import "temporal/api/enums/v1/task_queue.proto"; +import "temporal/api/common/v1/message.proto"; + +// `Deployment` identifies a deployment of Temporal workers. The combination of deployment series +// name + build ID serves as the identifier. User can use `WorkerDeploymentOptions` in their worker +// programs to specify these values. +message Deployment { + // Different versions of the same worker service/application are related together by having a + // shared series name. + // Out of all deployments of a series, one can be designated as the current deployment, which + // receives new workflow executions and new tasks of workflows with + // `VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior. + string series_name = 1; + // Build ID changes with each version of the worker when the worker program code and/or config + // changes. + 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. +message DeploymentInfo { + Deployment deployment = 1; + google.protobuf.Timestamp create_time = 2; + repeated TaskQueueInfo task_queue_infos = 3; + // A user-defined set of key-values. Can be updated as part of write operations to the + // deployment, such as `SetCurrentDeployment`. + map metadata = 4; + // If this deployment is the current deployment of its deployment series. + bool is_current = 5; + + message TaskQueueInfo { + string name = 1; + temporal.api.enums.v1.TaskQueueType type = 2; + // When server saw the first poller for this task queue in this deployment. + google.protobuf.Timestamp first_poller_time = 3; + } +} + +// Used as part of Deployment write APIs to update metadata attached to a deployment. +message UpdateDeploymentMetadata { + map upsert_entries = 1; + // List of keys to remove from the metadata. + repeated string remove_entries = 2; +} + +// DeploymentListInfo is an abbreviates set of fields from DeploymentInfo that's returned in +// ListDeployments. +message DeploymentListInfo { + deployment.v1.Deployment deployment = 1; + google.protobuf.Timestamp create_time = 2; + // If this deployment is the current deployment of its deployment series. + bool is_current = 3; +} diff --git a/temporal/api/enums/v1/deployment.proto b/temporal/api/enums/v1/deployment.proto new file mode 100644 index 000000000..005ba4406 --- /dev/null +++ b/temporal/api/enums/v1/deployment.proto @@ -0,0 +1,49 @@ +// The MIT License +// +// Copyright (c) 2020 Temporal Technologies Inc. All rights reserved. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +// THE SOFTWARE. + +syntax = "proto3"; + +package temporal.api.enums.v1; + +option go_package = "go.temporal.io/api/enums/v1;enums"; +option java_package = "io.temporal.api.enums.v1"; +option java_multiple_files = true; +option java_outer_classname = "DeploymentProto"; +option ruby_package = "Temporalio::Api::Enums::V1"; +option csharp_namespace = "Temporalio.Api.Enums.V1"; + +// Specify the reachability level for a deployment so users can decide if it is time to +// decommission the deployment. +enum DeploymentReachability { + // Reachability level is not specified. + DEPLOYMENT_REACHABILITY_UNSPECIFIED = 0; + // The deployment is reachable by new and/or open workflows. The deployment cannot be + // decommissioned safely. + DEPLOYMENT_REACHABILITY_REACHABLE = 1; + // The deployment is not reachable by new or open workflows, but might be still needed by + // Queries sent to closed workflows. The deployment can be decommissioned safely if user does + // not query closed workflows. + DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY = 2; + // The deployment is not reachable by any workflow because all the workflows who needed this + // deployment went out of retention period. The deployment can be decommissioned safely. + DEPLOYMENT_REACHABILITY_UNREACHABLE = 3; +} diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 4d8ca8cb6..97cb47e3f 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -140,10 +140,23 @@ enum TimeoutType { } enum VersioningBehavior { + // Workflow is unversioned. This is the legacy behavior. An unversioned workflow's task may go + // to any worker who is polling for the task queue. VERSIONING_BEHAVIOR_UNSPECIFIED = 0; - // Workflow should be pinned to the current build ID until manually moved. + // Workflow should be pinned to the current deployment until completion. Can still be moved + // explicitly via `UpdateWorkflowExecutionOptions` API. + // Activities of `PINNED` workflows are sent to the same deployment. Exception to this would be + // when the activity task queue workers are not present in the workflows deployment, in which + // case, the activity will be sent to the current deployment of its own task queue. VERSIONING_BEHAVIOR_PINNED = 1; - // Workflow automatically moves to the latest version (default build ID of the task queue) when the next - // task is dispatched. + // Workflow automatically moves to the current deployment of its task queue when the next + // workflow task is dispatched. + // Activities of `AUTO_UPGRADE` workflows are sent to the current deployment of the workflow + // execution based on the last completed workflow task. Exception to this would be when the + // activity task queue workers are not present in the workflows deployment, in which case, the + // activity will be sent to the current deployment of its own task queue. + // Workflows stuck on a backlogged activity will still auto-upgrade if the default deployment + // of their task queue changes, without having to wait for the backlogged activity to complete + // on the old deployment. VERSIONING_BEHAVIOR_AUTO_UPGRADE = 2; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 594ff4ade..33073a87e 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -40,6 +40,7 @@ import "temporal/api/enums/v1/failed_cause.proto"; import "temporal/api/enums/v1/update.proto"; import "temporal/api/enums/v1/workflow.proto"; import "temporal/api/common/v1/message.proto"; +import "temporal/api/deployment/v1/message.proto"; import "temporal/api/failure/v1/message.proto"; import "temporal/api/taskqueue/v1/message.proto"; import "temporal/api/update/v1/message.proto"; @@ -255,7 +256,7 @@ message WorkflowTaskCompletedEventAttributes { message CompletedDeploymentRedirectInfo { // The target deployment of the redirect. Null means a previously versioned workflow just // completed a redirect to unversioned workers. - temporal.api.common.v1.WorkerDeployment deployment = 1; + temporal.api.deployment.v1.Deployment deployment = 1; // Versioning behavior sent by SDK for this workflow execution on the new deployment. // Must be present if and only if `deployment` is set. temporal.api.enums.v1.VersioningBehavior versioning_behavior = 2; @@ -268,7 +269,7 @@ message CompletedDeploymentRedirectInfo { message FailedDeploymentRedirectInfo { // The target deployment of the failed redirect attempt. Null means a versioned workflow // tried to redirect to unversioned workers. - temporal.api.common.v1.WorkerDeployment deployment = 1; + temporal.api.deployment.v1.Deployment deployment = 1; } message WorkflowTaskTimedOutEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 56838aa3a..4d142eae0 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -38,6 +38,7 @@ import "google/protobuf/timestamp.proto"; import "temporal/api/enums/v1/common.proto"; import "temporal/api/enums/v1/workflow.proto"; import "temporal/api/common/v1/message.proto"; +import "temporal/api/deployment/v1/message.proto"; import "temporal/api/failure/v1/message.proto"; import "temporal/api/taskqueue/v1/message.proto"; import "temporal/api/sdk/v1/user_metadata.proto"; @@ -107,29 +108,27 @@ message WorkflowExecutionInfo { message VersioningInfo { // Determines how server should treat this execution when workers are upgraded. - // When present it means that this workflow is versioned. This is not set until an execution + // When present it means that this workflow is versioned. This is set after an execution // completes its first workflow task on a versioned worker. temporal.api.enums.v1.VersioningBehavior behavior = 1; // The worker deployment to which this workflow is assigned currently. // Must be present if and only if `behavior` is set. - temporal.api.common.v1.WorkerDeployment deployment = 2; - // Manual override for execution's versioning behavior. Takes precedence over `behavior`. - temporal.api.enums.v1.VersioningBehavior behavior_override = 3; - // Used to manually pin the execution to a deployment. Must be set when if and only if - // `behavior_override` is PINNED. Takes precedence over `deployment`. - temporal.api.common.v1.WorkerDeployment deployment_override = 4; + temporal.api.deployment.v1.Deployment deployment = 2; + // Present if user has set an execution-specific versioning override. This override takes + // precedence over SDK-sent `behavior` and `deployment`. + VersioningOverride versioning_override = 3; // When present, indicates the workflow is being redirected to a different deployment. - // A deployment redirect can only exist during the life time of a pending workflow task. + // A redirect can only exist during the lifetime of a pending workflow task. // If the pending workflow task completes (at the next WorkflowTaskCompleted event), the // redirect is considered complete and the workflow's deployment is updated. If the pending // workflow task fails or times out, then the redirect is canceled and workflow remains on // the previous deployment. - RedirectInfo redirect_info = 5; + RedirectInfo redirect_info = 4; message RedirectInfo { // The target deployment of the redirect. Null means a so-far-versioned workflow is // being redirected to unversioned workers. - temporal.api.common.v1.WorkerDeployment deployment = 1; + temporal.api.deployment.v1.Deployment deployment = 1; // If present, it means the redirect is initiated by a (safe) manual versioning // override. Such override is only applied to the workflow when and if the redirect // successfully completes. @@ -192,7 +191,7 @@ message PendingActivityInfo { // The deployment this activity was dispatched to most recently. Present only if the activity // was dispatched to a versioned worker. - temporal.api.common.v1.WorkerDeployment last_started_deployment = 19; + temporal.api.deployment.v1.Deployment last_started_deployment = 19; } message PendingChildExecutionInfo { @@ -363,6 +362,20 @@ message NexusOperationCancellationInfo { } message WorkflowExecutionOptions { - // If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on. - temporal.api.common.v1.VersioningBehaviorOverride versioning_behavior_override = 1; -} \ No newline at end of file + // If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow + // Execution it is set on. + VersioningOverride versioning_override = 1; +} + +// Used to override the versioning behavior and deployment 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. +message VersioningOverride { + // Required. + 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. + temporal.api.deployment.v1.Deployment deployment = 2; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 7f3c4b344..51f3364bc 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -39,12 +39,14 @@ import "temporal/api/enums/v1/failed_cause.proto"; import "temporal/api/enums/v1/query.proto"; import "temporal/api/enums/v1/reset.proto"; import "temporal/api/enums/v1/task_queue.proto"; +import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/update.proto"; import "temporal/api/activity/v1/message.proto"; import "temporal/api/common/v1/message.proto"; import "temporal/api/history/v1/message.proto"; import "temporal/api/workflow/v1/message.proto"; import "temporal/api/command/v1/message.proto"; +import "temporal/api/deployment/v1/message.proto"; import "temporal/api/failure/v1/message.proto"; import "temporal/api/filter/v1/message.proto"; import "temporal/api/protocol/v1/message.proto"; @@ -358,7 +360,7 @@ message RespondWorkflowTaskCompletedRequest { reserved 14; reserved "capabilities"; // Must be set when versioning-3 is used (i.e. `worker_version_stamp.use_versioning` is `true` - // and `worker_version_stamp.deployment_name` is provided). + // and `worker_version_stamp.deployment_series_name` is provided). temporal.api.enums.v1.VersioningBehavior versioning_behavior = 15; } @@ -1737,3 +1739,65 @@ message UpdateWorkflowExecutionOptionsResponse { // Workflow Execution options after update. temporal.api.workflow.v1.WorkflowExecutionOptions workflow_execution_options = 1; } + +message DescribeDeploymentRequest { + string namespace = 1; + deployment.v1.Deployment deployment = 2; +} + +message DescribeDeploymentResponse { + deployment.v1.DeploymentInfo deployment_info = 1; +} + +message ListDeploymentsRequest { + string namespace = 1; + int32 page_size = 2; + bytes next_page_token = 3; + // Optional. Use to filter based on exact series name match. + string series_name = 4; +} + +message ListDeploymentsResponse { + bytes next_page_token = 1; + repeated temporal.api.deployment.v1.DeploymentListInfo deployments = 2; +} + +message SetCurrentDeploymentRequest { + string namespace = 1; + temporal.api.deployment.v1.Deployment deployment = 2; + // Optional. The identity of the client who initiated this request. + string identity = 3; + // Optional. Use to add or remove user-defined metadata entries. Metadata entries are exposed + // when describing a deployment. It is a good place for information such as operator name, + // links to internal deployment pipelines, etc. + temporal.api.deployment.v1.UpdateDeploymentMetadata update_metadata = 4; +} + +message SetCurrentDeploymentResponse { + temporal.api.deployment.v1.DeploymentInfo current_deployment_info = 1; + // Info of the deployment that was current before executing this operation. + temporal.api.deployment.v1.DeploymentInfo previous_deployment_info = 2; +} + +// Returns the Current Deployment of a deployment series. +message GetCurrentDeploymentRequest { + string namespace = 1; + string series_name = 2; +} + +message GetCurrentDeploymentResponse { + temporal.api.deployment.v1.DeploymentInfo current_deployment_info = 1; +} + +message GetDeploymentReachabilityRequest { + string namespace = 1; + temporal.api.deployment.v1.Deployment deployment = 2; +} + +message GetDeploymentReachabilityResponse { + temporal.api.deployment.v1.DeploymentInfo deployment_info = 1; + enums.v1.DeploymentReachability reachability = 2; + // Reachability level might come from server cache. This timestamp specifies when the value + // was actually calculated. + google.protobuf.Timestamp last_update_time = 3; +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 4a2f513fe..f3f2b315b 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -772,6 +772,70 @@ service WorkflowService { }; } + // Describes a worker deployment. + // Experimental. This API might significantly change or be removed in a future release. + rpc DescribeDeployment (DescribeDeploymentRequest) returns (DescribeDeploymentResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}" + } + }; + } + + // Lists worker deployments in the namespace. Optionally can filter based on deployment series + // name. + // Experimental. This API might significantly change or be removed in a future release. + rpc ListDeployments (ListDeploymentsRequest) returns (ListDeploymentsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/deployments" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/deployments" + } + }; + } + + // Returns the reachability level of a worker deployment to help users decide when it is time + // to decommission a deployment. Reachability level is calculated based on the deployment's + // `status` and existing workflows that depend on the given deployment for their execution. + // Calculating reachability is relatively expensive. Therefore, server might return a recently + // cached value. In such a case, the `last_update_time` will inform you about the actual + // reachability calculation time. + // Experimental. This API might significantly change or be removed in a future release. + rpc GetDeploymentReachability (GetDeploymentReachabilityRequest) returns (GetDeploymentReachabilityResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability" + } + }; + } + + // Returns the current deployment (and its info) for a given deployment series. + // Experimental. This API might significantly change or be removed in a future release. + rpc GetCurrentDeployment (GetCurrentDeploymentRequest) returns (GetCurrentDeploymentResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/current-deployment/{series_name}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/current-deployment/{series_name}" + } + }; + } + + // Sets a deployment as the current deployment for its deployment series. Can optionally update + // the metadata of the deployment as well. + // Experimental. This API might significantly change or be removed in a future release. + rpc SetCurrentDeployment (SetCurrentDeploymentRequest) returns (SetCurrentDeploymentResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/current-deployment/{deployment.series_name}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/current-deployment/{deployment.series_name}" + body: "*" + } + }; + } + // Invokes the specified Update function on user Workflow code. rpc UpdateWorkflowExecution(UpdateWorkflowExecutionRequest) returns (UpdateWorkflowExecutionResponse) { option (google.api.http) = {