sap-samples/btp-cap-multitenant-saas

Sample project that demonstrates how to setup a multitenant application for a Software-as-a-Service scenario, leveraging the Kyma and Cloud Foundry Runtimes of the SAP Business Technology Platform. Developers learn how to implement their own CAP (mtxs) based SaaS app including an SaaS API and integration with various essential SAP BTP service of...

Develop a multitenant Software as a Service application in SAP BTP using CAP (Kyma + Cloud Foundry)

Description

The Sustainable SaaS (SusaaS) sample application has been built in a partner collaboration to help interested developers, partners, and customers in developing multitenant Software as a Service applications using CAP and deploying them to the SAP Business Technology Platform (SAP BTP). For this use-case, the SAP BTP, Cloud Foundry and Kyma Runtime were chosen. Still, you can also develop similar SaaS applications in the SAP BTP, ABAP environment (click here for further details).

The example focuses on using standard frameworks and SAP BTP services for developing, deploying, and monitoring the solution like the Cloud Application Programming Model (CAP), SAP API Management, Alert Notification, and many more.

The sample application has a focus on the topic of sustainability and is therefore called Sustainable SaaS (Susaas) app. It allows customers (Consumer Tenants) of the SaaS application to extend their SAP solutions like SAP S/4HANA with additional features developed by the SaaS vendor (Provider).

Due to the technical and theoretical complexity of the topic, the sample application shall not be seen or used in any kind for productive scenarios. It is supposed to present ideas and approaches for putting your scenario into practice. Our goal is to cover as many topics as we can, but not in the greatest depth that might justify productive usability.

Below you can find the solution architecture diagrams of our sample application. As you can see, the Kyma as well as the Cloud Foundry architecture both contain a lot of services and tools which you will use in this tutorial (click to enlarge).

Kyma

Cloud Foundry

Content

To get started, we recommend to Discover some basic skills and learnings first. The following parts of the documentation will introduce you to the basics of this scenario, the concepts of multitenancy, and Software as a Service applications.

• 1 - Discover the tutorial target
• 2 - Basics of SAP BTP, Cloud Foundry, Kyma and CAP
• 3 - Partners in SAP BTP ecosystem
• 4 - Get an idea of SaaS applications
• 5 - Understand SAP BTP multitenancy
• 6 - What's New

Continue your journey and deploy the Basic Version of the SaaS sample application to your SAP BTP, Cloud Foundry or Kyma environment, after preparing your Provider Subaccount by assigning the required entitlements. Learn about the different components used in the comprehensive SaaS sample app running in your environment now and subscribe a first Consumer Tenant.

• 0 - Introduction of the Basic Version
• 1 - Understand the repository structure
• 2 - Prepare the Provider Subaccount
• 3 - Build and deploy the Application
  • Build and deploy the Application (Cloud Foundry only)
  • Build your Container Images (Kyma only)
  • Deploy the SaaS Application (Kyma only)
• 4 - Subscribe a Consumer Subaccount
• 5 - Push data to the SaaS API
• 6 - Test the SaaS application
• 7 - Explore technical Application details
  • Explore the application components
  • Discover Helm and Kyma Resources (Kyma only)
• 8 - Unsubscribe Consumer Subaccounts
• 9 - Undeploy the SaaS application

Once you successfully deployed the Basic features of the SaaS sample application to your Cloud Foundry landscape or Kyma Cluster, feel free to enhance it with more features as part of the Advanced Version. This includes for example a SAP API Management integration to monitor and manage your SaaS API endpoints or SAP Identity Authentication to provide a Central User Management without relying on SAP ID service. Furthermore, you will learn and see a sample of how to integrate a backend system like SAP S/4HANA from a SaaS Consumer perspective.

• 0 - Introduction of the Advanced Version
• 1 - Prepare the Provider Subaccount
• 2 - Central user management with SAP IAS
• 3 - Push data from SAP S/4HANA system
• 4 - Make your API enterprise-ready
  • Connect Cloud Foundry with SAP API Management (Cloud Foundry only)
  • Integrate Kyma with SAP API Management (Kyma only)

After adding some or all of the Advanced Features, the following Expert Features contain a variety of different topics, which will make your application and life as a SaaS developer even more convenient. You will learn about management and backup of your Tenant database containers, multi-region deployments of SaaS applications and how to tackle topics like Custom Domain usage. Most of the Advanced Features can be tested with both, the Cloud Foundry and the Kyma Runtime, while some of the features are (as of now) available for a specific runtime only.

Important - Some of the Expert Features are Work-in-Progress. The code and documentation are subject to change.

• Local and hybrid development
• Tenant onboarding with Terraform
• Custom domain for SAP IAS
• Send emails using Microsoft Graph
• Feature Toggles
• SaaS Consumer Extensibility
• Manage Tenant database containers
• HDI container administration
• Backup database containers
• Integrate a Consumer IdP
• Update Tenant database containers

Cloud Foundry (only)

• Custom domain usage
• Multiple SAP HANA Cloud instances
• Deployment to multiple regions
• Setup a Continuous Integration Scenario
• Using the SAP Theme Designer
• Configure SAP Transport Management

Kyma (only)

• Custom domain usage
• Onboarding Automation and One Domain
• Setup a Continuous Integration Scenario

Requirements

If not yet done, for this sample application we recommend to set up a Pay-As-You-Go (PAYG) or CPEA account and use the mentioned Free (Tier) service plans. A tutorial how to setup a PAYG account (allowing you to use all Free Tier service plans) can be found in the Tutorial Navigator.

Hint - This sample scenario (Basic and Advanced Version) can also be deployed to Cloud Foundry and Kyma environments in Trial accounts, although we recommend to use one of the two account types mentioned above. When going for a Trial account, please make sure to choose the us10 region to have access to SAP HANA Cloud.

Basic Version

The Basic Version of the sample application requires the following set of SAP BTP entitlements in the Provider Subaccount and can be done using Free (Tier) service plans of PAYG and CPEA accounts.

Kyma

Service / Subscription	Free Tier / (Trial) Plans
Destination Service	Lite
SAP Alert Notification service for SAP BTP	Free / (Trial: Lite)
SAP Application Logging Service	Lite
SAP Authorization and Trust Management Service	Broker Application
SAP BTP, Kyma Runtime	Free / (Trial: Trial)
SAP Cloud Management Service for SAP BTP	Central
SAP HTML5 Application Repository Service for SAP BTP	App-host App-runtime
SAP Software-as-a-Service Provisioning service	Application
SAP HANA Cloud	hana-free (Trial: hana) tools
SAP HANA Schemas & HDI Containers	hdi-shared
SAP Service Manager	Container Subaccount-Admin

Cloud Foundry

Hint - 1GB of Cloud Foundry Runtime is sufficient for this use-case.

Service / Subscription	Free (Tier) / (Trial) Plans
Application Autoscaler	Standard
Destination Service	Lite
SAP Alert Notification service for SAP BTP	Free / (Trial: Lite)
SAP Application Logging Service	Lite
SAP Authorization and Trust Management Service	Broker Application
SAP BTP, Cloud Foundry Runtime	Free / (Trial: MEMORY)
SAP Cloud Management Service for SAP BTP	Central
SAP Credential Store	Free / (Trial: Trial)
SAP HTML5 Application Repository Service for SAP BTP	App-host App-runtime
SAP SaaS Provisioning Service	Application
SAP HANA Cloud	hana-free / (Trial: hana) tools
SAP HANA Schemas & HDI Containers	hdi-shared
SAP Service Manager	Container Subaccount-Admin

If you need assistance assigning entitlements to your Provider Subaccount, you might find information here.

Advanced Features

The Advanced Features require some additional services and software components which are listed below. Please note that the SAP Identity Authentication Service is only available in Pay-As-You-Go (PAYG) and CPEA accounts.

Service	Free (Tier) / (Trial) Plans
SAP Integration Suite	Free (Application) (Trial: trial (Application))
Cloud Identity Services	default (Application) Application
SAP S/4HANA 2021 (or newer)

Please check the below details on these additional entitlements required for the Advanced Version. Especially using the Cloud Identity Services it is essential to understand the licensing model to remain within the free usage boundaries!

SAP Integration Suite

The free service plan is usable for 90 days only. Your tenant will be decommissioned after 90 days and you need to set up a new tenant if you wish to do further validations.

Cloud Identity Services

When signing up for a PAYG or CPEA account, you're entitled for one free test and productive SAP Identity Authentication Service (SAP IAS) tenant. Use the Cloud Identity Services plan default (Application) to create such an instance in your environment. Any further tenant can be licensed as Additional Tenant and will be charged according to your account type. Please also check the official SAP Help documentation (click here) and the following blog post (click here) for further information. Please check for potentially existing SAP IAS tenants first, to make sure you are sticking to the free service offering limits.

