From aad202a2ebc881d680f74997e108a57292337c27 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Sun, 17 Nov 2024 13:19:07 -0800 Subject: [PATCH 1/6] Add Deployment APIs --- openapi/openapiv2.json | 855 +++++++++++++++--- openapi/openapiv3.yaml | 567 +++++++++++- temporal/api/common/v1/message.proto | 21 - temporal/api/deployment/v1/message.proto | 63 ++ temporal/api/enums/v1/deployment.proto | 66 ++ temporal/api/history/v1/message.proto | 5 +- temporal/api/workflow/v1/message.proto | 33 +- .../workflowservice/v1/request_response.proto | 74 ++ temporal/api/workflowservice/v1/service.proto | 55 ++ 9 files changed, 1566 insertions(+), 173 deletions(-) create mode 100644 temporal/api/deployment/v1/message.proto create mode 100644 temporal/api/enums/v1/deployment.proto diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 3d46f56d..83d2d58e 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -747,6 +747,226 @@ ] } }, + "/api/v1/namespaces/{namespace}/current-deployment/{deployment.deploymentName}": { + "post": { + "summary": "Sets a deployment as the current deployment for its deployment name. Can optionally set the\nmemo of the deployment as well.", + "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.deploymentName", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/current-deployment/{deploymentName}": { + "get": { + "summary": "Returns the current deployment (and its info) for a given deployment name.", + "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": "deploymentName", + "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 name.", + "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": "deploymentName", + "description": "Optional. Use to filter based on deployment name.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}": { + "get": { + "summary": "Describes a worker deployment.", + "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.deploymentName", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/deployments/{deployment.deploymentName}/{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.", + "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.deploymentName", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.buildId", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/schedules": { "get": { "summary": "List all schedules in a namespace.", @@ -3099,7 +3319,270 @@ "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + } + }, + "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/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": { @@ -3112,7 +3595,14 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "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" @@ -3122,7 +3612,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" } } ], @@ -3131,15 +3621,15 @@ ] } }, - "/namespaces/{namespace}/activities/update-options-by-id": { + "/namespaces/{namespace}/current-deployment/{deployment.deploymentName}": { "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 name. Can optionally set the\nmemo of the deployment as well.", + "operationId": "SetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsByIdResponse" + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" } }, "default": { @@ -3152,7 +3642,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "deployment.deploymentName", "in": "path", "required": true, "type": "string" @@ -3162,7 +3657,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsByIdBody" + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" } } ], @@ -3171,15 +3666,15 @@ ] } }, - "/namespaces/{namespace}/archived-workflows": { + "/namespaces/{namespace}/current-deployment/{deploymentName}": { "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 name.", + "operationId": "GetCurrentDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" } }, "default": { @@ -3197,23 +3692,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": "deploymentName", + "in": "path", + "required": true, "type": "string" } ], @@ -3222,15 +3703,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 name.", + "operationId": "ListDeployments", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" + "$ref": "#/definitions/v1ListDeploymentsResponse" } }, "default": { @@ -3243,14 +3724,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 +3737,17 @@ }, { "name": "nextPageToken", - "description": "Next page token", "in": "query", "required": false, "type": "string", "format": "byte" + }, + { + "name": "deploymentName", + "description": "Optional. Use to filter based on deployment name.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -3270,15 +3755,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}": { + "/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}": { "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation", + "summary": "Describes a worker deployment.", + "operationId": "DescribeDeployment", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1DescribeDeploymentResponse" } }, "default": { @@ -3291,62 +3776,21 @@ "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.deploymentName", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", + "name": "deployment.buildId", "in": "path", "required": true, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" - } } ], "tags": [ @@ -3354,15 +3798,15 @@ ] } }, - "/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation", + "/namespaces/{namespace}/deployments/{deployment.deploymentName}/{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.", + "operationId": "GetDeploymentReachability", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" } }, "default": { @@ -3375,25 +3819,21 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "deployment.deploymentName", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "deployment.buildId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" - } + "type": "string" } ], "tags": [ @@ -4868,6 +5308,22 @@ } } }, + "DeploymentInfoTaskQueueInfo": { + "type": "object", + "properties": { + "taskQueueName": { + "type": "string" + }, + "taskQueueType": { + "$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 +5542,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,10 +5568,10 @@ "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": { @@ -5123,12 +5579,12 @@ "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`." + "$ref": "#/definitions/v1Deployment", + "description": "Used to manually pin the execution to a deployment. Must be set if and only if\n`behavior_override` is PINNED. Takes precedence over `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 +5944,28 @@ } } }, + "WorkflowServiceSetCurrentDeploymentBody": { + "type": "object", + "properties": { + "deployment": { + "type": "object", + "properties": { + "buildId": { + "type": "string" + } + }, + "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\ndeployment name + build ID. Both values are required." + }, + "identity": { + "type": "string", + "description": "Optional. The identity of the client who initiated this request." + }, + "updateMemo": { + "$ref": "#/definitions/v1UpdateDeploymentMemo", + "description": "Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values\nthat are exposed when describing deployments. It is a good place for such as operator name,\nlinks to internal deployment pipelines, etc." + } + } + }, "WorkflowServiceSignalWithStartWorkflowExecutionBody": { "type": "object", "properties": { @@ -6104,6 +6582,33 @@ }, "description": "The client request that triggers a Workflow Update." }, + "deploymentv1DeploymentInfo": { + "type": "object", + "properties": { + "deployment": { + "$ref": "#/definitions/v1Deployment" + }, + "status": { + "$ref": "#/definitions/v1DeploymentStatus" + }, + "statusChangeTime": { + "type": "string", + "format": "date-time" + }, + "memo": { + "$ref": "#/definitions/v1Memo", + "description": "A user-defined set of fields. Can be updated via other write operations to the deployment,\nsuch as SetCurrentDeployment." + }, + "taskQueuesInfo": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/DeploymentInfoTaskQueueInfo" + } + } + }, + "description": "Holds information about a worker deployment." + }, "protobufAny": { "type": "object", "properties": { @@ -7233,7 +7738,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 +7895,40 @@ "v1DeleteWorkflowExecutionResponse": { "type": "object" }, + "v1Deployment": { + "type": "object", + "properties": { + "deploymentName": { + "type": "string" + }, + "buildId": { + "type": "string" + } + }, + "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\ndeployment name + build ID. Both values are required." + }, + "v1DeploymentReachability": { + "type": "string", + "enum": [ + "DEPLOYMENT_REACHABILITY_UNSPECIFIED", + "DEPLOYMENT_REACHABILITY_OPEN_WORKFLOWS", + "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_OPEN_WORKFLOWS: The deployment is reachable by open workflows that can only run on this deployment. The\ndeployment cannot be decommissioned safely.\n - DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY: The deployment is not reachable by open workflows but might be still needed by closed\nworkflows who can only run Queries on this deployment. The deployment can be decommissioned\nsafely if user does not 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\nsafely." + }, + "v1DeploymentStatus": { + "type": "string", + "enum": [ + "DEPLOYMENT_STATUS_UNSPECIFIED", + "DEPLOYMENT_STATUS_NO_STATUS", + "DEPLOYMENT_STATUS_RAMPING", + "DEPLOYMENT_STATUS_CURRENT" + ], + "default": "DEPLOYMENT_STATUS_UNSPECIFIED", + "description": "Status of a deployment. Among all deployments with shared deployment name, at most one can have\n`RAMPING` status, and at most one can have `CURRENT` status.\n\n\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment name.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment name." + }, "v1DeprecateNamespaceResponse": { "type": "object", "description": "Deprecated." @@ -7444,6 +7983,14 @@ } } }, + "v1DescribeDeploymentResponse": { + "type": "object", + "properties": { + "deploymentInfo": { + "$ref": "#/definitions/deploymentv1DeploymentInfo" + } + } + }, "v1DescribeNamespaceResponse": { "type": "object", "properties": { @@ -7787,7 +8334,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 +8389,30 @@ }, "description": "GetClusterInfoResponse contains information about Temporal cluster." }, + "v1GetCurrentDeploymentResponse": { + "type": "object", + "properties": { + "currentDeploymentInfo": { + "$ref": "#/definitions/deploymentv1DeploymentInfo" + } + } + }, + "v1GetDeploymentReachabilityResponse": { + "type": "object", + "properties": { + "deploymentInfo": { + "$ref": "#/definitions/deploymentv1DeploymentInfo" + }, + "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 +8946,37 @@ } } }, + "v1ListDeploymentsResponse": { + "type": "object", + "properties": { + "nextPageToken": { + "type": "string", + "format": "byte" + }, + "deployments": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1ListDeploymentsResponseDeploymentInfo" + } + } + } + }, + "v1ListDeploymentsResponseDeploymentInfo": { + "type": "object", + "properties": { + "deployment": { + "$ref": "#/definitions/v1Deployment" + }, + "status": { + "$ref": "#/definitions/v1DeploymentStatus" + }, + "statusChangeTime": { + "type": "string", + "format": "date-time" + } + } + }, "v1ListNamespacesResponse": { "type": "object", "properties": { @@ -9134,7 +9736,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 +11094,14 @@ } } }, + "v1SetCurrentDeploymentResponse": { + "type": "object", + "properties": { + "currentDeployment": { + "$ref": "#/definitions/deploymentv1DeploymentInfo" + } + } + }, "v1Severity": { "type": "string", "enum": [ @@ -11456,6 +12066,21 @@ "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." }, + "v1UpdateDeploymentMemo": { + "type": "object", + "properties": { + "upsertEntries": { + "$ref": "#/definitions/v1Memo" + }, + "removeEntries": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "description": "Used as part of Deployment write APIs to update metadata attached to a deployment." + }, "v1UpdateNamespaceInfo": { "type": "object", "properties": { @@ -11690,9 +12315,9 @@ "$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." @@ -11707,18 +12332,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": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index d70fc752..792575b1 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -635,6 +635,203 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/current-deployment/{deployment.deployment_name}: + post: + tags: + - WorkflowService + description: |- + Sets a deployment as the current deployment for its deployment name. Can optionally set the + memo of the deployment as well. + operationId: SetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_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/{deploymentName}: + get: + tags: + - WorkflowService + description: Returns the current deployment (and its info) for a given deployment name. + operationId: GetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deploymentName + 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 name. + 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: deploymentName + in: query + description: Optional. Use to filter based on deployment name. + 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.deployment_name}/{deployment.build_id}: + get: + tags: + - WorkflowService + description: Describes a worker deployment. + operationId: DescribeDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.deploymentName + in: query + schema: + type: string + - name: deployment.buildId + in: query + 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.deployment_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. + operationId: GetDeploymentReachability + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.deploymentName + in: query + schema: + type: string + - name: deployment.buildId + in: query + 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 +3131,203 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/current-deployment/{deployment.deployment_name}: + post: + tags: + - WorkflowService + description: |- + Sets a deployment as the current deployment for its deployment name. Can optionally set the + memo of the deployment as well. + operationId: SetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_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/{deploymentName}: + get: + tags: + - WorkflowService + description: Returns the current deployment (and its info) for a given deployment name. + operationId: GetCurrentDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deploymentName + 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 name. + 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: deploymentName + in: query + description: Optional. Use to filter based on deployment name. + 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.deployment_name}/{deployment.build_id}: + get: + tags: + - WorkflowService + description: Describes a worker deployment. + operationId: DescribeDeployment + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.deploymentName + in: query + schema: + type: string + - name: deployment.buildId + in: query + 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.deployment_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. + operationId: GetDeploymentReachability + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: deployment.deployment_name + in: path + required: true + schema: + type: string + - name: deployment.build_id + in: path + required: true + schema: + type: string + - name: deployment.deploymentName + in: query + schema: + type: string + - name: deployment.buildId + in: query + 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 +5488,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 +5611,60 @@ components: DeleteScheduleResponse: type: object properties: {} + Deployment: + type: object + properties: + deploymentName: + type: string + buildId: + type: string + description: |- + Identifies a worker deployment. A worker deployment is identified by the combination of + deployment name + build ID. Both values are required. + DeploymentInfo: + type: object + properties: + deployment: + $ref: '#/components/schemas/Deployment' + status: + enum: + - DEPLOYMENT_STATUS_UNSPECIFIED + - DEPLOYMENT_STATUS_NO_STATUS + - DEPLOYMENT_STATUS_RAMPING + - DEPLOYMENT_STATUS_CURRENT + type: string + format: enum + statusChangeTime: + type: string + format: date-time + memo: + allOf: + - $ref: '#/components/schemas/Memo' + description: |- + A user-defined set of fields. Can be updated via other write operations to the deployment, + such as SetCurrentDeployment. + taskQueuesInfo: + type: array + items: + $ref: '#/components/schemas/DeploymentInfo_TaskQueueInfo' + description: Holds information about a worker deployment. + DeploymentInfo_TaskQueueInfo: + type: object + properties: + taskQueueName: + type: string + taskQueueType: + 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 DescribeBatchOperationResponse: type: object properties: @@ -5266,6 +5714,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 +5989,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 +6079,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_OPEN_WORKFLOWS + - 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 +6569,32 @@ components: nextPageToken: type: string format: bytes + ListDeploymentsResponse: + type: object + properties: + nextPageToken: + type: string + format: bytes + deployments: + type: array + items: + $ref: '#/components/schemas/ListDeploymentsResponse_DeploymentInfo' + ListDeploymentsResponse_DeploymentInfo: + type: object + properties: + deployment: + $ref: '#/components/schemas/Deployment' + status: + enum: + - DEPLOYMENT_STATUS_UNSPECIFIED + - DEPLOYMENT_STATUS_NO_STATUS + - DEPLOYMENT_STATUS_RAMPING + - DEPLOYMENT_STATUS_CURRENT + type: string + format: enum + statusChangeTime: + type: string + format: date-time ListNamespacesResponse: type: object properties: @@ -6714,7 +7217,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 +8397,28 @@ 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. + updateMemo: + allOf: + - $ref: '#/components/schemas/UpdateDeploymentMemo' + description: |- + Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values + that are exposed when describing deployments. It is a good place for such as operator name, + links to internal deployment pipelines, etc. + SetCurrentDeploymentResponse: + type: object + properties: + currentDeployment: + $ref: '#/components/schemas/DeploymentInfo' SignalExternalWorkflowExecutionFailedEventAttributes: type: object properties: @@ -8800,6 +9325,16 @@ components: allOf: - $ref: '#/components/schemas/ActivityOptions' description: Activity options after an update + UpdateDeploymentMemo: + type: object + properties: + upsertEntries: + $ref: '#/components/schemas/Memo' + removeEntries: + type: array + items: + type: string + description: Used as part of Deployment write APIs to update metadata attached to a deployment. UpdateNamespaceInfo: type: object properties: @@ -9082,12 +9617,12 @@ components: type: string description: Required. format: enum - workerDeployment: + deployment: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' 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. + Identifies the worker deployment 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 @@ -9099,7 +9634,7 @@ components: 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. @@ -9132,14 +9667,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: @@ -9507,12 +10034,12 @@ 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. @@ -9526,16 +10053,16 @@ components: format: enum deploymentOverride: allOf: - - $ref: '#/components/schemas/WorkerDeployment' + - $ref: '#/components/schemas/Deployment' description: |- - Used to manually pin the execution to a deployment. Must be set when if and only if + Used to manually pin the execution to a deployment. Must be set if and only if `behavior_override` is PINNED. Takes precedence over `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 diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 888b8eae..48f5bc35 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; @@ -157,26 +156,6 @@ message WorkerVersionCapabilities { // 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 00000000..d2cc665c --- /dev/null +++ b/temporal/api/deployment/v1/message.proto @@ -0,0 +1,63 @@ +// 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/deployment.proto"; +import "temporal/api/enums/v1/task_queue.proto"; +import "temporal/api/common/v1/message.proto"; + +// Identifies a worker deployment. A worker deployment is identified by the combination of +// deployment name + build ID. Both values are required. +message Deployment { + string deployment_name = 1; + string build_id = 2; +} + +// Holds information about a worker deployment. +message DeploymentInfo { + Deployment deployment = 1; + enums.v1.DeploymentStatus status = 2; + google.protobuf.Timestamp status_change_time = 3; + // A user-defined set of fields. Can be updated via other write operations to the deployment, + // such as SetCurrentDeployment. + common.v1.Memo memo = 4; + repeated TaskQueueInfo task_queues_info = 5; + + message TaskQueueInfo { + string task_queue_name = 1; + enums.v1.TaskQueueType task_queue_type = 2; + // When server saw the first poller for this task queue in this deployment. + google.protobuf.Timestamp first_poller_time = 3; + } +} diff --git a/temporal/api/enums/v1/deployment.proto b/temporal/api/enums/v1/deployment.proto new file mode 100644 index 00000000..17b3e9eb --- /dev/null +++ b/temporal/api/enums/v1/deployment.proto @@ -0,0 +1,66 @@ +// 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"; + +// Status of a deployment. Among all deployments with shared deployment name, at most one can have +// `RAMPING` status, and at most one can have `CURRENT` status. +// +// (-- api-linter: core::0216::synonyms=disabled +// aip.dev/not-precedent: This enum specifies the status of the deployment among all deployments +// of the same name, therefore `DeploymentStatus` is a better name that `DeploymentState`. --) +enum DeploymentStatus { + DEPLOYMENT_STATUS_UNSPECIFIED = 0; + // The deployment does not have a special status. + DEPLOYMENT_STATUS_NO_STATUS = 1; + // The deployment is the ramping deployment for the deployment name. + DEPLOYMENT_STATUS_RAMPING = 2; + // The deployment is the current deployment for the deployment name. + DEPLOYMENT_STATUS_CURRENT = 3; +} + +// 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 open workflows that can only run on this deployment. The + // deployment cannot be decommissioned safely. + DEPLOYMENT_REACHABILITY_OPEN_WORKFLOWS = 1; + // The deployment is not reachable by open workflows but might be still needed by closed + // workflows who can only run Queries on this deployment. 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/history/v1/message.proto b/temporal/api/history/v1/message.proto index 594ff4ad..1249c475 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; + 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; + deployment.v1.Deployment deployment = 1; } message WorkflowTaskTimedOutEventAttributes { diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 56838aa3..ee00c697 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,19 +108,19 @@ 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; + deployment.v1.Deployment 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 + // Used to manually pin the execution to a deployment. Must be set if and only if // `behavior_override` is PINNED. Takes precedence over `deployment`. - temporal.api.common.v1.WorkerDeployment deployment_override = 4; + deployment.v1.Deployment deployment_override = 4; // 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 @@ -129,7 +130,7 @@ message WorkflowExecutionInfo { 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; + 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 +193,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; + deployment.v1.Deployment last_started_deployment = 19; } message PendingChildExecutionInfo { @@ -364,5 +365,19 @@ 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 + VersioningBehaviorOverride versioning_behavior_override = 1; +} + +// 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. + 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. + deployment.v1.Deployment deployment = 2; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 7f3c4b34..df977c97 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"; @@ -1737,3 +1739,75 @@ 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 { + int32 page_size = 1; + bytes next_page_token = 2; + string namespace = 3; + // Optional. Use to filter based on deployment name. + string deployment_name = 4; +} + +message ListDeploymentsResponse { + bytes next_page_token = 1; + repeated DeploymentInfo deployments = 2; + + message DeploymentInfo { + deployment.v1.Deployment deployment = 1; + enums.v1.DeploymentStatus status = 2; + google.protobuf.Timestamp status_change_time = 3; + } +} + +message SetCurrentDeploymentRequest { + string namespace = 1; + deployment.v1.Deployment deployment = 2; + // Optional. The identity of the client who initiated this request. + string identity = 3; + // Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values + // that are exposed when describing deployments. It is a good place for such as operator name, + // links to internal deployment pipelines, etc. + UpdateDeploymentMemo update_memo = 4; +} + +// Used as part of Deployment write APIs to update metadata attached to a deployment. +message UpdateDeploymentMemo { + common.v1.Memo upsert_entries = 1; + repeated string remove_entries = 2; +} + +message SetCurrentDeploymentResponse { + deployment.v1.DeploymentInfo current_deployment = 1; +} + +// Returns the Current Deployment of a deployment name. +message GetCurrentDeploymentRequest { + string namespace = 1; + string deployment_name = 2; +} + +message GetCurrentDeploymentResponse { + deployment.v1.DeploymentInfo current_deployment_info = 1; +} + +message GetDeploymentReachabilityRequest { + string namespace = 1; + deployment.v1.Deployment deployment = 2; +} + +message GetDeploymentReachabilityResponse { + 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 4a2f513f..23336161 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -772,6 +772,61 @@ service WorkflowService { }; } + // Describes a worker deployment. + rpc DescribeDeployment (DescribeDeploymentRequest) returns (DescribeDeploymentResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}" + } + }; + } + + // Lists worker deployments in the namespace. Optionally can filter based on deployment name. + 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. + rpc GetDeploymentReachability (GetDeploymentReachabilityRequest) returns (GetDeploymentReachabilityResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability" + } + }; + } + + // Returns the current deployment (and its info) for a given deployment name. + rpc GetCurrentDeployment (GetCurrentDeploymentRequest) returns (GetCurrentDeploymentResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/current-deployment/{deployment_name}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/current-deployment/{deployment_name}" + } + }; + } + + // Sets a deployment as the current deployment for its deployment name. Can optionally set the + // memo of the deployment as well. + rpc SetCurrentDeployment (SetCurrentDeploymentRequest) returns (SetCurrentDeploymentResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/current-deployment/{deployment.deployment_name}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/current-deployment/{deployment.deployment_name}" + body: "*" + } + }; + } + // Invokes the specified Update function on user Workflow code. rpc UpdateWorkflowExecution(UpdateWorkflowExecutionRequest) returns (UpdateWorkflowExecutionResponse) { option (google.api.http) = { From 12ec5b2f7b2cf1b6a3cab4094b74e69e29ebbcd4 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Sun, 17 Nov 2024 15:42:20 -0800 Subject: [PATCH 2/6] Move UpdateDeploymentMemo to deployment dir --- temporal/api/deployment/v1/message.proto | 6 ++++++ temporal/api/workflowservice/v1/request_response.proto | 8 +------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index d2cc665c..b2be7d6a 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -61,3 +61,9 @@ message DeploymentInfo { google.protobuf.Timestamp first_poller_time = 3; } } + +// Used as part of Deployment write APIs to update metadata attached to a deployment. +message UpdateDeploymentMemo { + common.v1.Memo upsert_entries = 1; + repeated string remove_entries = 2; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index df977c97..42cf18d7 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1776,13 +1776,7 @@ message SetCurrentDeploymentRequest { // Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values // that are exposed when describing deployments. It is a good place for such as operator name, // links to internal deployment pipelines, etc. - UpdateDeploymentMemo update_memo = 4; -} - -// Used as part of Deployment write APIs to update metadata attached to a deployment. -message UpdateDeploymentMemo { - common.v1.Memo upsert_entries = 1; - repeated string remove_entries = 2; + deployment.v1.UpdateDeploymentMemo update_memo = 4; } message SetCurrentDeploymentResponse { From bf6ec802dc691dd1d66903ca134c9d186c439b80 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Mon, 18 Nov 2024 12:48:19 -0800 Subject: [PATCH 3/6] Address feedback & rename deployment_name --- openapi/openapiv2.json | 113 +++++++------- openapi/openapiv3.yaml | 139 +++++++++--------- temporal/api/common/v1/message.proto | 8 +- temporal/api/deployment/v1/message.proto | 24 +-- temporal/api/enums/v1/deployment.proto | 10 +- temporal/api/history/v1/message.proto | 4 +- temporal/api/workflow/v1/message.proto | 29 ++-- .../workflowservice/v1/request_response.proto | 16 +- temporal/api/workflowservice/v1/service.proto | 25 ++-- 9 files changed, 186 insertions(+), 182 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 83d2d58e..6e98b529 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -747,9 +747,9 @@ ] } }, - "/api/v1/namespaces/{namespace}/current-deployment/{deployment.deploymentName}": { + "/api/v1/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { - "summary": "Sets a deployment as the current deployment for its deployment name. Can optionally set the\nmemo of the deployment as well.", + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.", "operationId": "SetCurrentDeployment2", "responses": { "200": { @@ -773,7 +773,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -792,9 +792,9 @@ ] } }, - "/api/v1/namespaces/{namespace}/current-deployment/{deploymentName}": { + "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { "get": { - "summary": "Returns the current deployment (and its info) for a given deployment name.", + "summary": "Returns the current deployment (and its info) for a given deployment series.", "operationId": "GetCurrentDeployment2", "responses": { "200": { @@ -818,7 +818,7 @@ "type": "string" }, { - "name": "deploymentName", + "name": "seriesName", "in": "path", "required": true, "type": "string" @@ -831,7 +831,7 @@ }, "/api/v1/namespaces/{namespace}/deployments": { "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment name.", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.", "operationId": "ListDeployments2", "responses": { "200": { @@ -869,8 +869,8 @@ "format": "byte" }, { - "name": "deploymentName", - "description": "Optional. Use to filter based on deployment name.", + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", "in": "query", "required": false, "type": "string" @@ -881,7 +881,7 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}": { + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { "summary": "Describes a worker deployment.", "operationId": "DescribeDeployment2", @@ -907,7 +907,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -924,7 +924,7 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}/reachability": { + "/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.", "operationId": "GetDeploymentReachability2", @@ -950,7 +950,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -3621,9 +3621,9 @@ ] } }, - "/namespaces/{namespace}/current-deployment/{deployment.deploymentName}": { + "/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { "post": { - "summary": "Sets a deployment as the current deployment for its deployment name. Can optionally set the\nmemo of the deployment as well.", + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.", "operationId": "SetCurrentDeployment", "responses": { "200": { @@ -3647,7 +3647,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -3666,9 +3666,9 @@ ] } }, - "/namespaces/{namespace}/current-deployment/{deploymentName}": { + "/namespaces/{namespace}/current-deployment/{seriesName}": { "get": { - "summary": "Returns the current deployment (and its info) for a given deployment name.", + "summary": "Returns the current deployment (and its info) for a given deployment series.", "operationId": "GetCurrentDeployment", "responses": { "200": { @@ -3692,7 +3692,7 @@ "type": "string" }, { - "name": "deploymentName", + "name": "seriesName", "in": "path", "required": true, "type": "string" @@ -3705,7 +3705,7 @@ }, "/namespaces/{namespace}/deployments": { "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment name.", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.", "operationId": "ListDeployments", "responses": { "200": { @@ -3743,8 +3743,8 @@ "format": "byte" }, { - "name": "deploymentName", - "description": "Optional. Use to filter based on deployment name.", + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", "in": "query", "required": false, "type": "string" @@ -3755,7 +3755,7 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}": { + "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { "summary": "Describes a worker deployment.", "operationId": "DescribeDeployment", @@ -3781,7 +3781,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -3798,7 +3798,7 @@ ] } }, - "/namespaces/{namespace}/deployments/{deployment.deploymentName}/{deployment.buildId}/reachability": { + "/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.", "operationId": "GetDeploymentReachability", @@ -3824,7 +3824,7 @@ "type": "string" }, { - "name": "deployment.deploymentName", + "name": "deployment.seriesName", "in": "path", "required": true, "type": "string" @@ -5311,10 +5311,10 @@ "DeploymentInfoTaskQueueInfo": { "type": "object", "properties": { - "taskQueueName": { + "name": { "type": "string" }, - "taskQueueType": { + "type": { "$ref": "#/definitions/v1TaskQueueType" }, "firstPollerTime": { @@ -5574,13 +5574,9 @@ "$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/v1Deployment", - "description": "Used to manually pin the execution to a deployment. Must be set if and only if\n`behavior_override` is PINNED. Takes precedence over `deployment`." + "manualOverride": { + "$ref": "#/definitions/v1VersioningBehaviorOverride", + "description": "Manual override for execution's versioning behavior. Takes precedence over `behavior`\nand `deployment`." }, "redirectInfo": { "$ref": "#/definitions/VersioningInfoRedirectInfo", @@ -5954,15 +5950,15 @@ "type": "string" } }, - "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\ndeployment name + build ID. Both values are required." + "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\nseries name + build ID. Both values are required." }, "identity": { "type": "string", "description": "Optional. The identity of the client who initiated this request." }, - "updateMemo": { - "$ref": "#/definitions/v1UpdateDeploymentMemo", - "description": "Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values\nthat are exposed when describing deployments. It is a good place for such as operator name,\nlinks to internal deployment pipelines, etc." + "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." } } }, @@ -6595,11 +6591,15 @@ "type": "string", "format": "date-time" }, - "memo": { - "$ref": "#/definitions/v1Memo", - "description": "A user-defined set of fields. Can be updated via other write operations to the deployment,\nsuch as SetCurrentDeployment." + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "byte" + }, + "description": "A user-defined set of key-values. Can be updated as part of write operations to the\ndeployment, such as `SetCurrentDeployment`." }, - "taskQueuesInfo": { + "taskQueueInfos": { "type": "array", "items": { "type": "object", @@ -7898,14 +7898,14 @@ "v1Deployment": { "type": "object", "properties": { - "deploymentName": { + "seriesName": { "type": "string" }, "buildId": { "type": "string" } }, - "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\ndeployment name + build ID. Both values are required." + "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\nseries name + build ID. Both values are required." }, "v1DeploymentReachability": { "type": "string", @@ -7927,7 +7927,7 @@ "DEPLOYMENT_STATUS_CURRENT" ], "default": "DEPLOYMENT_STATUS_UNSPECIFIED", - "description": "Status of a deployment. Among all deployments with shared deployment name, at most one can have\n`RAMPING` status, and at most one can have `CURRENT` status.\n\n\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment name.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment name." + "description": "Status of a deployment within its deployment series. Any given deployment series can at most have\none `RAMPING` deployment, and one `CURRENT` deployment.\n\n\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment series.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment series." }, "v1DeprecateNamespaceResponse": { "type": "object", @@ -12066,17 +12066,22 @@ "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." }, - "v1UpdateDeploymentMemo": { + "v1UpdateDeploymentMetadata": { "type": "object", "properties": { "upsertEntries": { - "$ref": "#/definitions/v1Memo" + "type": "object", + "additionalProperties": { + "type": "string", + "format": "byte" + } }, "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." @@ -12320,7 +12325,7 @@ "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 manually override the versioning behavior of a specific workflow execution. If set, takes\nprecedence over the SDK-sent Versioning Behavior.\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated." }, "v1WaitPolicy": { "type": "object", @@ -12343,9 +12348,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." @@ -12361,9 +12366,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" diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 792575b1..c2113bb0 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -635,13 +635,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/current-deployment/{deployment.deployment_name}: + /api/v1/namespaces/{namespace}/current-deployment/{deployment.series_name}: post: tags: - WorkflowService description: |- - Sets a deployment as the current deployment for its deployment name. Can optionally set the - memo of the deployment as well. + Sets a deployment as the current deployment for its deployment series. Can optionally update + the metadata of the deployment as well. operationId: SetCurrentDeployment parameters: - name: namespace @@ -649,7 +649,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -673,11 +673,11 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/current-deployment/{deploymentName}: + /api/v1/namespaces/{namespace}/current-deployment/{seriesName}: get: tags: - WorkflowService - description: Returns the current deployment (and its info) for a given deployment name. + description: Returns the current deployment (and its info) for a given deployment series. operationId: GetCurrentDeployment parameters: - name: namespace @@ -685,7 +685,7 @@ paths: required: true schema: type: string - - name: deploymentName + - name: seriesName in: path required: true schema: @@ -707,7 +707,9 @@ paths: get: tags: - WorkflowService - description: Lists worker deployments in the namespace. Optionally can filter based on deployment name. + description: |- + Lists worker deployments in the namespace. Optionally can filter based on deployment series + name. operationId: ListDeployments parameters: - name: namespace @@ -725,9 +727,9 @@ paths: schema: type: string format: bytes - - name: deploymentName + - name: seriesName in: query - description: Optional. Use to filter based on deployment name. + description: Optional. Use to filter based on exact series name match. schema: type: string responses: @@ -743,7 +745,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}: + /api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}: get: tags: - WorkflowService @@ -755,7 +757,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -765,7 +767,7 @@ paths: required: true schema: type: string - - name: deployment.deploymentName + - name: deployment.seriesName in: query schema: type: string @@ -786,7 +788,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability: + /api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability: get: tags: - WorkflowService @@ -801,7 +803,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -811,7 +813,7 @@ paths: required: true schema: type: string - - name: deployment.deploymentName + - name: deployment.seriesName in: query schema: type: string @@ -3131,13 +3133,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/current-deployment/{deployment.deployment_name}: + /namespaces/{namespace}/current-deployment/{deployment.series_name}: post: tags: - WorkflowService description: |- - Sets a deployment as the current deployment for its deployment name. Can optionally set the - memo of the deployment as well. + Sets a deployment as the current deployment for its deployment series. Can optionally update + the metadata of the deployment as well. operationId: SetCurrentDeployment parameters: - name: namespace @@ -3145,7 +3147,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -3169,11 +3171,11 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/current-deployment/{deploymentName}: + /namespaces/{namespace}/current-deployment/{seriesName}: get: tags: - WorkflowService - description: Returns the current deployment (and its info) for a given deployment name. + description: Returns the current deployment (and its info) for a given deployment series. operationId: GetCurrentDeployment parameters: - name: namespace @@ -3181,7 +3183,7 @@ paths: required: true schema: type: string - - name: deploymentName + - name: seriesName in: path required: true schema: @@ -3203,7 +3205,9 @@ paths: get: tags: - WorkflowService - description: Lists worker deployments in the namespace. Optionally can filter based on deployment name. + description: |- + Lists worker deployments in the namespace. Optionally can filter based on deployment series + name. operationId: ListDeployments parameters: - name: namespace @@ -3221,9 +3225,9 @@ paths: schema: type: string format: bytes - - name: deploymentName + - name: seriesName in: query - description: Optional. Use to filter based on deployment name. + description: Optional. Use to filter based on exact series name match. schema: type: string responses: @@ -3239,7 +3243,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}: + /namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}: get: tags: - WorkflowService @@ -3251,7 +3255,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -3261,7 +3265,7 @@ paths: required: true schema: type: string - - name: deployment.deploymentName + - name: deployment.seriesName in: query schema: type: string @@ -3282,7 +3286,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' - /namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability: + /namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability: get: tags: - WorkflowService @@ -3297,7 +3301,7 @@ paths: required: true schema: type: string - - name: deployment.deployment_name + - name: deployment.series_name in: path required: true schema: @@ -3307,7 +3311,7 @@ paths: required: true schema: type: string - - name: deployment.deploymentName + - name: deployment.seriesName in: query schema: type: string @@ -5614,13 +5618,13 @@ components: Deployment: type: object properties: - deploymentName: + seriesName: type: string buildId: type: string description: |- Identifies a worker deployment. A worker deployment is identified by the combination of - deployment name + build ID. Both values are required. + series name + build ID. Both values are required. DeploymentInfo: type: object properties: @@ -5637,13 +5641,15 @@ components: statusChangeTime: type: string format: date-time - memo: - allOf: - - $ref: '#/components/schemas/Memo' + metadata: + type: object + additionalProperties: + type: string + format: bytes description: |- - A user-defined set of fields. Can be updated via other write operations to the deployment, - such as SetCurrentDeployment. - taskQueuesInfo: + A user-defined set of key-values. Can be updated as part of write operations to the + deployment, such as `SetCurrentDeployment`. + taskQueueInfos: type: array items: $ref: '#/components/schemas/DeploymentInfo_TaskQueueInfo' @@ -5651,9 +5657,9 @@ components: DeploymentInfo_TaskQueueInfo: type: object properties: - taskQueueName: + name: type: string - taskQueueType: + type: enum: - TASK_QUEUE_TYPE_UNSPECIFIED - TASK_QUEUE_TYPE_WORKFLOW @@ -8407,12 +8413,12 @@ components: identity: type: string description: Optional. The identity of the client who initiated this request. - updateMemo: + updateMetadata: allOf: - - $ref: '#/components/schemas/UpdateDeploymentMemo' + - $ref: '#/components/schemas/UpdateDeploymentMetadata' description: |- - Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values - that are exposed when describing deployments. It is a good place for such as operator name, + 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 @@ -9325,15 +9331,19 @@ components: allOf: - $ref: '#/components/schemas/ActivityOptions' description: Activity options after an update - UpdateDeploymentMemo: + UpdateDeploymentMetadata: type: object properties: upsertEntries: - $ref: '#/components/schemas/Memo' + type: object + additionalProperties: + type: string + format: bytes 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 @@ -9624,11 +9634,10 @@ components: Required if behavior is `PINNED`. Must be null if behavior is `AUTO_UPGRADE`. Identifies the worker deployment 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. + Used to manually override the versioning behavior of a specific workflow execution. If set, takes + precedence over the SDK-sent Versioning Behavior. + To remove the override, call `UpdateWorkflowExecutionOptions` with a null + `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. VersioningInfo_RedirectInfo: type: object properties: @@ -9678,9 +9687,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 @@ -9698,9 +9707,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 @@ -10043,20 +10052,12 @@ components: 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: + manualOverride: allOf: - - $ref: '#/components/schemas/Deployment' + - $ref: '#/components/schemas/VersioningBehaviorOverride' description: |- - Used to manually pin the execution to a deployment. Must be set if and only if - `behavior_override` is PINNED. Takes precedence over `deployment`. + Manual override for execution's versioning behavior. Takes precedence over `behavior` + and `deployment`. redirectInfo: allOf: - $ref: '#/components/schemas/VersioningInfo_RedirectInfo' diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 48f5bc35..c3c61d1f 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -133,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. } @@ -150,8 +150,8 @@ 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" } diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index b2be7d6a..0f69924c 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -35,35 +35,35 @@ import "google/protobuf/timestamp.proto"; import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/task_queue.proto"; -import "temporal/api/common/v1/message.proto"; // Identifies a worker deployment. A worker deployment is identified by the combination of -// deployment name + build ID. Both values are required. +// series name + build ID. Both values are required. message Deployment { - string deployment_name = 1; + string series_name = 1; string build_id = 2; } // Holds information about a worker deployment. message DeploymentInfo { Deployment deployment = 1; - enums.v1.DeploymentStatus status = 2; + temporal.api.enums.v1.DeploymentStatus status = 2; google.protobuf.Timestamp status_change_time = 3; - // A user-defined set of fields. Can be updated via other write operations to the deployment, - // such as SetCurrentDeployment. - common.v1.Memo memo = 4; - repeated TaskQueueInfo task_queues_info = 5; + // A user-defined set of key-values. Can be updated as part of write operations to the + // deployment, such as `SetCurrentDeployment`. + map metadata = 4; + repeated TaskQueueInfo task_queue_infos = 5; message TaskQueueInfo { - string task_queue_name = 1; - enums.v1.TaskQueueType task_queue_type = 2; + 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 UpdateDeploymentMemo { - common.v1.Memo upsert_entries = 1; +message UpdateDeploymentMetadata { + map upsert_entries = 1; + // List of keys to remove from the metadata. repeated string remove_entries = 2; } diff --git a/temporal/api/enums/v1/deployment.proto b/temporal/api/enums/v1/deployment.proto index 17b3e9eb..57c57671 100644 --- a/temporal/api/enums/v1/deployment.proto +++ b/temporal/api/enums/v1/deployment.proto @@ -31,19 +31,19 @@ option java_outer_classname = "DeploymentProto"; option ruby_package = "Temporalio::Api::Enums::V1"; option csharp_namespace = "Temporalio.Api.Enums.V1"; -// Status of a deployment. Among all deployments with shared deployment name, at most one can have -// `RAMPING` status, and at most one can have `CURRENT` status. +// Status of a deployment within its deployment series. Any given deployment series can at most have +// one `RAMPING` deployment, and one `CURRENT` deployment. // // (-- api-linter: core::0216::synonyms=disabled // aip.dev/not-precedent: This enum specifies the status of the deployment among all deployments -// of the same name, therefore `DeploymentStatus` is a better name that `DeploymentState`. --) +// in the same series, therefore `DeploymentStatus` is a better name that `DeploymentState`. --) enum DeploymentStatus { DEPLOYMENT_STATUS_UNSPECIFIED = 0; // The deployment does not have a special status. DEPLOYMENT_STATUS_NO_STATUS = 1; - // The deployment is the ramping deployment for the deployment name. + // The deployment is the ramping deployment for the deployment series. DEPLOYMENT_STATUS_RAMPING = 2; - // The deployment is the current deployment for the deployment name. + // The deployment is the current deployment for the deployment series. DEPLOYMENT_STATUS_CURRENT = 3; } diff --git a/temporal/api/history/v1/message.proto b/temporal/api/history/v1/message.proto index 1249c475..33073a87 100644 --- a/temporal/api/history/v1/message.proto +++ b/temporal/api/history/v1/message.proto @@ -256,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. - deployment.v1.Deployment 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; @@ -269,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. - deployment.v1.Deployment 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 ee00c697..eef95a14 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -113,24 +113,22 @@ message WorkflowExecutionInfo { 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. - deployment.v1.Deployment 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 if and only if - // `behavior_override` is PINNED. Takes precedence over `deployment`. - deployment.v1.Deployment deployment_override = 4; + temporal.api.deployment.v1.Deployment deployment = 2; + // Manual override for execution's versioning behavior. Takes precedence over `behavior` + // and `deployment`. + VersioningBehaviorOverride manual_override = 3; // When present, indicates the workflow is being redirected to a different deployment. // 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. - deployment.v1.Deployment 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. @@ -193,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. - deployment.v1.Deployment last_started_deployment = 19; + temporal.api.deployment.v1.Deployment last_started_deployment = 19; } message PendingChildExecutionInfo { @@ -368,16 +366,15 @@ message WorkflowExecutionOptions { VersioningBehaviorOverride versioning_behavior_override = 1; } -// 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. +// Used to manually override the versioning behavior of a specific workflow execution. If set, takes +// precedence over the SDK-sent Versioning Behavior. +// To remove the override, call `UpdateWorkflowExecutionOptions` with a null +// `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. message VersioningBehaviorOverride { // Required. - enums.v1.VersioningBehavior behavior = 1; + 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. - deployment.v1.Deployment deployment = 2; + 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 42cf18d7..c4b3f24f 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -360,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; } @@ -1753,8 +1753,8 @@ message ListDeploymentsRequest { int32 page_size = 1; bytes next_page_token = 2; string namespace = 3; - // Optional. Use to filter based on deployment name. - string deployment_name = 4; + // Optional. Use to filter based on exact series name match. + string series_name = 4; } message ListDeploymentsResponse { @@ -1773,20 +1773,20 @@ message SetCurrentDeploymentRequest { deployment.v1.Deployment deployment = 2; // Optional. The identity of the client who initiated this request. string identity = 3; - // Optional. Use to add or remove memo entries. Memo can contain user-defined keys and values - // that are exposed when describing deployments. It is a good place for such as operator name, + // 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. - deployment.v1.UpdateDeploymentMemo update_memo = 4; + deployment.v1.UpdateDeploymentMetadata update_metadata = 4; } message SetCurrentDeploymentResponse { deployment.v1.DeploymentInfo current_deployment = 1; } -// Returns the Current Deployment of a deployment name. +// Returns the Current Deployment of a deployment series. message GetCurrentDeploymentRequest { string namespace = 1; - string deployment_name = 2; + string series_name = 2; } message GetCurrentDeploymentResponse { diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 23336161..d14593e8 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -775,14 +775,15 @@ service WorkflowService { // Describes a worker deployment. rpc DescribeDeployment (DescribeDeploymentRequest) returns (DescribeDeploymentResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}" + get: "/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}" additional_bindings { - get: "/api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}" + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}" } }; } - // Lists worker deployments in the namespace. Optionally can filter based on deployment name. + // Lists worker deployments in the namespace. Optionally can filter based on deployment series + // name. rpc ListDeployments (ListDeploymentsRequest) returns (ListDeploymentsResponse) { option (google.api.http) = { get: "/namespaces/{namespace}/deployments" @@ -797,31 +798,31 @@ service WorkflowService { // `status` and existing workflows that depend on the given deployment for their execution. rpc GetDeploymentReachability (GetDeploymentReachabilityRequest) returns (GetDeploymentReachabilityResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability" + get: "/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability" additional_bindings { - get: "/api/v1/namespaces/{namespace}/deployments/{deployment.deployment_name}/{deployment.build_id}/reachability" + get: "/api/v1/namespaces/{namespace}/deployments/{deployment.series_name}/{deployment.build_id}/reachability" } }; } - // Returns the current deployment (and its info) for a given deployment name. + // Returns the current deployment (and its info) for a given deployment series. rpc GetCurrentDeployment (GetCurrentDeploymentRequest) returns (GetCurrentDeploymentResponse) { option (google.api.http) = { - get: "/namespaces/{namespace}/current-deployment/{deployment_name}" + get: "/namespaces/{namespace}/current-deployment/{series_name}" additional_bindings { - get: "/api/v1/namespaces/{namespace}/current-deployment/{deployment_name}" + get: "/api/v1/namespaces/{namespace}/current-deployment/{series_name}" } }; } - // Sets a deployment as the current deployment for its deployment name. Can optionally set the - // memo of the deployment as well. + // Sets a deployment as the current deployment for its deployment series. Can optionally update + // the metadata of the deployment as well. rpc SetCurrentDeployment (SetCurrentDeploymentRequest) returns (SetCurrentDeploymentResponse) { option (google.api.http) = { - post: "/namespaces/{namespace}/current-deployment/{deployment.deployment_name}" + post: "/namespaces/{namespace}/current-deployment/{deployment.series_name}" body: "*" additional_bindings { - post: "/api/v1/namespaces/{namespace}/current-deployment/{deployment.deployment_name}" + post: "/api/v1/namespaces/{namespace}/current-deployment/{deployment.series_name}" body: "*" } }; From a432c29ad0b120ef9cca49bfdeb1c4e1462518fc Mon Sep 17 00:00:00 2001 From: ShahabT Date: Mon, 18 Nov 2024 17:30:04 -0800 Subject: [PATCH 4/6] Addressed comments --- openapi/openapiv2.json | 53 +++++----- openapi/openapiv3.yaml | 96 ++++++++++++------- temporal/api/deployment/v1/message.proto | 6 +- temporal/api/enums/v1/deployment.proto | 16 ++-- temporal/api/workflow/v1/message.proto | 13 +-- .../workflowservice/v1/request_response.proto | 3 +- temporal/api/workflowservice/v1/service.proto | 8 ++ 7 files changed, 114 insertions(+), 81 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 6e98b529..028cfe44 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -749,7 +749,7 @@ }, "/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.", + "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": { @@ -794,7 +794,7 @@ }, "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { "get": { - "summary": "Returns the current deployment (and its info) for a given deployment series.", + "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": { @@ -831,7 +831,7 @@ }, "/api/v1/namespaces/{namespace}/deployments": { "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.", + "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": { @@ -883,7 +883,7 @@ }, "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { - "summary": "Describes a worker deployment.", + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "DescribeDeployment2", "responses": { "200": { @@ -926,7 +926,7 @@ }, "/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.", + "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": { @@ -3623,7 +3623,7 @@ }, "/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.", + "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": { @@ -3668,7 +3668,7 @@ }, "/namespaces/{namespace}/current-deployment/{seriesName}": { "get": { - "summary": "Returns the current deployment (and its info) for a given deployment series.", + "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": { @@ -3705,7 +3705,7 @@ }, "/namespaces/{namespace}/deployments": { "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.", + "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": { @@ -3757,7 +3757,7 @@ }, "/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { "get": { - "summary": "Describes a worker deployment.", + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.", "operationId": "DescribeDeployment", "responses": { "200": { @@ -3800,7 +3800,7 @@ }, "/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.", + "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": { @@ -5574,9 +5574,9 @@ "$ref": "#/definitions/v1Deployment", "description": "The worker deployment to which this workflow is assigned currently.\nMust be present if and only if `behavior` is set." }, - "manualOverride": { - "$ref": "#/definitions/v1VersioningBehaviorOverride", - "description": "Manual override for execution's versioning behavior. Takes precedence over `behavior`\nand `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", @@ -6587,15 +6587,14 @@ "status": { "$ref": "#/definitions/v1DeploymentStatus" }, - "statusChangeTime": { + "lastBecameCurrentTime": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { - "type": "string", - "format": "byte" + "type": "string" }, "description": "A user-defined set of key-values. Can be updated as part of write operations to the\ndeployment, such as `SetCurrentDeployment`." }, @@ -7911,12 +7910,12 @@ "type": "string", "enum": [ "DEPLOYMENT_REACHABILITY_UNSPECIFIED", - "DEPLOYMENT_REACHABILITY_OPEN_WORKFLOWS", + "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_OPEN_WORKFLOWS: The deployment is reachable by open workflows that can only run on this deployment. The\ndeployment cannot be decommissioned safely.\n - DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY: The deployment is not reachable by open workflows but might be still needed by closed\nworkflows who can only run Queries on this deployment. The deployment can be decommissioned\nsafely if user does not 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\nsafely." + "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." }, "v1DeploymentStatus": { "type": "string", @@ -7927,7 +7926,7 @@ "DEPLOYMENT_STATUS_CURRENT" ], "default": "DEPLOYMENT_STATUS_UNSPECIFIED", - "description": "Status of a deployment within its deployment series. Any given deployment series can at most have\none `RAMPING` deployment, and one `CURRENT` deployment.\n\n\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment series.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment series." + "description": "Status of a deployment within its deployment series. Any given deployment series can at most have\none `RAMPING` deployment, and one `CURRENT` deployment.\n\n\n - DEPLOYMENT_STATUS_UNSPECIFIED: Status of the deployment is not specified.\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment series.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment series." }, "v1DeprecateNamespaceResponse": { "type": "object", @@ -11097,7 +11096,10 @@ "v1SetCurrentDeploymentResponse": { "type": "object", "properties": { - "currentDeployment": { + "currentDeploymentInfo": { + "$ref": "#/definitions/deploymentv1DeploymentInfo" + }, + "previousCurrentDeploymentInfo": { "$ref": "#/definitions/deploymentv1DeploymentInfo" } } @@ -12072,8 +12074,7 @@ "upsertEntries": { "type": "object", "additionalProperties": { - "type": "string", - "format": "byte" + "type": "string" } }, "removeEntries": { @@ -12313,7 +12314,7 @@ "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." }, - "v1VersioningBehaviorOverride": { + "v1VersioningOverride": { "type": "object", "properties": { "behavior": { @@ -12636,9 +12637,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 c2113bb0..dd4d1b8d 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -642,6 +642,7 @@ paths: 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 @@ -677,7 +678,9 @@ paths: get: tags: - WorkflowService - description: Returns the current deployment (and its info) for a given deployment series. + 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 @@ -710,6 +713,7 @@ paths: 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 @@ -749,7 +753,9 @@ paths: get: tags: - WorkflowService - description: Describes a worker deployment. + description: |- + Describes a worker deployment. + Experimental. This API might significantly change or be removed in a future release. operationId: DescribeDeployment parameters: - name: namespace @@ -796,6 +802,10 @@ paths: 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 @@ -3140,6 +3150,7 @@ paths: 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 @@ -3175,7 +3186,9 @@ paths: get: tags: - WorkflowService - description: Returns the current deployment (and its info) for a given deployment series. + 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 @@ -3208,6 +3221,7 @@ paths: 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 @@ -3247,7 +3261,9 @@ paths: get: tags: - WorkflowService - description: Describes a worker deployment. + description: |- + Describes a worker deployment. + Experimental. This API might significantly change or be removed in a future release. operationId: DescribeDeployment parameters: - name: namespace @@ -3294,6 +3310,10 @@ paths: 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 @@ -5638,14 +5658,13 @@ components: - DEPLOYMENT_STATUS_CURRENT type: string format: enum - statusChangeTime: + lastBecameCurrentTime: type: string format: date-time metadata: type: object additionalProperties: type: string - format: bytes description: |- A user-defined set of key-values. Can be updated as part of write operations to the deployment, such as `SetCurrentDeployment`. @@ -6098,7 +6117,7 @@ components: reachability: enum: - DEPLOYMENT_REACHABILITY_UNSPECIFIED - - DEPLOYMENT_REACHABILITY_OPEN_WORKFLOWS + - DEPLOYMENT_REACHABILITY_REACHABLE - DEPLOYMENT_REACHABILITY_CLOSED_WORKFLOWS_ONLY - DEPLOYMENT_REACHABILITY_UNREACHABLE type: string @@ -8423,7 +8442,9 @@ components: SetCurrentDeploymentResponse: type: object properties: - currentDeployment: + currentDeploymentInfo: + $ref: '#/components/schemas/DeploymentInfo' + previousCurrentDeploymentInfo: $ref: '#/components/schemas/DeploymentInfo' SignalExternalWorkflowExecutionFailedEventAttributes: type: object @@ -9338,7 +9359,6 @@ components: type: object additionalProperties: type: string - format: bytes removeEntries: type: array items: @@ -9616,7 +9636,27 @@ components: type: string format: date-time description: VersionInfo contains details about current and recommended release versions as well as alerts and upgrade instructions. - VersioningBehaviorOverride: + VersioningInfo_RedirectInfo: + type: object + properties: + deployment: + allOf: + - $ref: '#/components/schemas/Deployment' + description: |- + The target deployment of the redirect. Null means a so-far-versioned workflow is + being redirected to unversioned workers. + behaviorOverride: + enum: + - VERSIONING_BEHAVIOR_UNSPECIFIED + - VERSIONING_BEHAVIOR_PINNED + - VERSIONING_BEHAVIOR_AUTO_UPGRADE + type: string + description: |- + 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. + format: enum + VersioningOverride: type: object properties: behavior: @@ -9638,26 +9678,6 @@ components: precedence over the SDK-sent Versioning Behavior. To remove the override, call `UpdateWorkflowExecutionOptions` with a null `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. - VersioningInfo_RedirectInfo: - type: object - properties: - deployment: - allOf: - - $ref: '#/components/schemas/Deployment' - description: |- - The target deployment of the redirect. Null means a so-far-versioned workflow is - being redirected to unversioned workers. - behaviorOverride: - enum: - - VERSIONING_BEHAVIOR_UNSPECIFIED - - VERSIONING_BEHAVIOR_PINNED - - VERSIONING_BEHAVIOR_AUTO_UPGRADE - type: string - description: |- - 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. - format: enum WaitPolicy: type: object properties: @@ -10052,12 +10072,12 @@ components: description: |- The worker deployment to which this workflow is assigned currently. Must be present if and only if `behavior` is set. - manualOverride: + versioningOverride: allOf: - - $ref: '#/components/schemas/VersioningBehaviorOverride' + - $ref: '#/components/schemas/VersioningOverride' description: |- - Manual override for execution's versioning behavior. Takes precedence over `behavior` - and `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' @@ -10071,10 +10091,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/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 0f69924c..2005638b 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -47,10 +47,10 @@ message Deployment { message DeploymentInfo { Deployment deployment = 1; temporal.api.enums.v1.DeploymentStatus status = 2; - google.protobuf.Timestamp status_change_time = 3; + google.protobuf.Timestamp last_became_current_time = 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; + map metadata = 4; repeated TaskQueueInfo task_queue_infos = 5; message TaskQueueInfo { @@ -63,7 +63,7 @@ message DeploymentInfo { // Used as part of Deployment write APIs to update metadata attached to a deployment. message UpdateDeploymentMetadata { - map upsert_entries = 1; + map upsert_entries = 1; // List of keys to remove from the metadata. repeated string remove_entries = 2; } diff --git a/temporal/api/enums/v1/deployment.proto b/temporal/api/enums/v1/deployment.proto index 57c57671..35da02eb 100644 --- a/temporal/api/enums/v1/deployment.proto +++ b/temporal/api/enums/v1/deployment.proto @@ -38,6 +38,7 @@ option csharp_namespace = "Temporalio.Api.Enums.V1"; // aip.dev/not-precedent: This enum specifies the status of the deployment among all deployments // in the same series, therefore `DeploymentStatus` is a better name that `DeploymentState`. --) enum DeploymentStatus { + // Status of the deployment is not specified. DEPLOYMENT_STATUS_UNSPECIFIED = 0; // The deployment does not have a special status. DEPLOYMENT_STATUS_NO_STATUS = 1; @@ -52,15 +53,14 @@ enum DeploymentStatus { enum DeploymentReachability { // Reachability level is not specified. DEPLOYMENT_REACHABILITY_UNSPECIFIED = 0; - // The deployment is reachable by open workflows that can only run on this deployment. The - // deployment cannot be decommissioned safely. - DEPLOYMENT_REACHABILITY_OPEN_WORKFLOWS = 1; - // The deployment is not reachable by open workflows but might be still needed by closed - // workflows who can only run Queries on this deployment. The deployment can be decommissioned - // safely if user does not query closed workflows. + // 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 went out of retention period. The deployment can be decommissioned safely. DEPLOYMENT_REACHABILITY_UNREACHABLE = 3; } diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index eef95a14..bd827181 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -114,9 +114,9 @@ message WorkflowExecutionInfo { // The worker deployment to which this workflow is assigned currently. // Must be present if and only if `behavior` is set. temporal.api.deployment.v1.Deployment deployment = 2; - // Manual override for execution's versioning behavior. Takes precedence over `behavior` - // and `deployment`. - VersioningBehaviorOverride manual_override = 3; + // 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 redirect can only exist during the lifetime of a pending workflow task. // If the pending workflow task completes (at the next WorkflowTaskCompleted event), the @@ -362,15 +362,16 @@ message NexusOperationCancellationInfo { } message WorkflowExecutionOptions { - // If set, takes precedence over the sdk-sent Versioning Behavior for the specific Workflow Execution it is set on. - VersioningBehaviorOverride versioning_behavior_override = 1; + // 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 manually override the versioning behavior of a specific workflow execution. If set, takes // precedence over the SDK-sent Versioning Behavior. // To remove the override, call `UpdateWorkflowExecutionOptions` with a null // `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. -message VersioningBehaviorOverride { +message VersioningOverride { // Required. temporal.api.enums.v1.VersioningBehavior behavior = 1; diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index c4b3f24f..2bf5b898 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1780,7 +1780,8 @@ message SetCurrentDeploymentRequest { } message SetCurrentDeploymentResponse { - deployment.v1.DeploymentInfo current_deployment = 1; + deployment.v1.DeploymentInfo current_deployment_info = 1; + deployment.v1.DeploymentInfo previous_current_deployment_info = 2; } // Returns the Current Deployment of a deployment series. diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index d14593e8..f3f2b315 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -773,6 +773,7 @@ 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}" @@ -784,6 +785,7 @@ service WorkflowService { // 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" @@ -796,6 +798,10 @@ service WorkflowService { // 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" @@ -806,6 +812,7 @@ service WorkflowService { } // 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}" @@ -817,6 +824,7 @@ service WorkflowService { // 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}" From d3bd873438e5fecfe3d75c22abb638ed95af6f95 Mon Sep 17 00:00:00 2001 From: ShahabT Date: Tue, 19 Nov 2024 14:15:07 -0800 Subject: [PATCH 5/6] Addressed feedback --- openapi/openapiv2.json | 146 +++++++++--------- openapi/openapiv3.yaml | 118 +++++++++----- temporal/api/deployment/v1/message.proto | 38 +++-- temporal/api/enums/v1/deployment.proto | 17 -- temporal/api/enums/v1/workflow.proto | 19 ++- .../workflowservice/v1/request_response.proto | 29 ++-- 6 files changed, 214 insertions(+), 153 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 028cfe44..bb9f231c 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -774,6 +774,7 @@ }, { "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" @@ -908,12 +909,14 @@ }, { "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" @@ -951,12 +954,14 @@ }, { "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" @@ -3648,6 +3653,7 @@ }, { "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" @@ -3782,12 +3788,14 @@ }, { "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" @@ -3825,12 +3833,14 @@ }, { "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" @@ -5947,10 +5957,11 @@ "type": "object", "properties": { "buildId": { - "type": "string" + "type": "string", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges." } }, - "description": "Identifies a worker deployment. A worker deployment is identified by the combination of\nseries name + build ID. Both values are required." + "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", @@ -6578,36 +6589,6 @@ }, "description": "The client request that triggers a Workflow Update." }, - "deploymentv1DeploymentInfo": { - "type": "object", - "properties": { - "deployment": { - "$ref": "#/definitions/v1Deployment" - }, - "status": { - "$ref": "#/definitions/v1DeploymentStatus" - }, - "lastBecameCurrentTime": { - "type": "string", - "format": "date-time" - }, - "metadata": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "A user-defined set of key-values. Can be updated as part of write operations to the\ndeployment, such as `SetCurrentDeployment`." - }, - "taskQueueInfos": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/DeploymentInfoTaskQueueInfo" - } - } - }, - "description": "Holds information about a worker deployment." - }, "protobufAny": { "type": "object", "properties": { @@ -7898,13 +7879,63 @@ "type": "object", "properties": { "seriesName": { - "type": "string" + "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" + "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": "Identifies a worker deployment. A worker deployment is identified by the combination of\nseries name + build ID. Both values are required." + "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", @@ -7917,17 +7948,6 @@ "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." }, - "v1DeploymentStatus": { - "type": "string", - "enum": [ - "DEPLOYMENT_STATUS_UNSPECIFIED", - "DEPLOYMENT_STATUS_NO_STATUS", - "DEPLOYMENT_STATUS_RAMPING", - "DEPLOYMENT_STATUS_CURRENT" - ], - "default": "DEPLOYMENT_STATUS_UNSPECIFIED", - "description": "Status of a deployment within its deployment series. Any given deployment series can at most have\none `RAMPING` deployment, and one `CURRENT` deployment.\n\n\n - DEPLOYMENT_STATUS_UNSPECIFIED: Status of the deployment is not specified.\n - DEPLOYMENT_STATUS_NO_STATUS: The deployment does not have a special status.\n - DEPLOYMENT_STATUS_RAMPING: The deployment is the ramping deployment for the deployment series.\n - DEPLOYMENT_STATUS_CURRENT: The deployment is the current deployment for the deployment series." - }, "v1DeprecateNamespaceResponse": { "type": "object", "description": "Deprecated." @@ -7986,7 +8006,7 @@ "type": "object", "properties": { "deploymentInfo": { - "$ref": "#/definitions/deploymentv1DeploymentInfo" + "$ref": "#/definitions/v1DeploymentInfo" } } }, @@ -8392,7 +8412,7 @@ "type": "object", "properties": { "currentDeploymentInfo": { - "$ref": "#/definitions/deploymentv1DeploymentInfo" + "$ref": "#/definitions/v1DeploymentInfo" } } }, @@ -8400,7 +8420,7 @@ "type": "object", "properties": { "deploymentInfo": { - "$ref": "#/definitions/deploymentv1DeploymentInfo" + "$ref": "#/definitions/v1DeploymentInfo" }, "reachability": { "$ref": "#/definitions/v1DeploymentReachability" @@ -8956,26 +8976,11 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/v1ListDeploymentsResponseDeploymentInfo" + "$ref": "#/definitions/v1DeploymentListInfo" } } } }, - "v1ListDeploymentsResponseDeploymentInfo": { - "type": "object", - "properties": { - "deployment": { - "$ref": "#/definitions/v1Deployment" - }, - "status": { - "$ref": "#/definitions/v1DeploymentStatus" - }, - "statusChangeTime": { - "type": "string", - "format": "date-time" - } - } - }, "v1ListNamespacesResponse": { "type": "object", "properties": { @@ -11097,10 +11102,11 @@ "type": "object", "properties": { "currentDeploymentInfo": { - "$ref": "#/definitions/deploymentv1DeploymentInfo" + "$ref": "#/definitions/v1DeploymentInfo" }, - "previousCurrentDeploymentInfo": { - "$ref": "#/definitions/deploymentv1DeploymentInfo" + "previousDeploymentInfo": { + "$ref": "#/definitions/v1DeploymentInfo", + "description": "Info of the deployment that was current before executing this operation." } } }, @@ -12074,7 +12080,7 @@ "upsertEntries": { "type": "object", "additionalProperties": { - "type": "string" + "$ref": "#/definitions/v1Payload" } }, "removeEntries": { @@ -12312,7 +12318,7 @@ "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 `UpdateWorkflowOptions` 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." }, "v1VersioningOverride": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index dd4d1b8d..18b8586a 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -775,10 +775,19 @@ paths: 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: @@ -825,10 +834,19 @@ paths: 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: @@ -3283,10 +3301,19 @@ paths: 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: @@ -3333,10 +3360,19 @@ paths: 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: @@ -5640,39 +5676,47 @@ components: 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: |- - Identifies a worker deployment. A worker deployment is identified by the combination of - series name + build ID. Both values are required. + `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' - status: - enum: - - DEPLOYMENT_STATUS_UNSPECIFIED - - DEPLOYMENT_STATUS_NO_STATUS - - DEPLOYMENT_STATUS_RAMPING - - DEPLOYMENT_STATUS_CURRENT - type: string - format: enum - lastBecameCurrentTime: + createTime: type: string format: date-time + taskQueueInfos: + type: array + items: + $ref: '#/components/schemas/DeploymentInfo_TaskQueueInfo' metadata: type: object additionalProperties: - type: string + $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`. - taskQueueInfos: - type: array - items: - $ref: '#/components/schemas/DeploymentInfo_TaskQueueInfo' - description: Holds information about a worker deployment. + 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: @@ -5690,6 +5734,20 @@ components: 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: @@ -6603,23 +6661,7 @@ components: deployments: type: array items: - $ref: '#/components/schemas/ListDeploymentsResponse_DeploymentInfo' - ListDeploymentsResponse_DeploymentInfo: - type: object - properties: - deployment: - $ref: '#/components/schemas/Deployment' - status: - enum: - - DEPLOYMENT_STATUS_UNSPECIFIED - - DEPLOYMENT_STATUS_NO_STATUS - - DEPLOYMENT_STATUS_RAMPING - - DEPLOYMENT_STATUS_CURRENT - type: string - format: enum - statusChangeTime: - type: string - format: date-time + $ref: '#/components/schemas/DeploymentListInfo' ListNamespacesResponse: type: object properties: @@ -8444,8 +8486,10 @@ components: properties: currentDeploymentInfo: $ref: '#/components/schemas/DeploymentInfo' - previousCurrentDeploymentInfo: - $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: @@ -9358,7 +9402,7 @@ components: upsertEntries: type: object additionalProperties: - type: string + $ref: '#/components/schemas/Payload' removeEntries: type: array items: diff --git a/temporal/api/deployment/v1/message.proto b/temporal/api/deployment/v1/message.proto index 2005638b..4d6ce823 100644 --- a/temporal/api/deployment/v1/message.proto +++ b/temporal/api/deployment/v1/message.proto @@ -33,25 +33,36 @@ option csharp_namespace = "Temporalio.Api.Deployment.V1"; import "google/protobuf/timestamp.proto"; -import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/task_queue.proto"; +import "temporal/api/common/v1/message.proto"; -// Identifies a worker deployment. A worker deployment is identified by the combination of -// series name + build ID. Both values are required. +// `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; } -// Holds information about a worker deployment. +// `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; - temporal.api.enums.v1.DeploymentStatus status = 2; - google.protobuf.Timestamp last_became_current_time = 3; + 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; - repeated TaskQueueInfo task_queue_infos = 5; + map metadata = 4; + // If this deployment is the current deployment of its deployment series. + bool is_current = 5; message TaskQueueInfo { string name = 1; @@ -63,7 +74,16 @@ message DeploymentInfo { // Used as part of Deployment write APIs to update metadata attached to a deployment. message UpdateDeploymentMetadata { - map upsert_entries = 1; + 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 index 35da02eb..005ba440 100644 --- a/temporal/api/enums/v1/deployment.proto +++ b/temporal/api/enums/v1/deployment.proto @@ -31,23 +31,6 @@ option java_outer_classname = "DeploymentProto"; option ruby_package = "Temporalio::Api::Enums::V1"; option csharp_namespace = "Temporalio.Api.Enums.V1"; -// Status of a deployment within its deployment series. Any given deployment series can at most have -// one `RAMPING` deployment, and one `CURRENT` deployment. -// -// (-- api-linter: core::0216::synonyms=disabled -// aip.dev/not-precedent: This enum specifies the status of the deployment among all deployments -// in the same series, therefore `DeploymentStatus` is a better name that `DeploymentState`. --) -enum DeploymentStatus { - // Status of the deployment is not specified. - DEPLOYMENT_STATUS_UNSPECIFIED = 0; - // The deployment does not have a special status. - DEPLOYMENT_STATUS_NO_STATUS = 1; - // The deployment is the ramping deployment for the deployment series. - DEPLOYMENT_STATUS_RAMPING = 2; - // The deployment is the current deployment for the deployment series. - DEPLOYMENT_STATUS_CURRENT = 3; -} - // Specify the reachability level for a deployment so users can decide if it is time to // decommission the deployment. enum DeploymentReachability { diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index 4d8ca8cb..b1ff8266 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 `UpdateWorkflowOptions` 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/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 2bf5b898..51f3364b 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1750,38 +1750,33 @@ message DescribeDeploymentResponse { } message ListDeploymentsRequest { - int32 page_size = 1; - bytes next_page_token = 2; - string namespace = 3; + 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 DeploymentInfo deployments = 2; - - message DeploymentInfo { - deployment.v1.Deployment deployment = 1; - enums.v1.DeploymentStatus status = 2; - google.protobuf.Timestamp status_change_time = 3; - } + repeated temporal.api.deployment.v1.DeploymentListInfo deployments = 2; } message SetCurrentDeploymentRequest { string namespace = 1; - deployment.v1.Deployment deployment = 2; + 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. - deployment.v1.UpdateDeploymentMetadata update_metadata = 4; + temporal.api.deployment.v1.UpdateDeploymentMetadata update_metadata = 4; } message SetCurrentDeploymentResponse { - deployment.v1.DeploymentInfo current_deployment_info = 1; - deployment.v1.DeploymentInfo previous_current_deployment_info = 2; + 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. @@ -1791,16 +1786,16 @@ message GetCurrentDeploymentRequest { } message GetCurrentDeploymentResponse { - deployment.v1.DeploymentInfo current_deployment_info = 1; + temporal.api.deployment.v1.DeploymentInfo current_deployment_info = 1; } message GetDeploymentReachabilityRequest { string namespace = 1; - deployment.v1.Deployment deployment = 2; + temporal.api.deployment.v1.Deployment deployment = 2; } message GetDeploymentReachabilityResponse { - deployment.v1.DeploymentInfo deployment_info = 1; + 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. From 6421777ef8142a9dec86b7023386abb2eeb97eae Mon Sep 17 00:00:00 2001 From: ShahabT Date: Tue, 19 Nov 2024 15:23:37 -0800 Subject: [PATCH 6/6] improve VersioningOverride comments --- openapi/openapiv2.json | 4 ++-- openapi/openapiv3.yaml | 8 ++++---- temporal/api/enums/v1/workflow.proto | 2 +- temporal/api/workflow/v1/message.proto | 8 ++++---- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index bb9f231c..2e497559 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -12318,7 +12318,7 @@ "VERSIONING_BEHAVIOR_AUTO_UPGRADE" ], "default": "VERSIONING_BEHAVIOR_UNSPECIFIED", - "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 `UpdateWorkflowOptions` 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." + "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." }, "v1VersioningOverride": { "type": "object", @@ -12332,7 +12332,7 @@ "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 to manually override the versioning behavior of a specific workflow execution. If set, takes\nprecedence over the SDK-sent Versioning Behavior.\nTo remove the override, call `UpdateWorkflowExecutionOptions` with a null\n`VersioningBehaviorOverride`, and use the `update_mask` 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", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 18b8586a..dd623386 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -9718,10 +9718,10 @@ components: 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 manually override the versioning behavior of a specific workflow execution. If set, takes - precedence over the SDK-sent Versioning Behavior. - To remove the override, call `UpdateWorkflowExecutionOptions` with a null - `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. + 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: diff --git a/temporal/api/enums/v1/workflow.proto b/temporal/api/enums/v1/workflow.proto index b1ff8266..97cb47e3 100644 --- a/temporal/api/enums/v1/workflow.proto +++ b/temporal/api/enums/v1/workflow.proto @@ -144,7 +144,7 @@ enum VersioningBehavior { // to any worker who is polling for the task queue. VERSIONING_BEHAVIOR_UNSPECIFIED = 0; // Workflow should be pinned to the current deployment until completion. Can still be moved - // explicitly via `UpdateWorkflowOptions` API. + // 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. diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index bd827181..4d142eae 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -367,10 +367,10 @@ message WorkflowExecutionOptions { VersioningOverride versioning_override = 1; } -// Used to manually override the versioning behavior of a specific workflow execution. If set, takes -// precedence over the SDK-sent Versioning Behavior. -// To remove the override, call `UpdateWorkflowExecutionOptions` with a null -// `VersioningBehaviorOverride`, and use the `update_mask` to indicate that it should be mutated. +// 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;