CX Works

A single portal for curated, field-tested and SAP-verified expertise for your SAP C/4HANA suite. Whether it's a new implementation, adding new features, or getting additional value from an existing deployment, get it here, at CX Works.

Working with Local Instances of SAP Commerce Cloud and Project "Kyma"

Enjoy the benefits of working locally with SAP Commerce Cloud and Project "Kyma"


Please note: these instructions are only applicable to "Kyma" 1.3.0 and later - they will not work with earlier versions. You will also require SAP Commerce Cloud version 1905 or later.

SAP Cloud Platform Extension Factory is the cloud-native application extensibility framework for the SAP C/4HANA Suite, powered by open-source project "Kyma". It allows you to extend and customize your SAP C/4HANA solutions in a quick and modern way, using serverless computing and microservice architectures. One of the key components of the SAP Cloud Platform Extension Factory runtime is the Application Connector which provides a mechanism to simplify the connection between external systems and "Kyma" in a secure manner.

Once the initial connection has been established, the registration of the external Events and APIs of the external system takes place. The Events and APIs are then available within the "Kyma" Service Catalog. The SAP Cloud Platform Extension Factory Integration Module for SAP Commerce Cloud provides features that registers Events and APIs from SAP Commerce Cloud to SAP Cloud Platform Extension Factory. The one-click integration allows you to connect the SAP Commerce Cloud platform to the Application Connector.

Sometimes you may not have access to cloud-based instances of either SAP Commerce Cloud or "Kyma" - for example, you may want to prototype something quickly on your local machine. This articles outlines the steps you need to take in order to successfully connect a local SAP Commerce Cloud instance with a local "Kyma" runtime.

Table of Contents

Introduction

Installing and running a local instance of "Kyma" is a great way to learn about its key features and to begin to explore the possibilities of using it for side-by-side extension of the SAP C/4HANA Suite. If you want to connect it to a locally-running instance of SAP Commerce Cloud, there are a couple of extra steps you'll need to take before you can start using the events and APIs from SAP Commerce Cloud in your "Kyma" lambdas and microservices.

This article assumes that you have successfully installed a local instance of SAP Commerce Cloud 1905 that includes the SAP Cloud Platform Extension Factory Integration Module, as detailed in this SAP Help document.

It also assumes that you have successfully installed "Kyma" (at least version 1.3.0) on your local machine using Minikube as per the "Kyma" installation instructions. In particular, make sure you follow the post installation step regarding adding the "Kyma" self-signed certificate to your OS trusted certificates.

The Challenges

There are two principle challenges you will face when trying to connect a local SAP Commerce Cloud instance with a local "Kyma" instance:

  1. How your "Kyma" instance running inside Minikube can resolve the DNS of your local SAP Commerce Cloud instance
  2. How "Kyma" and SAP Commerce Cloud will trust each other given that both by default use a self-signed TLS certificate

For the first issue, we need to determine an IP address that "Kyma" can use to connect to your local SAP Commerce Cloud, and use that IP address in the required property in your SAP Commerce Cloud local.properties file.

For the second issue, we need to import the "Kyma" self-signed certificate into the trusted certificate storage of our programming environment (SAP Commerce Cloud / Java) and then override the default configuration settings of some of the "Kyma" components to allow for what would otherwise be treated as an "insecure" connection. 

Connecting the Two Systems Together

1. Determine a DNS Value for SAP Commerce Cloud that Works Within Minikube


You first need to determine the IP address that your Minikube cluster will use to contact your local SAP Commerce Cloud instance - "Kyma" needs this in order to retrieve and register the SAP Commerce Cloud events and APIs within the "Kyma" Service Catalog:

minikube ssh -- ip route show


You are looking for the default via IP address - this is typically 192.168.64.1:



Add this IP address to your /path/to/commerce/hybris/config/local.properties file in the format shown in the following example:

local.properties
ccv2.services.api.url.0=https://local-192-168-64-1.nip.io:${tomcat.ssl.port}		

You can read more about this DNS resolution mechanism at nip.io.


Also make sure the apiregistryservices.events.exporting property is set to true, otherwise your local SAP Commerce Cloud instance won't export any events even if they are triggered:

local.properties
apiregistryservices.events.exporting=true


2. Import "Kyma" Certificate and Override Defaults to Allow Insecure Connections

a. Import the "Kyma" server certificate into the local trust store

