Kyma Deployment Update (#196)

Switched to Approuter based UI deployment instead of HTML5 Apps based
and updated other sections.

Co-authored-by: Marc Becker <[email protected]>

Author: sidakphull

README.md

@@ -241,57 +241,69 @@ Before you can access the UI using the (tenant-specific) URL to the bookshop(-mt
 - Container Registry (e.g. [Docker Hub](https://hub.docker.com/))
 - Command Line Tools: [`kubectl`](https://kubernetes.io/de/docs/tasks/tools/install-kubectl/), [`kubectl-oidc_login`](https://github.com/int128/kubelogin#setup), [`pack`](https://buildpacks.io/docs/tools/pack/), [`docker`](https://docs.docker.com/get-docker/), [`helm`](https://helm.sh/docs/intro/install/), [`cf`](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html)
 - Logged into Kyma Runtime (with `kubectl` CLI), Cloud Foundry space (with `cf` CLI) and Container Registry (with `docker login`)
-- `@sap/cds-dk` >= 6.0.1
+- `@sap/cds-dk` >= 6.6.0
 
 ### Add Deployment Files
 
-CAP tooling provides your a Helm chart for deployment to Kyma.
+CAP tooling provides you a Helm chart for deployment to Kyma.
 
-Add the CAP Helm chart with the required features to this project:
+For single tenant deployment, replace the `requires` section in _`.cdsrc.json`_ with:
 
-```bash
-cds add helm
-cds add hana
-cds add xsuaa
-cds add html5-repo
+```
+    "requires": {
+        "auth": {
+            "kind": "xsuaa"
+        },
+        "approuter": {
+            "kind": "cloudfoundry"
+        },
+        "db": {
+            "kind": "hana-cloud"
+        }
+    },
 ```
 
-#### Helm chart configuration
+For multi tenant deployment, replace the `requires` section in _`.cdsrc.json`_ with:
 
-This project contains a pre-configured configuration file `values.yaml`, you just need to do the following changes in this file:
+```
+    "requires": {
+        "multitenancy": true,
+        "extensibility": true,
+        "toggles": true,
+        "auth": {
+            "kind": "xsuaa"
+        },
+        "approuter": {
+            "kind": "cloudfoundry"
+        }
+    },
+```
 
-- `<your-container-registry>` - full-qualified hostname of your container registry
-- `domain`- full-qualified domain name used to access applications in your Kyma cluster
+Add the CAP Helm chart with the required features to this project:
+
+```bash
+cds add helm
+```
 
-#### Use API_BUSSINESS_PARTNER Remote Service (optional)
+#### Use API_BUSSINESS_PARTNER Remote Service (optional, single tenant only)
 
 You can try the `API_BUSINESS_PARTNER` service with a real S/4HANA system with the following configuration:
 
 1. Create either an on-premise or cloud destination in your subaccount.
 
-2. Add the binding to the destination service for the service (`srv`) to the `values.yaml` file:
+2. Add configuration required for the destination service by executing the following command.
 
-    ```yaml
-    srv:
-      ...
-      bindings:
-        ...
-        destinations:
-          serviceInstanceName: destinations
+    ```bash
+    cds add destination
     ```
 
-    (The destination service instance is already configured)
-
 3. Set the profiles `cloud` and `destination` active in your `values.yaml` file:
 
     ```yaml
     srv:
       ...
       env:
         SPRING_PROFILES_ACTIVE: cloud,destination
-        # TODO: To be removed after @sap/cds-dk patch
-        CDS_ENVIRONMENT_K8S_SERVICEBINDINGS_CONNECTIVITY_SECRETSPATH: '/bindings/connectivity'
-        CDS_ENVIRONMENT_K8S_SERVICEBINDINGS_CONNECTIVITY_SERVICE: 'connectivity'
     ```
 
 4. For on-premise only: Add the connectivity service to your Helm chart:
@@ -300,6 +312,8 @@ You can try the `API_BUSINESS_PARTNER` service with a real S/4HANA system with t
     cds add connectivity
     ```
 
+   Note: `cds add helm` will not add configuration required to create a Connectivity Service Instance. This Service Instance should be created by the Kyma Cluster Administrator. For more information regarding configuration of Connectivity Instance, please check the [documentation](https://cap.cloud.sap/docs/guides/deployment/deploy-to-kyma#connectivity-service).
+
 *See also: [API_BUSINESS_PARTNER Remote Service and Spring Profiles](#api_business_partner-remote-service-and-spring-profiles)*
 
 ### Prepare Kubernetes Namespace
@@ -314,78 +328,198 @@ bash ./scripts/create-container-registry-secret.sh
 
 The *Docker Server* is the full qualified hostname of your container registry.
 
-#### Create a HDI container and a secret
+#### Create a HDI container / Service Manager Instance and a Secret
+
+This step is only required if you're using a BTP Trial account. If you're using a production or a free tier account then you can create HDI Container from Kyma directly by adding a [mapping to your Kyma namespace in your HANA Cloud Instance](https://blogs.sap.com/2022/12/15/consuming-sap-hana-cloud-from-the-kyma-environment/) and skip this step.
+
+##### Single Tenant
 
 ```
 bash ./scripts/create-db-secret.sh bookshop-db
 ```
 
-It will create a HDI container `bookshop-db` on your currently targeted Cloud Foundry space and creates a secret `bookshop-db` with the HDI container's credentials in your current Kubernetes namespace.
+It will create a HDI container `bookshop-db` instance on your currently targeted Cloud Foundry space and a secret `bookshop-db` with the credentials in your current Kubernetes namespace.
 
-### Build
+Make the following changes to your _`chart/values.yaml`_.
+
+```diff
+srv:
+  bindings:
+    db:
+-     serviceInstanceName: hana
++     fromSecret: bookshop-db
+...
 
-**Build data base deployer image:**
+hana-deployer:
+  bindings:
+    hana:
+-     serviceInstanceName: hana
++     fromSecret: bookshop-db
 
+...
+- hana:
+-   serviceOfferingName: hana
+-   servicePlanName: hdi-shared
 ```
-cds build --production
 
-pack build $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer \
-     --path db \
-     --buildpack gcr.io/paketo-buildpacks/nodejs \
-     --builder paketobuildpacks/builder:base
+##### Multi Tenant
+
+```
+bash ./scripts/create-sm-secret.sh bookshop-sm
 ```
 
-(Replace `$YOUR_CONTAINER_REGISTRY` with the full-qualified hostname of your container registry)
+It will create a Service Manager `bookshop-sm` instance on your currently targeted Cloud Foundry space and a secret `bookshop-sm` with the credentials in your current Kubernetes namespace.
 
+Make the following changes to your _`chart/values.yaml`_.
 
-**Build image for CAP service:**
+```diff
+srv:
+  bindings:
+    service-manager:
+-     serviceInstanceName: service-manager
++     fromSecret: bookshop-sm
+...
 
+sidecar:
+  bindings:
+    service-manager:
+-     serviceInstanceName: service-manager
++     fromSecret: bookshop-sm
+
+...
+- service-manager:
+-   serviceOfferingName: service-manager
+-   servicePlanName: container
 ```
-mvn package
+
+### Build
+
+```bash
+cds build --production
 ```
 
+**Build image for CAP service:**
+
+```bash
+mvn clean package -DskipTests=true
 ```
+
+```bash
 pack build $YOUR_CONTAINER_REGISTRY/bookshop-srv \
         --path srv/target/*-exec.jar \
         --buildpack gcr.io/paketo-buildpacks/sap-machine \
         --buildpack gcr.io/paketo-buildpacks/java \
         --builder paketobuildpacks/builder:base \
-        --env SPRING_PROFILES_ACTIVE=cloud
+        --env SPRING_PROFILES_ACTIVE=cloud \
+        --env BP_JVM_VERSION=17
 ```
 
-**Build HTML5 application deployer image:**
+(Replace `$YOUR_CONTAINER_REGISTRY` with the full-qualified hostname of your container registry)
 
+**Build Approuter Image:**
+
+```bash
+pack build $YOUR_CONTAINER_REGISTRY/bookshop-approuter \
+     --path app \
+     --buildpack gcr.io/paketo-buildpacks/nodejs \
+     --builder paketobuildpacks/builder:base \
+     --env BP_NODE_RUN_SCRIPTS=""
+```
+
+**Build database deployer image (single tenant only):**
+
+```bash
+pack build $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer \
+     --path db \
+     --buildpack gcr.io/paketo-buildpacks/nodejs \
+     --builder paketobuildpacks/builder:base \
+     --env BP_NODE_RUN_SCRIPTS=""
 ```
-bash ./scripts/build-ui-image.sh
+
+**Build sidecar image (multi tenant only):**
+
+```bash
+pack build $YOUR_CONTAINER_REGISTRY/bookshop-sidecar \
+     --path mtx/sidecar/gen \
+     --buildpack gcr.io/paketo-buildpacks/nodejs \
+     --builder paketobuildpacks/builder:base \
+     --env BP_NODE_RUN_SCRIPTS=""
 ```
 
 ### Push container images
 
 You can push all the container images to your container registry, using:
 
+```bash
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-srv
+
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-approuter
 ```
-docker push $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer
 
-docker push $YOUR_CONTAINER_REGISTRY/bookshop-srv
+#### Single Tenant
 
-docker push $YOUR_CONTAINER_REGISTRY/bookshop-html5-deployer
+```bash
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer 
 ```
 
-### Deployment
+#### Multi Tenant
 
+```bash
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-sidecar
+```
+
+### Configuration
+
+Make the following changes in the _`chart/values.yaml`_ file.
+
+1. Change value of `global.domain` key to your cluster domain.
+
+2. Replace `<your-cluster-domain>` in `xsuaa.parameters.oauth2-configuration.redirect-uris` with your cluster domain.
+
+3. Replace `<your-container-registry>` with your container registry.
+
+4. Make the following change to add backend destinations required by Approuter.
+   
+```diff
+-  backendDestinations: {}
++  backendDestinations:
++     backend:
++       service: srv
++     mtx-api:
++       service: srv
 ```
-helm upgrade bookshop ./chart --install -f values.yaml
+
+5. Add your image registry secret created in [Create container registry secret](#create-container-registry-secret) step.
+
+```diff
+global:
+  domain: null
+-  imagePullSecret: {}
++  imagePullSecret:
++    name: container-registry
 ```
 
-### Access the UI
+### Deployment
+
+Deploy the helm chart using the following command:
+
+#### Single Tenant
+
+```bash
+helm install bookshop ./chart --set-file xsuaa.jsonParameters=xs-security.json
+```
 
 Before you can access the UI you should make sure to [Setup Authorizations in SAP Business Technology Platform](#setup-authorizations-in-sap-business-technology-platform).
 
-1. Create a Launchpad Service subscription in the BTP Cockpit
-2. Go to **HTML5 Applications**
-3. Start any of the HTML5 applications
+Click on the approuter url logged by the `helm install` to access the UI.
+
+#### Multi Tenant
+
+```bash
+helm install bookshop ./chart --set-file xsuaa.jsonParameters=xs-security-mt.json
+```
 
-Additionally, you can add the UIs to a Launchpad Service site like it is described in in the last two steps of [this tutorial](https://developers.sap.com/tutorials/btp-app-kyma-launchpad-service.html#9aab2dd0-18ea-4ccd-bc44-24e87c845740).
+In case of multi tenant, you'll have to subscribe to the application from a different subaccount. You can follow the steps mentioned [here](https://cap.cloud.sap/docs/guides/deployment/as-saas#subscribe) to access the application.
 
 ## Setup Authorizations in SAP Business Technology Platform