Important Notice

This public repository is read-only and no longer maintained.

Cloud HDI ZDM Reference Application

Description

Cloud HDI (HANA Deployment Infrastructure) ZDM (Zero-Downtime Maintenance) Reference Application, or cloud-hdi-zdm-ref-app, demonstrates how to develop Multi-Target Applications with HDI content, which support zero-downtime updates. It is based on the Muti-Target Application (MTA) model and follows the Zero-Downtime Maintenance (ZDM) Adoption Guideline in order to support zero-downtime updates. The update is done by following the Blue-Green Deployment process.

Blue-green deployment

This repository contains two versions of the reference application: blue and green. The green version contains changes on top of the blue version. The blue and green versions of the reference application are Muti-Target Applications (MTAs). Zero-downtime update is demonstrated by updating the blue version of the application to the green version, following the blue-green deployment process of MTAs. The blue-green deployment of MTAs is supported on SAP Cloud Platform Cloud Foundry (SAP CP CF) and SAP XS Advanced (XSA) environments. Both environments are following the Cloud Foundry concepts, so the user and development experience is identical. Note, however, that zero-downtime maintanance of HDI content is only supported on XSA.

The blue and green versions of the reference application are build independently by the MTA Archive Builder. The result from the build of each version of the application is MTA archive (.mtar) file. The build results are located at:

1. cloud-hdi-zdm-ref-app.blue/mta-jee. Blue version of MTA archive (.mtar) file.
2. cloud-hdi-zdm-ref-app.green/mta-jee. Green version of MTA archive (.mtar) file.

Components of the reference application

Each version of the reference application contains database (db) module and backend module.

Database module

The database module contains database artifacts, which are modeled in specific ZDM manner. The SAP HANA Deployment Infrastructure (HDI) provides a service that enables you to deploy database artifacts to so-called containers. After deployment the artifacts are materialized to database objects, which represent the persistence model of the application. The source code of the blue and green versions of the database modules is located at:

1. cloud-hdi-zdm-ref-app.db.blue. Contains blue version of database module.
2. cloud-hdi-zdm-ref-app.db.green. Contains green version of database module. It contains compatible and incompatible database changes on top of the blue version.

Backend module

The backend module is a Java web application, which consumes the database objects and provides REST API. The source code of the blue and green versions of the backend modules is located at:

1. cloud-hdi-zdm-ref-app.backend.jee.blue. Contains blue version of backend module.
2. cloud-hdi-zdm-ref-app.backend.jee.green. Contains green version of backend module.

Requirements

1. Git version 2.19.1 or newer version.
2. Apache Maven version 3.3.9 or newer version.
3. MTA Archive Builder version 1.1.7 or newer version. You can find more information for the MTA Archive Builder here. Currently it is a java archive (.jar) file. Place it in your home folder (~/mta-archive-builder.jar).
4. XSA Command Line Interface (xs CLI) version 1.0.99 or newer version.
5. Get access to SAP XS Advanced (XSA) on-premise environment, by following the linked guides.
6. Login to the SAP XSA environment. You can find more information for the login command here. After login an organization and space are targeted. The reference application will be deployed in this organization and space.
7. The reference application requires HANA service instances for persistence. For SAP XSA, the SAP HANA database instance is provided out of the box.

Download and Installation

1. Clone the repository

$ git clone https://github.com/SAP/cloud-hdi-zdm-reference-app.git && cd ./cloud-hdi-zdm-reference-app

2. Build blue version of cloud-hdi-zdm-ref-app

$ cd ./cloud-hdi-zdm-ref-app.blue/mta-jee/
$ java -jar ~/mta-archive-builder.jar --build-target=XSA --mtar=cloud-hdi-zdm-ref-app-blue-<version>.mtar build
$ cd ../../
$ # The result from the build is located at ./cloud-hdi-zdm-ref-app.blue/mta-jee/cloud-hdi-zdm-ref-app-blue-<version>.mtar

3. Build green version of cloud-hdi-zdm-ref-app

$ cd ./cloud-hdi-zdm-ref-app.green/mta-jee/
$ java -jar ~/mta-archive-builder.jar --build-target=XSA --mtar=cloud-hdi-zdm-ref-app-green-<version>.mtar build
$ cd ../../
$ # The result from the build is located at ./cloud-hdi-zdm-ref-app.green/mta-jee/cloud-hdi-zdm-ref-app-green-<version>.mtar