As per the "Kyma" documentation, to access the Application Connector on a local deployment of "Kyma", you must add the "Kyma" server certificate to the trusted certificate storage of your programming environment. For example, to access the Application Connector from a Java environment, run this command to add the "Kyma" server certificate to the default Java trust store:

curl -LO https://raw.githubusercontent.com/kyma-project/kyma/<KYMA VERSION or master for latest>/installation/certs/workspace/raw/server.crt
"${JAVA_HOME}/bin/keytool" -keystore ${JAVA_HOME}/lib/security/cacerts -storepass changeit -import -file server.crt -alias kyma-local


If you are only interested in working with "Kyma" from a local SAP Commerce Cloud instance, a better option is to add the "Kyma" server certificate to the SAP Commerce Cloud-specific developer trust store that is configured in /path/to/hybris/bin/platform/resources/advanced.properties:

application.properties
# Additional trust store. If configured the trust store (in the JKS format) is added as a fallback trust store to the default one provided
# by the JVM. Its intention is to provide a trusted self-signed CA certificate for developers/testers convenience.
additional.javax.net.ssl.trustStore=${platformhome}/resources/devcerts/ydevelopers.jks
additional.javax.net.ssl.trustStorePassword=123456


To add the "Kyma" server certificate to this trust store, run this command:

curl -LO https://raw.githubusercontent.com/kyma-project/kyma/master/installation/certs/workspace/raw/server.crt
"${JAVA_HOME}/bin/keytool" -keystore /path/to/hybris/bin/platform/resources/devcerts/ydevelopers.jks -storepass 123456 -import -file server.crt -alias kyma-local


You also then need to add the following properties to your /path/to/commerce/hybris/config/local.properties:

local.properties
kymaintegrationservices.truststore.cacerts.path=${platformhome}/resources/devcerts/ydevelopers.jks
kymaintegrationservices.truststore.password=123456


b. Override "Kyma" defaults to disable TLS verification

As per the "Kyma" documentation:

To provide maximum security, the Application Connector uses TLS protocol with Client Authentication enabled. As a result, whoever wants to connect to the Application Connector must present a valid client certificate, which is dedicated to a specific Application (App). In this way, the traffic is fully encrypted and the client has a valid identity.

By default, a local version of SAP Commerce Cloud will use a self-signed certificate, and therefore be treated as untrusted by the Application Connector in "Kyma". To get around this issue, we can disable the SSL certificate verification in the communication between "Kyma" and your local SAP Commerce Cloud by patching two of the "Kyma" components - the Application Registry and the Application Gateway.

Execute the following commands using the Kubernetes CLI tool kubectl.


First patch the Application Registry:

Patch application-registry
kubectl -n kyma-integration patch deployment application-registry --type json -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value":"--insecureSpecDownload=true"}]'


Wait until the pod restarts:

Watch application-registry pod
# ctrl-c when the new pods are RUNNING / old pods have TERMINATED
kubectl -n kyma-integration get pod --watch -l app=application-registry


Create a new Application in "Kyma" to represent your local Commerce Cloud instance as shown below. Wait until its status is SERVING.



You now need to patch the Application Gateway that is created when you create this Application in "Kyma". Replace <APPLICATION_NAME> with whatever you called your Application when you created it in the previous step:

Patch application-gateway
kubectl -n kyma-integration patch deployment <APPLICATION_NAME>-application-gateway --type json -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value":"--skipVerify=true"}]'


Wait until the pod restarts:

Watch application-gateway pod
# ctrl-c when the new pods are RUNNING / old pods have TERMINATED
kubectl -n kyma-integration get pod --watch -l app=<APPLICATION_NAME>-application-gateway


Now you can follow the standard SAP Commerce Cloud - "Kyma" pairing process, as documented here.

You should see the following entries in your SAP Commerce Cloud console as it requests and retrieves the certificate from "Kyma":




Your SAP Commerce Cloud console should then show the server registering its events and APIs with "Kyma", and "Kyma" reply with response code 200:




Once the registration process has completed, you should see all the registered SAP Commerce Cloud events and APIs in your "Kyma" Application:



Troubleshooting

The following are some sample error messages you might see while trying to connect your local SAP Commerce Cloud instance with a local "Kyma" instance:




Conclusion

This article has introduced you to the steps you need to take to connect a local instance of SAP Commerce Cloud with a local "Kyma" runtime. You can now explore the possibilities of side-by-side extensibility for SAP Commerce Cloud by introducing new functionality and innovation without having to do in-app customizations.

For more information about using SAP Cloud Platform Extension Factory with the SAP C/4HANA Suite, please see the following references: