From 74d9c83aaf80c8316deac0da5ab03d759f2e31d8 Mon Sep 17 00:00:00 2001
From: Eckart Liemke <eckart.liemke@sap.com>
Date: Wed, 8 Jul 2026 15:10:30 +0200
Subject: [PATCH 1/2] tms v2 docu improvements: common tenant + clusterSize
 details

---
 guides/multitenancy/index.md | 21 +++++++++++++++------
 guides/multitenancy/mtxs.md  |  5 +++++
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md
index 173d8eed7..c490176ba 100644
--- a/guides/multitenancy/index.md
+++ b/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,7 +913,20 @@ 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 HANA tenant
+
+To group the tenant containers of many applications or microservices in a common HANA tenant, you need to make sure that the same
+HANA tenant id is used.
+
+![One HANA tenant for many applications or microservices](./assets/hana_tenants_for_many.drawio.svg)
+
+**Option 1: Configure the same `hana_tenant_prefix`**
+###### 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.
+
+**Option 2: Pass the SAP HANA Tenant ID with a Subscription**
+###### Option 2: Pass the SAP HANA Tenant ID with a Subscription
 
 **... in CAP Node.js**
 ###### CAP Node.js
@@ -936,8 +949,6 @@ If you want to control the ID of the SAP HANA tenant ID on your own, you can pas
 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.
 
-![One HANA tenant for many applications](./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:
@@ -965,8 +976,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}
diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md
index 1e617a84f..f7c9ce043 100644
--- a/guides/multitenancy/mtxs.md
+++ b/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  |

From 543df6591d4d19c1435c80f8b7585bff69b054cd Mon Sep 17 00:00:00 2001
From: Rene Jeglinsky <rene.jeglinsky@sap.com>
Date: Wed, 8 Jul 2026 16:23:24 +0200
Subject: [PATCH 2/2] edit

---
 guides/multitenancy/index.md | 78 +++++++++++++++++-------------------
 1 file changed, 37 insertions(+), 41 deletions(-)

diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md
index c490176ba..09600d962 100644
--- a/guides/multitenancy/index.md
+++ b/guides/multitenancy/index.md
@@ -913,56 +913,52 @@ For **CAP Java** applications you need to set the same prefix in the <Config jav
     CDS_MULTITENANCY_HANAMTSERVICE_HANATENANTPREFIX: "some-prefix"
 ```
 
-##### Assign many tenant containers to a common HANA tenant
+##### Assign Many Tenant Containers to a Common SAP HANA Tenant
 
-To group the tenant containers of many applications or microservices in a common HANA tenant, you need to make sure that the same
-HANA tenant id is used.
+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 or microservices](./assets/hana_tenants_for_many.drawio.svg)
 
 **Option 1: Configure the same `hana_tenant_prefix`**
-###### 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.
+: 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.
 
 **Option 2: Pass the SAP HANA Tenant ID with a Subscription**
-###### Option 2: Pass the SAP HANA Tenant ID with a Subscription
 
-**... 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"
-	    }
-	  }
+: **... 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>"));
   }
-}
-```
-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**
-###### 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.
-
+  ```
+  
+  This will affect every new [tenant subscription](../../java/multitenancy.md#subscribe-tenant) and will set the specified SAP HANA tenant ID.
+  
 <div id="tmscmk" />