Tenant Registry

Summary

The tenant registry commands offer convenience for interacting with BTP’s Saas Provisioning service (technical name saas-registry).

The registry is the first of three perspectives that MTX Tool offers on tenant information. This is the outermost layer, the deeper layers are CAP Multitenancy and HANA Management.
Tenant Layers

For details and background information regarding the service, please consult the official documentation:

Commands for this area are:

   === tenant registry (reg) ===
~  regl   --registry-list [TENANT]                      list all subscribed subaccount names
~  regll  --registry-long-list [TENANT]                 long list all subscribed subaccounts
~  regs   --registry-service-config                     show registry service config
          --registry-update TENANT_ID                   update tenant dependencies
          --registry-update-all                         update dependencies for all subscribed tenants
          --registry-update-url [TENANT_ID]             update all subscribed application URL
*         --registry-offboard TENANT_ID                 offboard tenant subscription
*         --registry-offboard-skip TENANT_ID SKIP_APPS  offboard tenant subscription skipping apps
          ...    [TENANT]                               filter list for tenant id or subdomain
          ...    --json                                 list in json
          ...    --time                                 list includes timestamps
          ...    --skip-unchanged                       skip update for unchanged dependencies
          ...    --only-stale                           only update subscriptions that have not changed today
          ...    --only-failed                          only update subscriptions with UPDATE_FAILED state

~  are read-only commands
*  are potentially _dangerous_ commands

Environment

environment variable effect
MTX_REG_APP override configured app for saas-registry accesses
MTX_REG_CONCURRENCY change concurrency used for service calls (default is 10)
MTX_REG_FREQUENCY change polling frequency milliseconds for service async job calls (default is 15000)

List and Long List

The list command mtx regl is the most common entry point and will show a table of all registered subacconts with their most useful associated information.

With the addition of the --time flag, the list will include both absolute and relative timestamps for creation and the latest update.

If the provided information is insufficient or seems incomplete, then you can always fallback to the long list mtx regll, which will show the service’s full unparsed response data.

If you already know which subaccount or tenant id you want the information for, then you can filter the list or long list, by providing that information, e.g., mtx regl skyfin-company.

For automated processes, you can use the --json flag and consume the list data as JSON. With the --json flag active, you will get the same data for regl and regll. For example, to get the subscription url and state for each tenant, you could use:

mtx regl --json | jq '.subscriptions.[] | { url: .url, state: .state }'

Example for List

Here is an example of listing all registered tenants:

Registry Instance Introspection

The command mtx regs shows you the currently active configuration of the service instance. For details on the meaning of the configuration, please consult the official BTP documentation (see Summary).

Update Dependencies

The point of this command is comparatively complex and it will be rarely needed. The first part of the tenant onboarding process requires an xsapp to publish a list of multitenancy services, i.e., it’s “dependencies”. These services will then trust JWTs from the xsapp’s uaa for that tenant’s subaccont.

Now, if the xsapp developers want to add a new multitenancy service, but already have subscribed tenants, then you get a rare problem. The new services would trust tenants that have subscribed after they were added, but not those that had already been subscribed. For that reason, it is possible to re-do the dependency check and re-establish trust for already subscribed tenants.

In most cases, you can safely trigger this update for all tenants with mtx --registry-update-all, since no harm is done by re-establishing the trust for all subscribed subaccounts. Sometimes it pays to have more control and trigger the update just for a single subscribed subaccount with mtx --registry-update <tenant_id>.

Offboarding

Offboarding is the process of removing a tenant from the registry. Tenants, i.e., customer subaccount admins or test subaccounts admins will usually trigger this process themselves in the BTP cockpit by unsubscribing from an xsapp. In rare cases you, as the xsapp maintainer, may want to trigger this offboarding for a tenant. To achieve this run mtx --registry-offboard <tenant_id>.

This process is naturally irreversible and should be handled with extreme care.

In even rarer cases, you may want to remove the registry entry for a tenant without informing the underlying xsapp. One example would be if during a complete cleanup, if the xsapp was deleted prematurely, before all tenants had unsubscribed, then it will not be possible to run a regular offboarding for the remaining tenants, since the offboarding process expects a callback from the xsapp. In these circumstances you would use mtx --registry-offboard-skip <tenant_id> <xsapp_name>.