feat: add multi-tenancy docs for self-managed (#2727)

* Document multi-tenancy for Zeebe gRPC (#2696) * feat(apis-tools): document tenant-related grpc properties Document the tenantId and tenantIds properties in all of the gRPC request and response messages that were made tenant-aware. In some gRPC requests the tenantId property is not required as the tenant ownership of the data is already clear within Zeebe. * feat(apis-tools): document tenant-related grpc errors Document the multi-tenancy-related errors that may be produced by tenant-aware gRPC requests. * doc(api-tools): document multi-tenancy limiations of zeebe grpc spec Document the limitations of multi-tenancy in the Zeebe gRPC calls. Signals are not supported for non-<default> tenants, and resource deletion is not tenant-aware, meaning that it can delete any resource no matter the tenant ownership. * doc(api-tools): multi-tenancy for deprecated rpc Document that for the deprecated DeployProcess RPC, when multi-tenancy is enabled, any deployments are owned by the <default> tenant. Deploying to other tenants through this RPC is not possible since it's deprecated and no new behaviors are added. * fix(grpc): correct multi-tenancy support note for deletion Correct the note on multi-tenancy support for resource deletion in the gRPC documentation. Resource deletion is only supported for the <default> tenant. * docs(identity): introduce Identity specific documentation relating to multi tenancy (#2713) * docs(identity): introduce Identity specific documentation relating to multi tenancy * style(formatting): technical review * docs(identity): PR comments --------- Co-authored-by: Christina Ausley <[email protected]> * Add multi-tenancy config docs for Connectors * chore(multiTenancy): document C8SM multi tenancy feature for Optimize related to OPT-7250 * feat: add multi tenancy section to Job Worker This commit adds a section about multi-tenancy in Job workers and how to configure them. It also includes some small code examples to guide users during implementation. Co-authored-by: Christina Ausley <[email protected]> * chore(version-8.3): backport multi-tenancy changes * revert: remove mt sidebar changes The conceptual multi-tenancy docs haven't been added yet, so we shouldn't link to them from the sidebar. * docs(MT:tasklist): document MT-related changes for Tasklist (#2730) * docs(MT:tasklist): document MT-related changes for Tasklist * docs(MT:tasklist): port documentation for v`8.3` also * technical review --------- Co-authored-by: Christina Ausley <[email protected]> * Document multi-tenancy support for Zeebe (#2734) * doc(go-client): document multi-tenancy support for the go client Document that multi-tenancy is currently not supported for the go client. * doc(gateway): document multi-tenancy configuration for zeebe Document the configuration properties needed to enable multi-tenancy in Zeebe. * doc(update-guide): multi-tenancy adjustments on migration Document the impact of multi-tenancy when migrating from older versions of Zebe . * style(formatting): technical review * refactor: implement review hints * Add conceptual docs for multi-tenancy (#2735) * feat(self-managed): add conceptual docs on multi-tenancy * refactor: implement review hints --------- Co-authored-by: Christina Ausley <[email protected]> Co-authored-by: christinaausley <[email protected]> --------- Co-authored-by: Nikola Koevski <[email protected]> Co-authored-by: Ben Sheppard <[email protected]> Co-authored-by: Christina Ausley <[email protected]> Co-authored-by: Dmitriy Melnychuk <[email protected]> Co-authored-by: sbuettner <[email protected]> Co-authored-by: PHWaechtler <[email protected]> Co-authored-by: Remco <[email protected]> Co-authored-by: Dmitriy Melnychuk <[email protected]> Co-authored-by: christinaausley <[email protected]>
camunda · Oct 16, 2023 · c26d574 · c26d574
1 parent 3f58167
commit c26d574
Show file tree

Hide file tree

Showing 60 changed files with 1,021 additions and 22 deletions.
diff --git a/docs/apis-tools/go-client/go-get-started.md b/docs/apis-tools/go-client/go-get-started.md
@@ -11,6 +11,11 @@ In this tutorial, you will learn how to use the Go client in a Go application to
 
 You can find a complete example on [GitHub](https://github.com/camunda/camunda-platform-get-started/tree/main/go).
 
+:::note
+The Go client currently doesn't support multi-tenancy and can only be used when multi-tenancy is disabled. You can find
+more details on multi-tenancy [here](../../self-managed/concepts/multi-tenancy.md).
+:::
+
 ## Prerequisites
 
 - [Camunda 8 account](/guides/create-account.md)

diff --git a/docs/apis-tools/grpc.md b/docs/apis-tools/grpc.md
@@ -37,6 +37,8 @@ message ActivateJobsRequest {
   // if the requestTimeout = 0, a default timeout is used.
   // if the requestTimeout < 0, long polling is disabled and the request is completed immediately, even when no job is activated.
   int64 requestTimeout = 6;
+  // a list of tenant IDs for which to activate jobs
+  repeated string tenantIds = 7;
 }
 ```
 
@@ -78,6 +80,8 @@ message ActivatedJob {
   // JSON document, computed at activation time, consisting of all visible variables to
   // the task scope
   string variables = 13;
+  // the ID of the tenant that owns the job
+  string tenantId = 14;
 }
 ```
 
@@ -91,9 +95,23 @@ Returned if:
 - Worker is blank (empty string, null)
 - Timeout less than 1 (ms)
 - maxJobsToActivate is less than 1
+- If multi-tenancy is enabled, and `tenantIds` is empty (empty list)
+- If multi-tenancy is enabled, and an invalid tenant ID is provided. A tenant ID is considered invalid if:
+  - The tenant ID is blank (empty string, null)
+  - The tenant ID is longer than 31 characters
+  - The tenant ID contains anything other than alphanumeric characters, dot (.), dash (-), or underscore (\_)
+- If multi-tenancy is disabled, and `tenantIds` is not empty (empty list), or has an ID other than `<default>`
+
+##### GRPC_STATUS_PERMISSION_DENIED
+
+- If multi-tenancy is enabled, and an unauthorized tenant ID is provided
 
 ### `BroadcastSignal` RPC
 
+:::note
+When multi-tenancy is enabled, signals are only supported for the `<default>` tenant.
+:::
+
 Broadcasts a [signal](../components/concepts/signals.md).
 
 #### Input: `BroadcastSignalRequest`
@@ -146,6 +164,7 @@ message CancelProcessInstanceResponse {
 Returned if:
 
 - No process instance exists with the given key. Note that since process instances are removed once they are finished, it could mean the instance did exist at some point.
+- No process instance exists with the given key for the tenants the user is authorized to work with.
 
 ### `CompleteJob` RPC
 
@@ -176,6 +195,7 @@ message CompleteJobResponse {
 Returned if:
 
 - No job exists with the given job key. Note that since jobs are removed once completed, it could be that this job did exist at some point.
+- No job exists with the given job key for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_FAILED_PRECONDITION
 
@@ -215,6 +235,8 @@ message CreateProcessInstanceRequest {
   // will start at the start event. If non-empty the process instance will apply start
   // instructions after it has been created
   repeated ProcessInstanceCreationStartInstruction startInstructions = 5;
+  // the tenant ID of the process definition
+  string tenantId = 6;
 }
 
 message ProcessInstanceCreationStartInstruction {
@@ -245,6 +267,8 @@ message CreateProcessInstanceResponse {
   // the unique identifier of the created process instance; to be used wherever a request
   // needs a process instance key (e.g. CancelProcessInstanceRequest)
   int64 processInstanceKey = 4;
+  // the tenant ID of the created process instance
+  string tenantId = 5;
 }
 ```
 
@@ -285,6 +309,8 @@ message CreateProcessInstanceResponse {
   int64 processInstanceKey = 4;
   // consisting of all visible variables to the root scope
   string variables = 5;
+  // the tenant ID of the process definition
+  string tenantId = 6;
 }
 ```
 
@@ -311,6 +337,16 @@ Returned if:
 
 - The given variables argument is not a valid JSON document; it is expected to be a valid
   JSON document where the root node is an object.
+- If multi-tenancy is enabled, and `tenantId` is blank (empty string, null)
+- If multi-tenancy is enabled, and an invalid tenant ID is provided. A tenant ID is considered invalid if:
+  - The tenant ID is blank (empty string, null)
+  - The tenant ID is longer than 31 characters
+  - The tenant ID contains anything other than alphanumeric characters, dot (.), dash (-), or underscore (\_)
+- If multi-tenancy is disabled, and `tenantId` is not blank (empty string, null), or has an ID other than `<default>`
+
+##### GRPC_STATUS_PERMISSION_DENIED
+
+- If multi-tenancy is enabled, and an unauthorized tenant ID is provided
 
 ### `EvaluateDecision` RPC
 
@@ -339,6 +375,8 @@ message EvaluateDecisionRequest {
   // [{ "a": 1, "b": 2 }] would not be a valid argument, as the root of the
   // JSON document is an array and not an object.
   string variables = 3;
+  // the tenant ID of the decision
+  string tenantId = 4;
 }
 ```
 
@@ -372,6 +410,8 @@ message EvaluateDecisionResponse {
   string failedDecisionId = 9;
   // an optional message describing why the decision which was evaluated failed
   string failureMessage = 10;
+  // the tenant ID of the evaluated decision
+  string tenantId = 11;
 }
 
 message EvaluatedDecision {
@@ -394,6 +434,8 @@ message EvaluatedDecision {
   repeated MatchedDecisionRule matchedRules = 7;
   // the decision inputs that were evaluated within this decision evaluation
   repeated EvaluatedDecisionInput evaluatedInputs = 8;
+  // the tenant ID of the evaluated decision
+  string tenantId = 9;
 }
 
 message EvaluatedDecisionInput {
@@ -433,6 +475,16 @@ Returned if:
 - No decision with the given key exists (if decisionKey was given).
 - No decision with the given decision ID exists (if decisionId was given).
 - Both decision ID and decision KEY were provided, or are missing.
+- If multi-tenancy is enabled, and `tenantId` is blank (empty string, null)
+- If multi-tenancy is enabled, and an invalid tenant ID is provided. A tenant ID is considered invalid if:
+  - The tenant ID is blank (empty string, null)
+  - The tenant ID is longer than 31 characters
+  - The tenant ID contains anything other than alphanumeric characters, dot (.), dash (-), or underscore (\_)
+- If multi-tenancy is disabled, and `tenantId` is not blank (empty string, null), or has an ID other than `<default>`
+
+##### GRPC_STATUS_PERMISSION_DENIED
+
+- If multi-tenancy is enabled, and an unauthorized tenant ID is provided
 
 ### `DeployResource` RPC
 
@@ -445,6 +497,8 @@ Note that this is an atomic call, i.e. either all resources are deployed, or non
 message DeployResourceRequest {
   // list of resources to deploy
   repeated Resource resources = 1;
+  // the tenant ID of the resources to deploy
+  string tenantId = 2;
 }
 
 message Resource {
@@ -463,6 +517,8 @@ message DeployResourceResponse {
   int64 key = 1;
   // a list of deployed resources, e.g. processes
   repeated Deployment deployments = 2;
+  // the tenant ID of the deployed resources
+  string tenantId = 3;
 }
 
 message Deployment {
@@ -490,6 +546,8 @@ message ProcessMetadata {
   // the resource name (see: ProcessRequestObject.name) from which this process was
   // parsed
   string resourceName = 4;
+  // the tenant ID of the deployed process
+  string tenantId = 5;
 }
 
 message DecisionMetadata {
@@ -509,6 +567,8 @@ message DecisionMetadata {
   // the assigned key of the decision requirements graph that this decision is
   // part of
   int64 decisionRequirementsKey = 6;
+  // the tenant ID of the deployed decision
+  string tenantId = 7;
 }
 
 message DecisionRequirementsMetadata {
@@ -525,6 +585,8 @@ message DecisionRequirementsMetadata {
   // the resource name (see: Resource.name) from which this decision
   // requirements was parsed
   string resourceName = 5;
+  // the tenant ID of the deployed decision requirements
+  string tenantId = 6;
 }
 
 message FormMetadata {
@@ -537,7 +599,7 @@ message FormMetadata {
   int64 formKey = 3;
   // the resource name
   string resourceName = 4;
-  // the tenant id of the deployed form
+  // the tenant ID of the deployed form
   string tenantId = 5;
 }
 ```
@@ -553,6 +615,18 @@ Returned if:
   - The resource type is not supported (e.g. supported resources include BPMN and DMN files)
   - The content is not deserializable (e.g. detected as BPMN, but it's broken XML)
   - The content is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
+- If multi-tenancy is enabled, and `tenantId` is blank (empty string, null)
+- If multi-tenancy is enabled, and a BPMM resource containing an element of type `SIGNAL` is deployed to a
+  tenant ID other than `<default>`
+- If multi-tenancy is enabled, and an invalid tenant ID is provided. A tenant ID is considered invalid if:
+  - The tenant ID is blank (empty string, null)
+  - The tenant ID is longer than 31 characters
+  - The tenant ID contains anything other than alphanumeric characters, dot (.), dash (-), or underscore (\_)
+- If multi-tenancy is disabled, and `tenantId` is not blank (empty string, null), or has an ID other than `<default>`
+
+##### GRPC_STATUS_PERMISSION_DENIED
+
+- If multi-tenancy is enabled, and an unauthorized tenant ID is provided
 
 ### `FailJob` RPC
 
@@ -598,6 +672,7 @@ message FailJobResponse {
 Returned if:
 
 - No job was found with the given key.
+- No job was found with the given key for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_FAILED_PRECONDITION
 
@@ -670,6 +745,7 @@ message ModifyProcessInstanceResponse {
 Returned if:
 
 - No process instance exists with the given key, or it is not active.
+- No process instance was found with the given key for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_INVALID_ARGUMENT
 
@@ -709,6 +785,8 @@ message PublishMessageRequest {
   // the message variables as a JSON document; to be valid, the root of the document must be an
   // object, e.g. { "a": "foo" }. [ "foo" ] would not be valid.
   string variables = 5;
+  // the tenant ID of the message
+  string tenantId = 6;
 }
 ```
 
@@ -718,6 +796,8 @@ message PublishMessageRequest {
 message PublishMessageResponse {
   // the unique ID of the message that was published
   int64 key = 1;
+  // the tenant ID of the message
+  string tenantId = 2;
 }
 ```
 
@@ -729,6 +809,19 @@ Returned if:
 
 - A message with the same ID was previously published (and is still alive).
 
+##### GRPC_STATUS_NOT_FOUND
+
+- If multi-tenancy is enabled, and `tenantId` is blank (empty string, null)
+- If multi-tenancy is enabled, and an invalid tenant ID is provided. A tenant ID is considered invalid if:
+  - The tenant ID is blank (empty string, null)
+  - The tenant ID is longer than 31 characters
+  - The tenant ID contains anything other than alphanumeric characters, dot (.), dash (-), or underscore (\_)
+- If multi-tenancy is disabled, and `tenantId` is not blank (empty string, null), or has an ID other than `<default>`
+
+##### GRPC_STATUS_PERMISSION_DENIED
+
+- If multi-tenancy is enabled, and an unauthorized tenant ID is provided
+
 ### `ResolveIncident` RPC
 
 Resolves a given incident. This simply marks the incident as resolved; most likely a call to
@@ -758,6 +851,7 @@ message ResolveIncidentResponse {
 Returned if:
 
 - No incident with the given key exists.
+- No incident with the given key was found for the tenants the user is authorized to work with.
 
 ### `SetVariables` RPC
 
@@ -801,6 +895,7 @@ message SetVariablesResponse {
 Returned if:
 
 - No element with the given `elementInstanceKey` exists.
+- No element with the given `elementInstanceKey` was found for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_INVALID_ARGUMENT
 
@@ -850,6 +945,7 @@ message ThrowErrorResponse {
 Returned if:
 
 - No job was found with the given key.
+- No job was found with the given key for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_FAILED_PRECONDITION
 
@@ -953,6 +1049,7 @@ message UpdateJobRetriesResponse {
 Returned if:
 
 - No job exists with the given key.
+- No job was found with the given key for the tenants the user is authorized to work with.
 
 ##### GRPC_STATUS_INVALID_ARGUMENT
 
@@ -962,6 +1059,10 @@ Returned if:
 
 ### `DeleteResource` RPC
 
+:::note
+When multi-tenancy is enabled, resources can only be deleted for the `<default>` tenant.
+:::
+
 #### Input `DeleteResourceRequest`
 
 ```protobuf
@@ -1034,6 +1135,10 @@ The following RPCs are exposed by the gateway service, but have been deprecated.
 Deprecated since 8, replaced by [DeployResource RPC](#deployresource-rpc).
 :::
 
+:::note
+When multi-tenancy is enabled, processes are always deployed to the `<default>` tenant.
+:::
+
 Deploys one or more processes to Zeebe. Note that this is an atomic call,
 i.e. either all processes are deployed, or none of them are.
 

diff --git a/docs/apis-tools/java-client/job-worker.md b/docs/apis-tools/java-client/job-worker.md
@@ -198,3 +198,41 @@ Since an activated job must now cross two network boundaries - from broker to ga
 We implemented a best-effort mechanism to detect such issues and make the job available again, but this is never guaranteed, as it's not always possible to accurately detect in time that a job did not make it (e.g. network time out, where the job may or may not have made it to the recipient). When this happens, the job will remain in limbo until it times out, at which point it can be pushed out again.
 
 To help ensure accurate detection of client shutdown, make sure to close your job workers gracefully when you're finished with them. This will in turn tell the gateway that the worker is gone, and will help prevent job loss.
+
+## Multi-tenancy
+
+You can configure a job worker to pick up jobs belonging to one or more tenants. When using the builder, you can configure
+the tenant(s) it works for.
+
+Alternatively, you can configure default tenant(s) on the client. If you configure a default, all job workers you open will work on jobs for the configured default tenants.
+
+:::note
+The client must be authorized for **all** the provided tenants. If it is not, the job worker will not work on any jobs.
+:::
+
+### Job worker builder
+
+Opening a job worker for a single tenant:
+
+```java
+client.newWorker()
+    .jobType("myJobType")
+    .handler(new MyJobTypeHandler())
+    .tenantId("myTenant")
+    .open();
+```
+
+Opening a job worker for multiple tenants:
+
+```java
+client.newWorker()
+    .jobType("myJobType")
+    .handler(new MyJobTypeHandler())
+    .tenantIds("myTenant", "myOtherTenant")
+    .open();
+```
+
+### Default tenant
+
+You can configure the default tenant(s) using environment variables or system properties. It's configured using
+`DEFAULT_JOB_WORKER_TENANT_IDS` or `zeebe.client.worker.tenantIds` respectively.