Helm Chart (#152)

Co-authored-by: Marc Becker <marc.becker@sap.com>

Author: uwe-klinger

.gitignore

@@ -4,6 +4,8 @@ schema.sql
 schema-nomocks.sql
 default-env.json
 openapi.json
+.env
+.values.yaml
 
 bin/
 target/
@@ -31,4 +33,6 @@ hs_err*
 
 *.db
 
-.cdsrc-private.json
+.cdsrc-private.json
+
+/chart/

README.md

@@ -21,7 +21,9 @@ Welcome to the bookshop-java project. It demonstrates how to build business appl
   - [Using IntelliJ Idea (Community and Ultimate)](#using-intellij-idea-community-and-ultimate)
   - [Database Setup and Spring Profiles](#database-setup-and-spring-profiles)
   - [API_BUSINESS_PARTNER Remote Service and Spring Profiles](#api_business_partner-remote-service-and-spring-profiles)
-  - [Deploy to SAP Business Technology Platform](#deploy-to-sap-business-technology-platform)
+  - [Deploy to SAP Business Technology Platform, Cloud Foundry](#deploy-to-sap-business-technology-platform-cloud-foundry)
+  - [Deploy to SAP Business Technology Platform, Kyma Runtime](#deploy-to-sap-business-technology-platform-kyma-runtime)
+  - [Setup Authorizations in SAP Business Technology Platform](#setup-authorizations-in-sap-business-technology-platform)
 - [Code Tour](#code-tour)
 - [Get Support](#get-support)
 - [License](#license)
@@ -195,7 +197,7 @@ The behavior of the API_BUSINESS_PARTNER remote service is controlled using prof
 
 The profiles `sandbox` and `destination` can be combined with the `default` profile for [hybrid testing](https://cap.cloud.sap/docs/advanced/hybrid-testing) and with the `cloud` profile when deployed to the cloud.
 
-## Deploy to SAP Business Technology Platform
+## Deploy to SAP Business Technology Platform, Cloud Foundry
 
 CAP Java applications can be deployed to the SAP Business Technology Platform either in single tenant or in multitenancy mode. See [Multitenancy in CAP Java](https://cap.cloud.sap/docs/java/multitenancy) for more information.
 
@@ -220,6 +222,179 @@ Deploy as Multitenant Application:
 - Go to another subaccount in your global account, under subscriptions and subscribe to the application you deployed.
 - Run `cf map-route bookshop-mt-app <YOUR DOMAIN> --hostname <SUBSCRIBER TENANT>-<ORG>-<SPACE>-bookshop-mt-app` or create and bind the route manually.
 
+Before you can access the UI using the (tenant-specific) URL to the bookshop(-mt)-app application, make sure to [Setup Authorizations in SAP Business Technology Platform](#setup-authorizations-in-sap-business-technology-platform).
+
+## Deploy to SAP Business Technology Platform, Kyma Runtime
+
+**TIP:** You can find more information in the [Deploy Your CAP Application on SAP BTP Kyma Runtime](https://developers.sap.com/mission.btp-deploy-cap-kyma.html) tutorial and in the [Deploy to Kyma/K8s](https://cap.cloud.sap/docs/guides/deployment/deploy-to-kyma) guide of the CAP documentation.
+
+### Preconditions
+
+- BTP Subaccount with Kyma Runtime
+- BTP Subaccount with Cloud Foundry Space
+- HANA Cloud instance available for your Cloud Foundry space
+- BTP Entitlements for: *HANA HDI Services & Container* plan *hdi-shared*, *Launchpad Service* plan *standard*
+- Container Registry
+- Command Line Tools: `kubectl`, `kubectl-oidc_login`, `pack`, `docker`, `helm`, `cf`
+- 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
+
+### Add Deployment Files
+
+CAP tooling provides your a Helm chart for deployment to Kyma.
+
+Add the CAP Helm chart with the required features to this project:
+
+```bash
+cds add helm:hana_deployer
+cds add helm:xsuaa
+cds add helm:html5_apps_deployer
+```
+
+#### Helm chart configuration
+
+This project contains a pre-configured configuration file `values.yaml`, you just need to do the following changes in this file:
+
+- `<your-container-registry>` - full-qualified hostname of your container registry
+- `domain`- full-qualified domain name used to access applications in your Kyma cluster
+
+#### Use API_BUSSINESS_PARTNER Remote Service (optional)
+
+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:
+
+    ```yaml
+    srv:
+      ...
+      bindings:
+        ...
+        destinations:
+          serviceInstanceName: destinations
+    ```
+
+    (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:
+
+    ```bash
+    cds add helm:connectivity
+    ```
+
+*See also: [API_BUSINESS_PARTNER Remote Service and Spring Profiles](#api_business_partner-remote-service-and-spring-profiles)*
+
+### Prepare Kubernetes Namespace
+
+#### Create container registry secret
+
+Create a secret `container-registry` with credentials to access the container registry:
+
+```
+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
+
+```
+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.
+
+### Build
+
+**Build data base deployer image:**
+
+```
+cds build --production
+
+pack build $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer \
+     --path db \
+     --buildpack gcr.io/paketo-buildpacks/nodejs \
+     --builder paketobuildpacks/builder:base
+```
+
+(Replace `$YOUR_CONTAINER_REGISTRY` with the full-qualified hostname of your container registry)
+
+
+**Build image for CAP service:**
+
+```
+mvn package
+```
+
+```
+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
+```
+
+**Build HTML5 application deployer image:**
+
+```
+bash ./scripts/build-ui-image.sh
+```
+
+### Push container images
+
+You can push all the container images to your container registry, using:
+
+```
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-hana-deployer
+
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-srv
+
+docker push $YOUR_CONTAINER_REGISTRY/bookshop-html5-deployer
+```
+
+### Deployment
+
+```
+helm upgrade bookshop ./chart --install -f values.yaml
+```
+
+### Access the UI
+
+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
+
+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).
+
+## Setup Authorizations in SAP Business Technology Platform
+
+To access services and UIs that require specific authorizations (e.g. `admin`) you need to assign a corresponding role and role collections to your user in SAP BTP Cockpit.
+
+1. For single-tenant applications open the subaccount where you deployed the `bookshop` application to. For multitenant applications open the subaccount where you subscribed to the `bookshop` application.
+2. Navigate to *Security* -> *Roles*
+3. Create a role with name `bookshop-admin` based on the `admin` role template of the `bookshop` application:
+    1. Enter a Business Partner ID of your S/4 system as value for the `businessPartner` attribute. When using the sandbox environment use `10401010`.
+4. Navigate to *Security* -> *Role Collections*
+5. Create a new role collection `bookshop-admin`:
+    1. Assign the `bookshop-admin` role to this role collection
+    2. Assign the role collection to your user
+
 # Code Tour
 
 Take the [guided tour](.tours) in VS Code through our CAP Samples for Java and learn which CAP features are showcased by the different parts of the repository. Just install the [CodeTour extension](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) for VS Code.

scripts/build-ui-image.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+set -e
+cd "$(dirname "$(dirname "$0")")"
+
+npm install --no-save yaml
+
+function value() {
+    node ./scripts/value.js "$1"
+}
+
+function image() {
+    local REPOSITORY="$(value "$1.image.repository")"
+    local TAG="$(value "$1.image.tag")"
+    if [ "$TAG" != "" ]; then
+        echo "$REPOSITORY:$TAG"
+    else
+        echo "$REPOSITORY"
+    fi
+}
+
+rm -rf gen/ui
+mkdir -p gen/ui/resources
+
+CLOUD_SERVICE="$(value html5_apps_deployer.cloudService)"
+DESTINATIONS="$(value html5_apps_deployer.backendDestinations)"
+
+IMAGE="$(image html5_apps_deployer)"
+
+for APP in app/*; do
+    if [ -f "$APP/webapp/manifest.json" ]; then
+        echo "Build $APP..."
+        echo
+
+        rm -rf "gen/$APP"
+        mkdir -p "gen/app"
+        cp -r "$APP" gen/app
+        pushd >/dev/null "gen/$APP"
+
+        node ../../../scripts/prepareUiFiles.js $CLOUD_SERVICE $DESTINATIONS
+        npm install
+        npx ui5 build preload --clean-dest --config ui5-deploy.yaml --include-task=generateManifestBundle generateCachebusterInfo
+        cd dist
+        rm manifest-bundle.zip
+        mv *.zip ../../../ui/resources
+
+        popd >/dev/null
+    fi
+done
+
+cd gen/ui
+
+echo
+echo "HTML5 Apps:"
+ls -l resources
+echo
+
+cat >package.json <<EOF
+{
+    "name": "ui-deployer",
+    "scripts": { "start": "node node_modules/@sap/html5-app-deployer/index.js" }
+}
+EOF
+
+npm install @sap/html5-app-deployer
+pack build $IMAGE --path . --buildpack gcr.io/paketo-buildpacks/nodejs --builder paketobuildpacks/builder:base

scripts/create-container-registry-secret.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+read -p "Docker Server: " DOCKER_SERVER
+
+read -p "User ($USER): " DOCKER_USER
+if [ "$DOCKER_USER" == "" ]; then
+    DOCKER_USER="$USER"
+fi
+
+if [ "$EMAIL" == "" ]; then
+    read -p "EMail: " DOCKER_EMAIL
+else
+    read -p "EMail ($EMAIL): " DOCKER_EMAIL
+    if [ "$DOCKER_EMAIL" == "" ]; then
+        DOCKER_EMAIL="$EMAIL"
+    fi
+fi
+
+read -sp "API Key: " API_KEY
+
+echo
+echo
+
+kubectl create secret docker-registry container-registry \
+    "--docker-server=$DOCKER_SERVER" \
+    "--docker-username=$DOCKER_USER" \
+    "--docker-email=$DOCKER_EMAIL" \
+    "--docker-password=$API_KEY"

scripts/create-db-secret.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+set -e
+cd "$(dirname "$(dirname "$0")")"
+
+npm install --no-save yaml
+
+function value() {
+    node ./scripts/value.js "$1"
+}
+
+NAME="$1"
+if [ "$NAME" == "" ]; then
+  NAME="$(value srv.bindings.db.fromSecret)"
+  if [ "$NAME" == "" -o "$NAME" == "<nil>" ]; then
+    echo >&2 "[ERROR] Please either specify the name for the DB secret or maintain it in the Helm chart"
+    exit 1
+  fi
+fi
+
+SECRET_HEADER="$(cat <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: $NAME
+type: Opaque
+stringData:
+  type: hana
+  label: hana
+EOF
+)"
+
+cf 2>/dev/null >/dev/null service $NAME || cf create-service hana hdi-shared $NAME
+while true; do
+    STATUS="$(cf 2>/dev/null service $NAME | grep status: | head -n 1)"
+    echo $STATUS
+    if [[ "$STATUS" = *succeeded* ]]; then
+        break
+    fi
+    sleep 1
+done
+
+cf create-service-key $NAME $NAME-key
+
+node "$(dirname "$0")/format-kyma-secret.js" -- "$(echo "$SECRET_HEADER")" "$(cf service-key $NAME $NAME-key)" | kubectl apply -f -
+echo
+echo "HANA DB Kubernetes secret '$NAME' created."
+echo
+echo "You can view it using:"
+echo
+echo "kubectl get secret $NAME -o yaml"
+exit 0

scripts/format-kyma-secret.js

@@ -0,0 +1,9 @@
+const key=JSON.parse(process.argv[4].replace(/^.*/, ""));
+const credentials=key.credentials /* new cfcli? */ || key;
+console.log(process.argv[3]);
+console.log(Object.keys(credentials).map(k => {
+    if (credentials[k].match(/\n/s))
+        return (`  ${k}: |\n${credentials[k]}`).replace(/\n/gs,"\n    ")
+    else
+        return `  ${k}: "${credentials[k]}"`
+}).join("\n"))