Using the SAP Identity Authentication Service, please make sure to comply with the license model, which is highly dependent on the application registration type created in SAP IAS. Using SAP IAS for authentication scenarios involving third-party solutions will result in costs! While SAP Cloud to SAP Cloud Log-ons are usually part of your overall SAP BTP contract, make sure you understand the licensing model before extensively using SAP IAS as part of your overall architecture. Additional information can be found in SAP Help (click here).

The service plan application allows you to create respective Service Instances within SAP BTP, that will automatically register an application in the trusted SAP IAS tenant configured in your Subaccount configuration.

SAP S/4HANA

An SAP S/4HANA system is actually not part of your SAP BTP Provider Subaccount, but is required if you want to test the automated data push feature from an existing SAP On-Premise solution. While we recommend to use at least the SAP S/4HANA 2021 release, with a bit of coding effort you should also be able to integrate older releases. This tutorial assumes you have at least access to an SAP S/4HANA 2021 release. Feel free to check out the SAP Cloud Appliance Library (https://cal.sap.com/) to get yourself a free test license.

Known Issues

Open

• Automated Credential Rotation (Workaround available - 2023/06/09)
  • Problem: Users are facing a callback authentication error after successful login via SAP IAS as part of the One-Domain concept.
  • Issue: Activating the automated credential rotation of the SAP BTP Service Operator renews the X.509 certificate of the respective SAP IAS service bindings. As the Application Router caches the binding details for performance reasons, the cached X.509 certificate is not valid anymore after rotation. This results in an authentication error between Application Router and SAP IAS.
  • Workaround: A restart of the Application Router after credential rotation will solve this issue and the latest X.509 certificate is being cached. This restart can be automated in a Kubernetes/Kyma CronJob, starting a new Deployment rollout according to your credential rotation cycle. You can find an example incl. roles and service accounts in the respective Expert Features (click here). Combined with an external Redis cache for Application Router session management, downtimes can be minimized or completely mitigated! Make sure to have a sufficient overlap of both, the old and new X.509 certificate (rotatedBindingTTL: 24h & rotationFrequency: 48h), so the cached credentials are still valid until the restart has happened!
  • Solution: Issue has been addressed and a potential notification mechanism might trigger an automated update of the Application Router cache in the future (subject to change).
• Consumer extension API issue (Workaround available - 2022/12/19)
  • Problem: Applying a Consumer extension currently results in the Push API not being usable by the extended Tenant anymore.
  • Issue: The current implementation has issues to read and process the CSN file of the extended SaaS CAP service. This service serves as a base for the API CAP service.
  • Workaround: Extensibility has been temporarily disabled for the CAP API Service.
  • Solution: Issues has been addressed with the CAP product management and potential solutions will be worked on.

How to obtain support

Create an issue in this repository if you find a bug or have questions about the content.

For additional support, ask a question in SAP Community.

Contributing

If you wish to contribute code or offer fixes or improvements, please send a pull request. Check out our contribution guide. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request for this project. This happens in an automated fashion during the submission process. SAP uses the standard DCO text of the Linux Foundation.

Code of Conduct

Please follow our code of conduct.

License

Copyright (c) 2023 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.

btp-cap-multitenant-saas's Issues

adopt @capjs/hana driver

How to automatically switch service to access to shared table between HANA and SQLite?

Dear team,

Thanks for your great contribution to share multitenancy application and instruction.
I am implementing multitenancy application based on your repository and I have question for shared database container.

In your explanation, we need two CDS for both HANA for production and SQLite for local testing.
Currently I extended your service to access to shared table and manually change CDS file /code/db/sqlite/data-model to /code/db/hana/data-model before deployment to Cloud Foundry.

Is there smarter way to switch between two CDS files?
I could not find good example of this use case. So I am helpful if you advise me.

custom-domain-routes no routes found

Hi,

I'm following the instruction https://github.com/SAP-samples/btp-cap-multitenant-saas/blob/main/docu/4-expert/-CloudFoundry-/custom-domain-usage/README.md and get stuck in the following configuration.

I'm trying to create a custom domain mapping in my sub-account. I'm experiencing the inconsistent behaviour, which is cannot troubleshoot myself, so I kindly ask you to help me. The mapping creation finishes successfully:

d057039:my_own_rootCA$ cf custom-domain-map-route myapp-app-router.cfapps.eu12.hana.ondemand.com aaa.mydomain.cloud.sap
Command: custom-domain-map-route
Organisation:  tdo-dev  (184bdae4-0c2f-4174-9a64-fb847e13d13e)
API Endpoint:  https://api.cf.eu12.hana.ondemand.com/
Custom-Domain API Server:  https://custom-domain-certificates-api.cf.eu12.hana.ondemand.com/
OK

However the consequent mapping check shows the mapping is not created:

d057039:my_own_rootCA$ cf custom-domain-routes
Command: custom-domain-routes
Organisation:  tdo-dev  (184bdae4-0c2f-4174-9a64-fb847e13d13e)
API Endpoint:  https://api.cf.eu12.hana.ondemand.com/
Custom-Domain API Server:  https://custom-domain-certificates-api.cf.eu12.hana.ondemand.com/

No routes found

Trying to access the custom domain via web-browser confirms the mapping was not created:

https://aaa.tdo.cloud.sap/
404 Not Found: Requested route ('aaa.mydomain.cloud.sap') does not exist.

How can I create the mapping?

Kyma Docker image build fails due to missing sapse/html5-app-deployer:5.0.2 image

Hi,

I'm try to follow Kyma - Build, Pack and Push your Docker Images but when running step 3:

npx cross-env IMAGE_PREFIX=<ContainerImagePrefix> npm run build:all

I get this error message:

 => ERROR [internal] load metadata for docker.io/sapse/html5-app-deployer:5.0.2

I think this is because at https://hub.docker.com/r/sapse/html5-app-deployer/tags?page=1&name=5.0.2 no image with the tag 5.0.2 can be found.

Best Regards
Gregor

Issue with the Kyma deployment: susaas-hana-deployer stuck in status pending

Hello,

I'm trying to get the application deployed to my BTP Free Tier Kyma environment in the region us10-001. Unfortunately it seems to be stuck in in the HANA deployment. Executing the helm install / upgrade results in:

Error: UPGRADE FAILED: pre-upgrade hooks failed: 1 error occurred:
        * timed out waiting for the condition

Looking at the susaas-hana-deployer pod in the Kyma Cockpit i see this warning:

0/1 nodes are available: 1 Insufficient cpu. preemption: 0/1 nodes are available: 1 
No preemption victims found for incoming pod..

The log of this pod is completely empty.

The list of created service instances looks OK:

Also it seems that the HDI container for the t0 was created. But here I see a warning:

"This consuming option is out-of-date.More details here"

is an update needed here?

Looking forward for your input.

Best Regards
Gregor

Question: Blue-green deployment strategy

Hi,

I'm using this example as a basis for a multitenant solution built on top of cloud foundry. This setup seems to be working perfectly fine when using a default deployment configuration.

Once we start using a blue-green deployment strategy the subscription breaks, because the url of the onSubscription & getDependencies of the SaaS Provision Service is set to the temporary route of the blue-green deployment strategy, but not updated once the new version is up and running.

Any ideas on how to handle this?

Cheers,
Geert-Jan

Subscription fails for subscriber tenant

When performing tenant subscription for Saas dev plan, I get the 500 Error:

2023-12-18T17:47:16.969+0000 [APP/PROC/WEB/0] STDOUT Subscription Params: [object Object]
2023-12-18T17:47:16.969+0000 [APP/PROC/WEB/0] STDOUT Custdomain null
2023-12-18T17:47:16.969+0000 [APP/PROC/WEB/0] STDOUT [mtx|sap-provisioning] - subscribing tenant
2023-12-18T17:47:17.023+0000 [APP/PROC/WEB/0] STDOUT [mtx|] - creating HDI container for { tenant: '' } with {
2023-12-18T17:47:17.023+0000 [APP/PROC/WEB/0] STDOUT provisioning_parameters: {

2023-12-18T17:47:30.065+0000 [APP/PROC/WEB/0] STDOUT [mtx|] - finished HANA deployment artifact preparation
2023-12-18T17:47:30.067+0000 [APP/PROC/WEB/0] STDERR [mtx|] - refreshing credentials failed with Error: Connect failed (invalid SERVERNODE '')
2023-12-18T17:47:30.067+0000 [APP/PROC/WEB/0] STDERR at Socket. (/home/vcap/deps/0/node_modules/@sap/hana-client/lib/index.js:53:13)
2023-12-18T17:47:30.067+0000 [APP/PROC/WEB/0] STDERR at Socket.emit (node:events:517:28)
2023-12-18T17:47:30.067+0000 [APP/PROC/WEB/0] STDERR at addChunk (node:internal/streams/readable:335:12)

Onboarding Test

Create E2E Test for the repository which covers all possible critical points.

Adopt new @capjs-telemetry plugin and remove deprecated application logging service, put instead CLS

When trying to build on widnows

There is an error when trying to build from windows only for api & srv images using main branch

Error when starting susaas-srv, cannot find catalog 'hana'

i have tested and the connection to hana HDI is working. This is on the upgrade branch. All other services are starting without errors.

Integrate apps in SAP Build Work Zone

Hi,

Thank you for this nice step-to-step guide! I successfully deployed the application to my trial account. Now I have the use-case that I want to integrate the apps into an SAP Build WorkZone launchpad. But so far I haven't found a nice way to do this.

So my tenant subaccount looks like this:

I created a destination in the tenant subaccount pointing to the Sandbox launchpad of the SusaaS application:

URL=https\://mytenant-susaas-dev.cfapps.us10-001.hana.ondemand.com/sapsusaasuipublicflp
Name=my-susaas-launchpad
ProxyType=Internet
Type=HTTP
Authentication=NoAuthentication

In the Content Manager I added the app as following and added it to the launchpad:

When launching the application over the Work Zone service, but I have a duplicate shell header (which is logical for me):

It would be possible to hide the header by adding the following code to the application:

sap.ushell.Container.getRenderer("fiori2").setHeaderVisibility(false);

In my opinion, however, this is not a viable option in this case because the shell header would also disappear if I opened the app via the sandbox launchpad.

Is there a way to integrate the apps in the SAP Build Work Zone in a nice way? I am aware that I could provide the apps as a content provider, but that is not an option in this case, as deployment via the portal service is deprecated and it no longer works via the launchpad/work zone service as it used to with the portal service.

Kind regards,
Johannes

Update Alerrt Notification Service parameters

Alert Notification Service parameter should be updated as below.

{ "enableCloudControllerAuditEvents": true }

CNB Build for htlm5-deployer

In the example CICD configuration, a CNB build is defined for the htlm5-deployer image:

https://github.com/SAP-samples/btp-cap-multitenant-saas/blob/main/docu/4-expert/-Kyma-/setup-cicd-for-project/files/config.yml#L72

However, I do not get that to work, neither in the CICD service nor locally. It fails with:

failed to copy linked module directory to layer path: failed to copy: destination exists: remove /layers/paketo-buildpacks_npm-install: directory not empty

shared db not used

I believe that there is not usage of the shared db, it would be great to add examples to read / write data from any ui app with the corresponding service.

DB Content: https://github.com/SAP-samples/btp-cap-multitenant-saas/tree/main/code/db-com

Kind Regards.
Max.

Blue Green Deployment - CF and Kyma

Have a sync with mta colleagues and provide a guidance for Blue Green Deployment, on CF and Kyma.
Also additional blog post and documentation is necessary.

Blue Green Deployment for CF with MTA
Blue Green Deployment for Kyma with Istio

Screenshots are not visible in documentation at any page

Replacement of "console.log" statements with "cds.log" in the project.

Node.js standard console logs should be replaced with standard CDS Logs

console.log("Alper") // Not true

const LOG = cds.log('susaas').  // True
LOG.info ('whatever', you, 'like...')

Error - Subscription - Service instance can not be created for cis-central

Hello ,

I got below mentioned error when I tried to subscribed the service

Kindly let me know how I can fix it

Thanks
Sandeep

different git repository for every app to reduce development dependencies

Hi,

we have separate git repository of our custom fiori apps. we want to include those app in susaas solution.
can we keep separate repository for every app and refer/use them sussas launchpad config or app folder.

use CAP built-in /health endpoint for healthchecks in Runtimes (CF + Kyma )

Update npm package versions in the repo

npm dependency versions must be updated and repo should be tested afterwards functionalitywise.

Following packages have the prio:

• @sap/cds
• @sap/cds-mtxs