Skip to content

Add Kyma mtx-upgrade task to MT docs #2335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
swaldmann wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add Kyma mtx-upgrade task to MT docs #2335

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a0d0071
Add Kyma mtx-upgrade task to MT docs
swaldmann Jan 22, 2026
8363f52
Merge branch 'main' into mtx-upgrade-task
chgeo Jan 22, 2026
6f134c0
Merge branch 'main' into mtx-upgrade-task
swaldmann Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 152 additions & 120 deletions guides/multitenancy/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,136 +45,139 @@ In case of **CAP Node.js** projects, the `cds add multitenancy` command...

1. Adds package dependency `@sap/cds-mtxs` to your project:

```jsonc
{
"dependencies": {
"@sap/cds-mtxs": "^3"
},
}
```
```jsonc
{
"dependencies": {
"@sap/cds-mtxs": "^3"
},
}
```

2. Adds this configuration to your _package.json_ to enable multitenancy with sidecar:

```jsonc
{
"cds": {
"profile": "with-mtx-sidecar",
"requires": {
"[production]": {
"multitenancy": true
},
"[with-mtx]": {
"multitenancy": true
}
}
}
}
```
```jsonc
{
"cds": {
"profile": "with-mtx-sidecar",
"requires": {
"[production]": {
"multitenancy": true
},
"[with-mtx]": {
"multitenancy": true
}
}
}
}
```

3. Adds a sidecar subproject at `mtx/sidecar` with this _package.json_:

```json
{
"name": "bookshop-mtx",
"dependencies": {
"@cap-js/hana": "^2",
"@sap/cds": "^9",
"@sap/cds-mtxs": "^3",
"@sap/xssec": "^4",
"express": "^4"
},
"devDependencies": {
"@cap-js/sqlite": "^2"
},
"engines": {
"node": ">=20"
},
"scripts": {
"start": "cds-serve"
},
"cds": {
"profile": "mtx-sidecar"
}
}
```
```json
{
"name": "bookshop-mtx",
"dependencies": {
"@cap-js/hana": "^2",
"@sap/cds": "^9",
"@sap/cds-mtxs": "^3",
"@sap/xssec": "^4",
"express": "^4"
},
"devDependencies": {
"@cap-js/sqlite": "^2"
},
"engines": {
"node": ">=20"
},
"scripts": {
"start": "cds-serve"
},
"cds": {
"profile": "mtx-sidecar"
}
}
```

4. If necessary, modifies deployment descriptors such as `mta.yaml` for Cloud Foundry and Helm charts for Kyma.

:::
::: details See what this adds to your **Java** project…

In case of **CAP Java** projects, the `cds add multitenancy` command...

1. Adds the following to _.cdsrc.json_ in your app:

```jsonc
{
"profiles": [
"with-mtx-sidecar",
"java"
],
"requires": {
"[production]": {
"multitenancy": true
}
}
}
```

2. Adds the following to your _srv/pom.xml_ in your app:

```xml
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-feature-mt</artifactId>
<scope>runtime</scope>
</dependency>
```

3. Adds the following to your _srv/src/java/resources/application.yaml_:

```yml
---
spring:
config.activate.on-profile: cloud
cds:
multi-tenancy:
mtxs.enabled: true

```
::: details See what this adds to your **Java** project…

4. Adds a sidecar subproject at `mtx/sidecar` with this _package.json_:
In case of **CAP Java** projects, the `cds add multitenancy` command...

```json
{
"name": "bookshop-mtx",
"dependencies": {
"@cap-js/hana": "^2",
"@sap/cds": "^9",
"@sap/cds-mtxs": "^3",
"@sap/xssec": "^4",
"express": "^4"
},
"devDependencies": {
"@cap-js/sqlite": "^2"
},
"engines": {
"node": ">=20"
},
"scripts": {
"start": "cds-serve",
"build": "cds build ../.. --for mtx-sidecar --production && npm ci --prefix gen"
},
"cds": {
"profiles": [
"mtx-sidecar",
"java"
]
}
}
```
1. Adds the following to _.cdsrc.json_ in your app:

```jsonc
{
"profiles": [
"with-mtx-sidecar",
"java"
],
"requires": {
"[production]": {
"multitenancy": true
}
}
}
```

2. Adds the following to your _srv/pom.xml_ in your app:

```xml
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-feature-mt</artifactId>
<scope>runtime</scope>
</dependency>
```

3. Adds the following to your _srv/src/java/resources/application.yaml_:

```yml
---
spring:
config.activate.on-profile: cloud
cds:
multi-tenancy:
mtxs.enabled: true

```

4. Adds a sidecar subproject at `mtx/sidecar` with this _package.json_:

```json
{
"name": "bookshop-mtx",
"dependencies": {
"@cap-js/hana": "^2",
"@sap/cds": "^9",
"@sap/cds-mtxs": "^3",
"@sap/xssec": "^4",
"express": "^4"
},
"devDependencies": {
"@cap-js/sqlite": "^2"
},
"engines": {
"node": ">=20"
},
"scripts": {
"start": "cds-serve",
"build": "cds build ../.. --for mtx-sidecar --production && npm ci --prefix gen"
},
"cds": {
"profiles": [
"mtx-sidecar",
"java"
]
}
}
```
:::

::: details Profile-based configuration presets

The profiles `with-mtx-sidecar` and `mtx-sidecar` activate pre-defined configuration presets, which are defined as follows:
Expand Down Expand Up @@ -243,6 +246,7 @@ In case of **CAP Java** projects, the `cds add multitenancy` command...
You can always inspect the _effective_ configuration with `cds env`.
:::


## Test-Drive Locally


Expand Down Expand Up @@ -430,7 +434,7 @@ In the third terminal, subscribe and unsubscribe tenants as follows:
:::


### 4. Test via the app's UI {.node}
### 4. Test via the app's UI

For example, in case of [_@capire/bookshop_](https://github.com/capire/bookshop) sample, you can now test your app with different users/tenants as follows...

Expand Down Expand Up @@ -667,12 +671,13 @@ There are several ways to update the database schema of a multitenant applicatio

* For **CAP Java** applications, schema updates should be done as described in the respective [Java Guide](../../java/multitenancy#database-update).
* For **CAP Node.js** applications, you can use either of:
- the `cds-mtx upgrade` command from a terminal
* the `cds-mtx upgrade` command from a terminal
- the [MTX Sidecar API](mtxs#upgrade-tenants-→-jobs)
- via a [CloudFoundry hook](https://help.sap.com/docs/btp/sap-business-technology-platform/module-hooks)
- via a [CloudFoundry task](https://tutorials.cloudfoundry.org/cf4devs/advanced-concepts/tasks/)
- via a [Kubernetes job](https://kubernetes.io/docs/concepts/workloads/controllers/job/)

as shown in the examples below.
as shown in the examples below.

::: code-group
```sh [cds-mtx upgrade]
Expand All @@ -686,21 +691,48 @@ Content-Type: application/json

{ "tenants": ["t1"] }
```
```yaml [CloudFoundry hook]
```yaml [CF hook]
# mta.yaml
hooks:
- name: upgrade-all
type: task
phases:
# - blue-green.application.before-start.idle
- blue-green.application.before-start.idle
- deploy.application.before-start
parameters:
name: upgrade
memory: 512M
disk-quota: 768M
command: cds-mtx upgrade '*'
```
```sh [CloudFoundry task]
cf run-task <app> --name "upgrade-all" --command "cds-mtx upgrade '*'"
```sh [CF task]
cf run-task ‹app› --name "upgrade-all" --command "cds-mtx upgrade '*'"
```
```yaml [Kubernetes job]
# values.yaml
mtx-upgrade:
bindings:
saas-registry: # when using XSUAA
serviceInstanceName: saas-registry
subscription-manager: # when using IAS
serviceInstanceName: subscription-manager
service-manager:
serviceInstanceName: service-manager
image:
repository: bookshop-sidecar
resources:
limits:
ephemeral-storage: 1G
memory: 1G
requests:
ephemeral-storage: 1G
cpu: 1000m
memory: 1G
command: ["launcher"]
args:
- "cds-mtx"
- "upgrade"
- '*'
```
:::

Expand Down