tms v2 docu improvements: common tenant + clusterSize details

guides/multitenancy/index.md

@@ -894,7 +894,7 @@ To help ensure that the generated SAP HANA tenant UUID is unique within a region
 like `prefix-${org}-${space}` in Cloud Foundry.
 
 :::warning Prefix is mandatory
-The <Config label="hana_tenant_prefix" keyDelim="/">cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix</Config> configuration is mandatory to ensure that the internal tenant `t0` is created with its own SAP HANA tenant.
+The <Config label="hana_tenant_prefix" keyDelim="/" keyOnly>cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix</Config> configuration is mandatory to ensure that the internal tenant `t0` is created with its own SAP HANA tenant.
 :::
 
 :::warning Length restriction
@@ -913,45 +913,52 @@ For **CAP Java** applications you need to set the same prefix in the <Config jav
     CDS_MULTITENANCY_HANAMTSERVICE_HANATENANTPREFIX: "some-prefix"
 ```
 
-##### Pass the SAP HANA Tenant ID with a Subscription
+##### Assign Many Tenant Containers to a Common SAP HANA Tenant
 
-**... in CAP Node.js**
-###### CAP Node.js
-If you want to control the ID of the SAP HANA tenant ID on your own, you can pass it as subscription payload as parameters, for example, using a handler for the [`SaasRegistryService`](./mtxs#put-tenant):
-```jsonc
-{
-  "subscribedTenantId": "t1",
-  "subscribedSubdomain": "subdomain1",
-  "eventType": "CREATE"
-  ...
-  "_": {
-	  "hdi": {
-	    "create": {
-	      "hana_tenant_id": "5b3c0699-1c65-4ec1-9a8e-b7cfc3cc15bc"
-	    }
-	  }
-  }
-}
-```
-The `hana_tenant_id` must be a valid UUID and must be unique per subscriber tenant. Specifying `hana_tenant_id` overrides the prefix settings mentioned earlier,
-except for the internal tenant `t0`. Also ensure that the ID is unique within a region.
+To group the tenant containers of many applications or microservices in a common HANA tenant, you need to make sure that the same SAP HANA tenant ID is used.
 
-![One HANA tenant for many applications](./assets/hana_tenants_for_many.drawio.svg)
+![One HANA tenant for many applications or microservices](./assets/hana_tenants_for_many.drawio.svg)
 
-**... in CAP Java**
-###### CAP Java
-To specify the ID of the SAP HANA tenant in **CAP Java** applications you can register a custom handler for the `before` phase of the `SUBSCRIBE` event that sets the `hana_tenant_id` within the provisioning parameters:
+**Option 1: Configure the same `hana_tenant_prefix`**
+: You can configure the same [`hana_tenant_prefix`](#mandatory-specify-a-unique-prefix-for-the-sap-hana-tenant-name) many applications or microservices. With that, the SAP HANA tenant ID is generated in the same way for each subscriber tenant.
 
-```java
-@Before
-public void beforeSubscription(SubscribeEventContext context) {
-    context.getOptions().put("provisioningParameters",
-        Collections.singletonMap("hana_tenant_id", "<ID>"));
-}
-```
-
-This will affect every new [tenant subscription](../../java/multitenancy.md#subscribe-tenant) and will set the specified SAP HANA tenant ID.
+**Option 2: Pass the SAP HANA Tenant ID with a Subscription**
 
+: **... in CAP Node.js**
+
+   If you want to control the ID of the SAP HANA tenant ID on your own, you can pass it as subscription payload as parameters, for example, using a handler for the [`SaasRegistryService`](./mtxs#put-tenant):
+   ```jsonc
+   {
+     "subscribedTenantId": "t1",
+     "subscribedSubdomain": "subdomain1",
+     "eventType": "CREATE"
+     ...
+     "_": {
+   	  "hdi": {
+   	    "create": {
+   	      "hana_tenant_id": "5b3c0699-1c65-4ec1-9a8e-b7cfc3cc15bc"
+   	    }
+   	  }
+     }
+   }
+   ```
+  The `hana_tenant_id` must be a valid UUID and must be unique per subscriber tenant. Specifying `hana_tenant_id` overrides    the prefix settings mentioned earlier,
+  except for the internal tenant `t0`. Also ensure that the ID is unique within a region.   
+
+:  **... in CAP Java**
+
+  To specify the ID of the SAP HANA tenant in **CAP Java** applications you can register a custom handler for the `before`    phase of the `SUBSCRIBE` event that sets the `hana_tenant_id` within the provisioning parameters:
+
+  ```java
+  @Before
+  public void beforeSubscription(SubscribeEventContext context) {
+      context.getOptions().put("provisioningParameters",
+          Collections.singletonMap("hana_tenant_id", "<ID>"));
+  }
+  ```
+
+  This will affect every new [tenant subscription](../../java/multitenancy.md#subscribe-tenant) and will set the specified SAP HANA tenant ID.
+
 <div id="tmscmk" />
 
 
@@ -965,8 +972,6 @@ There are still some limitations with the current client implementation.
 
 - **Database ID is Mandatory**
   As mentioned, you need to specify a database ID that's to be used, either for all tenants or per subscription request, see [Deployment configuration](./mtxs#deployment-config).
-- [`clusterSize` configuration](./mtxs#saas-provisioning-config) needs to be set to `1` (default is `3`). HANA TMS v2 does not provide a performant way to determine all database IDs,
-so clustering the upgrade by database does not work properly.
 
 
 ## SaaS Dependencies {#saas-dependencies}

guides/multitenancy/mtxs.md

@@ -1308,6 +1308,11 @@ The _SaasProvisioningService_ is a façade for the _DeploymentService_ to adapt
   - `clusterSize` — max number of database clusters, running `workerSize` jobs each
   - `queueSize` — max number of jobs waiting to run in the job queue
 
+:::warning clusterSize configuration is not available with HANA TMS v2
+When using [HANA TMS v2](../multitenancy/index.md#sap-hana-tms-v2), the <Config label="`clusterSize` configuration" keyDelim="/" keyOnly>cds/requires/cds.xt.SaasProvisioningService/jobs/clusterSize</Config> is automatically set to `1`. HANA TMS v2 currently does not
+ provide a performant way to determine all database IDs, so clustering the upgrade by database does not work properly.
+:::
+
 #### HTTP Request Options
 
 | Request Header        |  Example Value                                         | Description  |