Overview

This sample provides a CAP Service application service which displays orders. Within the service a CDS action is used to call an external application. This application generates an order which is then saved into the database. Deployment to Kyma is done using a Helm chart generated by CAP. Within Kyma, the external application is being accessed using a BTP Destination via the Cloud Connector.

This sample demonstrates how to:

• Configure the CAP application to run locally
• Configure and build docker images using Paketo
• Generating a Helm chart with the CAP tooling which includes
  • Connecting a CAP application to Hana Cloud
  • Creating an XSUAA service instance
  • Creating a Destination service instance
  • Creating a Connectivity proxy service instanace
  • Creating a HTML5 Repository service instance
  • Configuration of the app in an approuter instance running in Kyma
  • Configuration of the app in the Fiori Launchpad

Prerequisites

• SAP BTP, Kyma runtime instance
• Docker
• Docker Hub Account
• Node.js
• kubectl configured to use the KUBECONFIG file downloaded from the Kyma runtime.
• Paketo
• SAP Cloud Connector
• UI5 Tooling

Steps

Run the frontend locally

1. Clone the project.

2. Inside the app directory, run:

npm install

3. Install the CAP tools - version @sap/cds-dk@6.3.2 was used at the time of creating this example

npm i -g @sap/cds-dk

4. Verify the CAP tools install by running

cds

5. Run the app using the command

cds watch

The application loads at http://localhost:4004 and is configured with dummy authentication and can be accessed using user: kyma password: kyma

The file request.http can also be used to call the service which requires REST Client for Visual Studio Code to be installed.

curl http://localhost:4004/orders/Orders -u kyma:kyma

Run the mock appliction locally

This example relies on the mock application found in the connectivity-proxy. Following the instructions to run this application locally. The mock application is accessed by calling the following action of the CAP application.

curl -X POST http://localhost:4004/orders/external -u kyma:kyma -H "Content-Type: application/json" -d '{"orderNo":100}'

Creating the Destination

This sample will rely on the Destination service to obtain the details of the localmock system. Within your BTP subaccount, choose the menu option Connectivity -> Destinations. Choose the option to import and import the file destination. The CAP applications expects the name of the destination to be localmock.

Configure the SAP Cloud Connector

Following the instructions to configure the localmock application within the SAP Cloud Connector found in the mock application sample at connectivity-proxy

Provising the HANA Database

⚠ NOTE: The creation of the instance will take some time. Also please note that when using the SAP BTP trial, the HANA instance will need to be restarted each day.

1. In the SAP BTP global account choose Entitlements -> Entity Assignments. Choose your subaccount and choose Go. This will list all assigned entitlements.
2. Choose Configure Entitlements and Add Service Plans to select additional entitlements.
3. For the Entitlement choose

• SAP HANA Cloud and choose the Plan tools
• SAP HANA Schemas & HDI Containers and choose the Plan hdi-shared

4. Create the HANA Cloud Instance by choosing within the the subaccount view, open Services -> Service Marketplace
5. Choose Create and choose the Plan tools
6. Assign the Role Collection SAP HANA Cloud Administrator to your user
7. Open Services -> Instances and Subscriptions and choose the SAP HANA Cloud application which opens the SAP HANA Cloud Central
8. Choose the option to Create Instance and choose...
9. SAP HANA Cloud, SAP HANA Database, choose Next
10. Provide an Instance Name and a Password, choose Next
11. Choose Next
12. Choose Next
13. SAP HANA Database Advanced Settings - set Allowed connections to Allow all IP addresses, choose Next. To restrict IP access, the following command can be used to determine the IP addresses of Kyma

    kubectl run -i --tty busybox --image=yauritux/busybox-curl --restart=Never
    curl ifconfig.me/all
    

14. Choose Review and Create
15. Choose Create Instance

Map Kyma Instance to the HANA DB

For this we will need the Environment Instance ID of the Kyma runtime environment.

1. In the Kyma dashboard choose the menu option Namespaces and open the Namespace kyma-system
2. Choose the menu option Configuration -> Config Maps, and search for sap-btp-operator-config
3. Open the config map and copy the value CLUSTER_ID
4. In the SAP HANA Cloud Central, choose the ellipse of your Instance and choose Manage Configuration
5. Choose Edit found at the top right, then choose the tab Instance Mapping
6. Choose Add Mapping, choose Kyma for the Environment Type, provide the Cluster ID copied from step three and provide the namespace dev from the Environment Group
7. Choose Save