Running

This section applies the blue-green deployment process step by step and demonstrates how a zero-downtime update of the cloud-hdi-zdm-ref-app can be achieved.

1. Deploy blue version

$ xs bg-deploy ./cloud-hdi-zdm-ref-app.blue/mta-jee/cloud-hdi-zdm-ref-app-blue-<version>.mtar -e config.mtaext

2. Test blue version on live URL

   After the blue version is deployed it can be tested by checking the web resource exposed by the cloud-hdi-zdm-ref-app-backend-blue module. The URL of the web resource is printed in a progress message in the console. Search for message: Application "cloud-hdi-zdm-ref-app-backend-blue" started and available at <live URL>. This URL is the so called "live URL", because it is publicly available and customers can use it. Execute the following command to test the blue version on the live URL:

$ curl <live URL (cloud-hdi-zdm-ref-app-backend-blue)>/api/v1/cdsPerson/version -k
$ # The response should be `BLUE`

$ curl <live URL (cloud-hdi-zdm-ref-app-backend-blue)>/api/v1/cdsPerson -k
$ # The response should be `{"cdsPerson":{"id":<ID>,"firstName":"FirstName <ID>","lastName":"LastName <ID>"}}`

3. Deploy green version

$ xs bg-deploy ./cloud-hdi-zdm-ref-app.green/mta-jee/cloud-hdi-zdm-ref-app-green-<version>.mtar -e config.mtaext

4. Test green version on idle URL

   Now both the blue and green versions are deployed and run simultaneously, but expose their web resources on different URLs. The green version can be tested by checking the web resource exposed by the cloud-hdi-zdm-ref-app-backend-green module. The URL of the web resource is printed in a progress message in the console. Search for message: Application "cloud-hdi-zdm-ref-app-backend-green" started and available at <idle URL>. This URL is the so called "idle URL", because it is not publicly available and customers can not use it. It can be used only internally to test whether the green version of the application is production-ready. If it is production-ready - the blue-green deployment process can be resumed, if not - the blue-green deployment process should be aborted. The resume and abort commands are printed as progress messages in the console. Execute the following commands to test the green version on the idle URL:

$ curl <idle URL (cloud-hdi-zdm-ref-app-backend-green)>/api/v1/cdsPerson/version -k
$ # The response should be `GREEN`

$ curl <idle URL (cloud-hdi-zdm-ref-app-backend-green)>/api/v1/cdsPerson -k
$ # The response should be `{"cdsPerson":{"id":<ID>,"firstName":"FirstName <ID>","lastName":"LastName <ID>"}}`

5. Resume the blue-green deployment process

   After the cloud-hdi-zdm-ref-app-backend-green application is tested, the blue-green deployment process can be resumed. The exact command is printed as a progress message in the console. Search for Use "xs bg-deploy -i <process id> -a resume" to resume the process.. After you found it you should execute it:

$ xs bg-deploy -a resume -i <process id>

6. Test green version on live URL

   After the blue-green process is resumed the blue version of the cloud-hdi-zdm-ref-app is deleted and the live URL is switched from the blue to the green version of the application. Now customers can access the publicly available web resource exposed by the green version of the application. Execute the following commands to test the green version on the live URL:

$ curl <live URL (cloud-hdi-zdm-ref-app-backend-green)>/api/v1/cdsPerson/version -k
$ # The response should be `GREEN`

$ curl <live URL (cloud-hdi-zdm-ref-app-backend-green)>/api/v1/cdsPerson -k
$ # The response should be `{"cdsPerson":{"id":<ID>,"firstName":"Fname <ID>","lastName":"LastName <ID>"}}`

$ curl <idle URL>/api/v1/cdsPerson -k
$ # The response should be `HTTP: 404`

Known Issues

• Currently there is one backend module implemented in Java. In future will be provided more backend modules implemented in different languages, like Node.js, Python, etc.

How to obtain support

If you need any support, have any question or have found a bug, please report it in the GitHub bug tracking system.

License

Copyright (c) 2020 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.

Further reading

• ZDM for Multi-Target Applications (MTA) with Database Changes on SAP XSA
• Muti-Target Application (MTA) model
• Maintaining HDI Containers