Skip to content

Commit 0286a69

Browse files
carlydfcarlydf
authored
add ManagerIdentity field to WorkerDeployment, and API to set/unset (#632)
_**READ BEFORE MERGING:** All PRs require approval by both Server AND SDK teams before merging! This is why the number of required approvals is "2" and not "1"--two reviewers from the same team is NOT sufficient. If your PR is not approved by someone in BOTH teams, it may be summarily reverted._ <!-- Tell your future self why have you made these changes --> I want the Worker Controller to stop making changes to a Worker Deployment if it detects that another client has written to the same Worker Deployment. This is so that, if a user calls `SetCurrentVersion` or `SetRampingVersion` from the CLI during an incident, the Controller does not overwrite that change. `LastModifiedBy` is not enough for this feature, because we need a way for the "other client" (likely user CLI in most cases, maybe UI if we allow such changes through the UI some day) to indicate to the controller that manual changes are no longer needed and the controller can safely take ownership over writing to this Worker Deployment again. I thought about doing this via a `Metadata` on the Deployment, similar to WorkerDeploymentVersion Metadata, but I can't think of any other use cases for Deployment-level metadata, and I think this is load-bearing enough to deserve it's own field, where we can clearly document semantics. <!-- Are there any breaking changes on binary or code level? --> No <!-- If this breaks the Server, please provide the Server PR to merge right after this PR was merged. --> Not implemented in server yet because this is just a proposal
1 parent 21b27ff commit 0286a69

File tree

5 files changed

+306
-0
lines changed

5 files changed

+306
-0
lines changed

‎openapi/openapiv2.json‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2130,6 +2130,51 @@
21302130
]
21312131
}
21322132
},
2133+
"/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-manager": {
2134+
"post": {
2135+
"summary": "Set/unset the ManagerIdentity of a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.",
2136+
"operationId": "SetWorkerDeploymentManager2",
2137+
"responses": {
2138+
"200": {
2139+
"description": "A successful response.",
2140+
"schema": {
2141+
"$ref": "#/definitions/v1SetWorkerDeploymentManagerResponse"
2142+
}
2143+
},
2144+
"default": {
2145+
"description": "An unexpected error response.",
2146+
"schema": {
2147+
"$ref": "#/definitions/rpcStatus"
2148+
}
2149+
}
2150+
},
2151+
"parameters": [
2152+
{
2153+
"name": "namespace",
2154+
"in": "path",
2155+
"required": true,
2156+
"type": "string"
2157+
},
2158+
{
2159+
"name": "deploymentName",
2160+
"in": "path",
2161+
"required": true,
2162+
"type": "string"
2163+
},
2164+
{
2165+
"name": "body",
2166+
"in": "body",
2167+
"required": true,
2168+
"schema": {
2169+
"$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentManagerBody"
2170+
}
2171+
}
2172+
],
2173+
"tags": [
2174+
"WorkflowService"
2175+
]
2176+
}
2177+
},
21332178
"/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": {
21342179
"post": {
21352180
"summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.",
@@ -5910,6 +5955,51 @@
59105955
]
59115956
}
59125957
},
5958+
"/namespaces/{namespace}/worker-deployments/{deploymentName}/set-manager": {
5959+
"post": {
5960+
"summary": "Set/unset the ManagerIdentity of a Worker Deployment.\nExperimental. This API might significantly change or be removed in a future release.",
5961+
"operationId": "SetWorkerDeploymentManager",
5962+
"responses": {
5963+
"200": {
5964+
"description": "A successful response.",
5965+
"schema": {
5966+
"$ref": "#/definitions/v1SetWorkerDeploymentManagerResponse"
5967+
}
5968+
},
5969+
"default": {
5970+
"description": "An unexpected error response.",
5971+
"schema": {
5972+
"$ref": "#/definitions/rpcStatus"
5973+
}
5974+
}
5975+
},
5976+
"parameters": [
5977+
{
5978+
"name": "namespace",
5979+
"in": "path",
5980+
"required": true,
5981+
"type": "string"
5982+
},
5983+
{
5984+
"name": "deploymentName",
5985+
"in": "path",
5986+
"required": true,
5987+
"type": "string"
5988+
},
5989+
{
5990+
"name": "body",
5991+
"in": "body",
5992+
"required": true,
5993+
"schema": {
5994+
"$ref": "#/definitions/WorkflowServiceSetWorkerDeploymentManagerBody"
5995+
}
5996+
}
5997+
],
5998+
"tags": [
5999+
"WorkflowService"
6000+
]
6001+
}
6002+
},
59136003
"/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version": {
59146004
"post": {
59156005
"summary": "Set/unset the Ramping Version of a Worker Deployment and its ramp percentage. Can be used for\ngradual ramp to unversioned workers too.\nExperimental. This API might significantly change or be removed in a future release.",
@@ -8400,6 +8490,29 @@
84008490
},
84018491
"description": "Set/unset the Current Version of a Worker Deployment."
84028492
},
8493+
"WorkflowServiceSetWorkerDeploymentManagerBody": {
8494+
"type": "object",
8495+
"properties": {
8496+
"managerIdentity": {
8497+
"type": "string",
8498+
"description": "Arbitrary value for `manager_identity`.\nEmpty will unset the field."
8499+
},
8500+
"self": {
8501+
"type": "boolean",
8502+
"description": "True will set `manager_identity` to `identity`."
8503+
},
8504+
"conflictToken": {
8505+
"type": "string",
8506+
"format": "byte",
8507+
"description": "Optional. This can be the value of conflict_token from a Describe, or another Worker\nDeployment API. Passing a non-nil conflict token will cause this request to fail if the\nDeployment's configuration has been modified between the API call that generated the\ntoken and this one."
8508+
},
8509+
"identity": {
8510+
"type": "string",
8511+
"description": "Required. The identity of the client who initiated this request."
8512+
}
8513+
},
8514+
"description": "Update the ManagerIdentity of a Worker Deployment."
8515+
},
84038516
"WorkflowServiceSetWorkerDeploymentRampingVersionBody": {
84048517
"type": "object",
84058518
"properties": {
@@ -14449,6 +14562,20 @@
1444914562
}
1445014563
}
1445114564
},
14565+
"v1SetWorkerDeploymentManagerResponse": {
14566+
"type": "object",
14567+
"properties": {
14568+
"conflictToken": {
14569+
"type": "string",
14570+
"format": "byte",
14571+
"description": "This value is returned so that it can be optionally passed to APIs\nthat write to the Worker Deployment state to ensure that the state\ndid not change between this API call and a future write."
14572+
},
14573+
"previousManagerIdentity": {
14574+
"type": "string",
14575+
"description": "What the `manager_identity` field was before this change."
14576+
}
14577+
}
14578+
},
1445214579
"v1SetWorkerDeploymentRampingVersionResponse": {
1445314580
"type": "object",
1445414581
"properties": {
@@ -15918,6 +16045,10 @@
1591816045
"lastModifierIdentity": {
1591916046
"type": "string",
1592016047
"description": "Identity of the last client who modified the configuration of this Deployment. Set to the\n`identity` value sent by APIs such as `SetWorkerDeploymentCurrentVersion` and\n`SetWorkerDeploymentRampingVersion`."
16048+
},
16049+
"managerIdentity": {
16050+
"type": "string",
16051+
"description": "Identity of the client that has the exclusive right to make changes to this Worker Deployment.\nEmpty by default.\nIf this is set, clients whose identity does not match `manager_identity` will not be able to make changes\nto this Worker Deployment. They can either set their own identity as the manager or unset the field to proceed."
1592116052
}
1592216053
},
1592316054
"description": "A Worker Deployment (Deployment, for short) represents all workers serving \na shared set of Task Queues. Typically, a Deployment represents one service or \napplication.\nA Deployment contains multiple Deployment Versions, each representing a different \nversion of workers. (see documentation of WorkerDeploymentVersionInfo)\nDeployment records are created in Temporal server automatically when their\nfirst poller arrives to the server.\nExperimental. Worker Deployments are experimental and might significantly change in the future."

‎openapi/openapiv3.yaml‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1914,6 +1914,44 @@ paths:
19141914
application/json:
19151915
schema:
19161916
$ref: '#/components/schemas/Status'
1917+
/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-manager:
1918+
post:
1919+
tags:
1920+
- WorkflowService
1921+
description: |-
1922+
Set/unset the ManagerIdentity of a Worker Deployment.
1923+
Experimental. This API might significantly change or be removed in a future release.
1924+
operationId: SetWorkerDeploymentManager
1925+
parameters:
1926+
- name: namespace
1927+
in: path
1928+
required: true
1929+
schema:
1930+
type: string
1931+
- name: deploymentName
1932+
in: path
1933+
required: true
1934+
schema:
1935+
type: string
1936+
requestBody:
1937+
content:
1938+
application/json:
1939+
schema:
1940+
$ref: '#/components/schemas/SetWorkerDeploymentManagerRequest'
1941+
required: true
1942+
responses:
1943+
"200":
1944+
description: OK
1945+
content:
1946+
application/json:
1947+
schema:
1948+
$ref: '#/components/schemas/SetWorkerDeploymentManagerResponse'
1949+
default:
1950+
description: Default error response
1951+
content:
1952+
application/json:
1953+
schema:
1954+
$ref: '#/components/schemas/Status'
19171955
/api/v1/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version:
19181956
post:
19191957
tags:
@@ -5297,6 +5335,44 @@ paths:
52975335
application/json:
52985336
schema:
52995337
$ref: '#/components/schemas/Status'
5338+
/namespaces/{namespace}/worker-deployments/{deploymentName}/set-manager:
5339+
post:
5340+
tags:
5341+
- WorkflowService
5342+
description: |-
5343+
Set/unset the ManagerIdentity of a Worker Deployment.
5344+
Experimental. This API might significantly change or be removed in a future release.
5345+
operationId: SetWorkerDeploymentManager
5346+
parameters:
5347+
- name: namespace
5348+
in: path
5349+
required: true
5350+
schema:
5351+
type: string
5352+
- name: deploymentName
5353+
in: path
5354+
required: true
5355+
schema:
5356+
type: string
5357+
requestBody:
5358+
content:
5359+
application/json:
5360+
schema:
5361+
$ref: '#/components/schemas/SetWorkerDeploymentManagerRequest'
5362+
required: true
5363+
responses:
5364+
"200":
5365+
description: OK
5366+
content:
5367+
application/json:
5368+
schema:
5369+
$ref: '#/components/schemas/SetWorkerDeploymentManagerResponse'
5370+
default:
5371+
description: Default error response
5372+
content:
5373+
application/json:
5374+
schema:
5375+
$ref: '#/components/schemas/Status'
53005376
/namespaces/{namespace}/worker-deployments/{deploymentName}/set-ramping-version:
53015377
post:
53025378
tags:
@@ -11447,6 +11523,46 @@ components:
1144711523
allOf:
1144811524
- $ref: '#/components/schemas/WorkerDeploymentVersion'
1144911525
description: The version that was current before executing this operation.
11526+
SetWorkerDeploymentManagerRequest:
11527+
type: object
11528+
properties:
11529+
namespace:
11530+
type: string
11531+
deploymentName:
11532+
type: string
11533+
managerIdentity:
11534+
type: string
11535+
description: |-
11536+
Arbitrary value for `manager_identity`.
11537+
Empty will unset the field.
11538+
self:
11539+
type: boolean
11540+
description: True will set `manager_identity` to `identity`.
11541+
conflictToken:
11542+
type: string
11543+
description: |-
11544+
Optional. This can be the value of conflict_token from a Describe, or another Worker
11545+
Deployment API. Passing a non-nil conflict token will cause this request to fail if the
11546+
Deployment's configuration has been modified between the API call that generated the
11547+
token and this one.
11548+
format: bytes
11549+
identity:
11550+
type: string
11551+
description: Required. The identity of the client who initiated this request.
11552+
description: Update the ManagerIdentity of a Worker Deployment.
11553+
SetWorkerDeploymentManagerResponse:
11554+
type: object
11555+
properties:
11556+
conflictToken:
11557+
type: string
11558+
description: |-
11559+
This value is returned so that it can be optionally passed to APIs
11560+
that write to the Worker Deployment state to ensure that the state
11561+
did not change between this API call and a future write.
11562+
format: bytes
11563+
previousManagerIdentity:
11564+
type: string
11565+
description: What the `manager_identity` field was before this change.
1145011566
SetWorkerDeploymentRampingVersionRequest:
1145111567
type: object
1145211568
properties:
@@ -13184,6 +13300,13 @@ components:
1318413300
Identity of the last client who modified the configuration of this Deployment. Set to the
1318513301
`identity` value sent by APIs such as `SetWorkerDeploymentCurrentVersion` and
1318613302
`SetWorkerDeploymentRampingVersion`.
13303+
managerIdentity:
13304+
type: string
13305+
description: |-
13306+
Identity of the client that has the exclusive right to make changes to this Worker Deployment.
13307+
Empty by default.
13308+
If this is set, clients whose identity does not match `manager_identity` will not be able to make changes
13309+
to this Worker Deployment. They can either set their own identity as the manager or unset the field to proceed.
1318713310
description: "A Worker Deployment (Deployment, for short) represents all workers serving \n a shared set of Task Queues. Typically, a Deployment represents one service or \n application.\n A Deployment contains multiple Deployment Versions, each representing a different \n version of workers. (see documentation of WorkerDeploymentVersionInfo)\n Deployment records are created in Temporal server automatically when their\n first poller arrives to the server.\n Experimental. Worker Deployments are experimental and might significantly change in the future."
1318813311
WorkerDeploymentInfo_WorkerDeploymentVersionSummary:
1318913312
type: object

‎temporal/api/deployment/v1/message.proto‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,12 @@ message WorkerDeploymentInfo {
195195
// `SetWorkerDeploymentRampingVersion`.
196196
string last_modifier_identity = 5;
197197

198+
// Identity of the client that has the exclusive right to make changes to this Worker Deployment.
199+
// Empty by default.
200+
// If this is set, clients whose identity does not match `manager_identity` will not be able to make changes
201+
// to this Worker Deployment. They can either set their own identity as the manager or unset the field to proceed.
202+
string manager_identity = 6;
203+
198204
message WorkerDeploymentVersionSummary {
199205
// Deprecated. Use `deployment_version`.
200206
string version = 1 [deprecated = true];

‎temporal/api/workflowservice/v1/request_response.proto‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2319,6 +2319,39 @@ message UpdateWorkerDeploymentVersionMetadataResponse {
23192319
temporal.api.deployment.v1.VersionMetadata metadata = 1;
23202320
}
23212321

2322+
// Update the ManagerIdentity of a Worker Deployment.
2323+
message SetWorkerDeploymentManagerRequest {
2324+
string namespace = 1;
2325+
string deployment_name = 2;
2326+
2327+
oneof new_manager_identity {
2328+
// Arbitrary value for `manager_identity`.
2329+
// Empty will unset the field.
2330+
string manager_identity = 3;
2331+
2332+
// True will set `manager_identity` to `identity`.
2333+
bool self = 4;
2334+
}
2335+
2336+
// Optional. This can be the value of conflict_token from a Describe, or another Worker
2337+
// Deployment API. Passing a non-nil conflict token will cause this request to fail if the
2338+
// Deployment's configuration has been modified between the API call that generated the
2339+
// token and this one.
2340+
bytes conflict_token = 5;
2341+
2342+
// Required. The identity of the client who initiated this request.
2343+
string identity = 6;
2344+
}
2345+
2346+
message SetWorkerDeploymentManagerResponse {
2347+
// This value is returned so that it can be optionally passed to APIs
2348+
// that write to the Worker Deployment state to ensure that the state
2349+
// did not change between this API call and a future write.
2350+
bytes conflict_token = 1;
2351+
2352+
// What the `manager_identity` field was before this change.
2353+
string previous_manager_identity = 2;
2354+
}
23222355

23232356
// Returns the Current Deployment of a deployment series.
23242357
// [cleanup-wv-pre-release] Pre-release deployment APIs, clean up later

‎temporal/api/workflowservice/v1/service.proto‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -923,6 +923,19 @@ service WorkflowService {
923923
};
924924
}
925925

926+
// Set/unset the ManagerIdentity of a Worker Deployment.
927+
// Experimental. This API might significantly change or be removed in a future release.
928+
rpc SetWorkerDeploymentManager (SetWorkerDeploymentManagerRequest) returns (SetWorkerDeploymentManagerResponse) {
929+
option (google.api.http) = {
930+
post: "/namespaces/{namespace}/worker-deployments/{deployment_name}/set-manager"
931+
body: "*"
932+
additional_bindings {
933+
post: "/api/v1/namespaces/{namespace}/worker-deployments/{deployment_name}/set-manager"
934+
body: "*"
935+
}
936+
};
937+
}
938+
926939
// Invokes the specified Update function on user Workflow code.
927940
rpc UpdateWorkflowExecution(UpdateWorkflowExecutionRequest) returns (UpdateWorkflowExecutionResponse) {
928941
option (google.api.http) = {

0 commit comments

Comments
 (0)