Create the SAP HANA Schemas & HDI Container

⚠ NOTE: The step requires that the creation of the SAP HANA Cloud has completed.

1. Create a new dev Namespace:

kubectl create namespace dev
kubectl label namespaces dev istio-injection=enabled

2. Create the schema instance and binding by running

kubectl -n dev apply -f ./k8s/hana-db-schema.yaml

Prepare the app for deployment

1. Within the directory app, run the command to build the for production

cds build --production

2. Build the service container using paketo

pack build <dockerid>/orders-srv --path gen/srv --builder paketobuildpacks/builder:base

3. Build the database deployer container using paketo

pack build <dockerid>/orders-hana-deployer --path gen/db --builder paketobuildpacks/builder:base

4. Push the two images to your docker account.

docker push <dockerid>/orders-srv
docker push <dockerid>/orders-hana-deployer

Prepare the Helm chart

1. Within the directory app, run the command to add the helm feature to the project

cds add helm

2. Within the directory app, run the command to add the XSUAA feature to the project. This will result in an XSUAA instance being created when the helm chart is deployed.

cds add xsuaa

3. Within the directory app, run the command to add the Connectivity feature to the project. This will result in an Connectivity Proxy instance being created when the helm chart is deployed. The the Connecitivity Proxy is used to communicate to the SAP Cloud Connector.

cds add connectivity

4. Within the directory app, run the command to add the Destinations feature to the project. This will result in an Destinations instance being created when the helm chart is deployed. This is used to obtain the details of the localmock destination.

cds add destinations

Configure the Helm chart

1. Open the file app/chart/values.yaml and provide the values

   1. Domain: your kyma cluster-domain
   2. Repository: your docker/repository account
   3. imagePullSecret.name: if using a secured docker/repository account provide the secret name, otherwise leave as defined
   4. srv.bindings.db.fromsecret: orders-db
   5. hana_deployer.bindings.hana.fromSecret: orders-db
   6. srv.bindings.destinations.serviceInstanceName: destination

2. Open the file app/chart/charts/web-application and adjust the value

   1. port: 4004

Deploy the app to Kyma

1. helm upgrade --install orders ./chart --namespace dev

Testing the application

The CAP application will be bound to an XSUAA instance which will handle the authentication. The values: url, clientid, and clientsecret will be needed to create a request to obtain an access token. This can be obtained within the Kyma dashboard by finding the secret orders-srv-auth under the menu option Configuration -> Secrets and using the option to Decode the value. The request to call the remote APIs can also be found in request.http.

1. To use curl within a shell.

export URL=$(kubectl get secrets/orders-srv-auth -n dev -o jsonpath="{.data.url}" | base64 -d)
export CLIENTID=$(kubectl get secrets/orders-srv-auth -n dev -o jsonpath="{.data.clientid}" | base64 -d)
export CLIENTSECRET=$(kubectl get secrets/orders-srv-auth -n dev -o jsonpath="{.data.clientsecret}" | base64 -d)

2. Run the command, which utilizes jq to extract the access_token from the response.

export ACCESSTOKEN=$(curl --location --request POST $URL/oauth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id='$CLIENTID \
--data-urlencode 'client_secret='$CLIENTSECRET \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'response_type=token' | jq -r '.access_token' )

3. Pass the access_token when calling the endpoint using curl

curl https://orders-srv-dev.<cluster domain>/orders/Orders --header 'Authorization: Bearer '$ACCESSTOKEN

4. Call the CDS action which calls mocked service and creates an new order.

curl -X POST  https://orders-srv-dev.<cluster domain>/orders/external --header 'Authorization: Bearer '$ACCESSTOKEN --header "Content-Type: application/json" -d '{"orderNo": 1231123}'

This should return a response similar to

{"@odata.context":"$metadata#OrdersService.return_OrdersService_external","affectedRows":1,"orders":[{"ID":"027e2eb5-8a22-4ad2-9ff9-abfd3bf6da4d"}]}

Prepare the UI application

1. In this step a UI application will be added to the helm chart. The helm chart will generate a service instance of the html5-apps-repo which is used to push the UI application to the HTML5 Repository service. This can later be configured to use the SAP Lauchpad service. Start by installing the UI5 tooling which is used to build the UI5 application.

npm install --global @sap/ux-ui5-tooling

2. To build the UI application run the following command in the directory app/app/orders

ui5 build --dest ../../../html5-deployer/resources/webapp --clean-dest true

3. Copy the file xs-app.json into the directory html5-deployer/resources. Within the directory app/app run

cp xs-app.json ../../html5-deployer/resources/webapp

4. Steps two and three will have added the built UI5 application and the xs-app.json to the directory html5-deployer. This directory defines the html5-app-deployer which is deployed as a Kubernetes job which publishes the UI5 application to the HTML5 Repository service. To build the container run the following command in the html5-deployer directory.

pack build <dockerid>/orders-html5-deployer --workspace app --buildpack gcr.io/paketo-buildpacks/nodejs --builder paketobuildpacks/builder:base

5. Push the image to your container repository

docker push <dockerid>/orders-html5-deployer

6. Add the html5_apps_deployer feature to helm chart by running the following command in the app directory.

cds add html5-repo

7. Configure the Helm chart by opening the file app/chart/values.yaml and provide the values

   1. html5_apps_deployer.image.repository: your docker/repository account

   2. html5_apps_deployer.cloudService: cpapp.service

   3. html5_apps_deployer.backendDestinations: see code block

      html5_apps_deployer:
        cloudService: cpapp.service
        backendDestinations:
           srv-api:
              service: srv
      

Update the helm chart, by running the following command in the directory app

helm upgrade --install orders ./chart --namespace dev

8. Once the chart installation completes you will find the UI5 application by opening the SAP CTP Cockpit and choosing HTML5 Applications. The application will be named comkymademoorders. Click on the application name to open it.

Access HTML5 via approuter running in Kyma

1. Undeploy the example

helm uninstall orders --namespace dev

2. Open the file app/chart/values.yaml and add the property

3. xsuaa.parameters.tenant-mode: dedicated

4. Open the file app/chart/xs-security.json and add the property oauth2-configuration, replacing the value {CLUSTER_DOMAIN} with your cluster domain as shown

{
  "scopes": [],
  "attributes": [],
  "role-templates": [],
  "oauth2-configuration": {
    "redirect-uris": [
      "https://orders-srv-cap-approuter.{CLUSTER_DOMAIN}/**"
    ]
  }
}

4. Redeploy the example

helm upgrade --install orders ./chart --namespace dev

5. Create the service instance and binding for the html5-apps-runtime

kubectl apply -f k8s/app-router-html5-repo.yaml -n dev

6. Deploy the app router deployment

kubectl apply -f k8s/app-router.yaml -n dev

7. Open the file k8s/app-router-apirule.yaml add replace {CLUSTER_DOMAIN} with your cluster domain. Apply the apirule

kubectl apply -f k8s/app-router-apirule.yaml -n dev

8. Verify that the contents of the data.xs-app.json property found in k8s/app-router-cm.yaml. Notice that the target entry for html5-apps-repo-rt is targeting the html5 application comkymademoorders Apply the config map

kubectl apply -f k8s/app-router-cm.yaml -n dev

9. Once started the application will be available at

https://orders-srv-cap-approuter.{CLUSTER_DOMAIN}/

Add application to the SAP Launchpad

1. Within your SAP BTP subaccount choose Service Marketplace. Select the Launchpad Service and choose Create.

2. Assign the role for the Launchpad Service by choosing Security -> Users in the subaccount. Then choose your user and the option Assign Role Collection.

3. Assign the value Launchpad_Admin to the user.

4. Within the SAP BTP subaccount choose Services -> Instances and Subscriptions. Choose Launchpad Service found under Subscriptions and Go to Application.

5. Choose Create Site and provide name Kyma. Choose the < at the top left to leave the Site Settings and navigate back to Site Directory.

6. In the left hand menu choose Channel Manager . Under Actions choose the refresh option.

7. Choose Content Manager and then Content Explorer at the top menu.

8. Choose HTML5 Apps and select the application Orders and choose Add to My Content.

9. Choose My Contentand then New -> Group. Provide Kyma as the Title and assign Orders as the app. Choose Save.

10. Choose the arrow button < to go back. Choose the role Everyone and choose Edit and assign Orders as the app and Save.

11. Choose Site Directory and then the option to Go to Site.