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 Blue-Green Deployment process.
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.
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:
- cloud-hdi-zdm-ref-app.blue/mta-jee. Blue version of MTA archive (.mtar) file.
- cloud-hdi-zdm-ref-app.green/mta-jee. Green version of MTA archive (.mtar) file.
Each version of the reference application contains database (db) module and backend 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:
- cloud-hdi-zdm-ref-app.db.blue. Contains blue version of database module.
- 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.
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:
- cloud-hdi-zdm-ref-app.backend.jee.blue. Contains blue version of backend module.
- cloud-hdi-zdm-ref-app.backend.jee.green. Contains green version of backend module.
- Git version 2.19.1 or newer version.
- Apache Maven version 3.3.9 or newer version.
- 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
). - Cloud Foundry Command Line Interface (cf CLI) version 6.34.1 or newer version.
- CF MTA CLI Plugin version 2.0.7 or newer version.
- Get access to SAP Cloud Platform Cloud Foundry (SAP CP CF) or SAP XS Advanced (XSA) on-premise environment, by following the linked guides.
- Login to the SAP CP CF environment or 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.
- The reference application requires a HANA service instances for persistence.
- For SAP CP CF Enterprise account you should create SAP HANA Tenant Database in your organization and space or share SAP HANA Tenant Database in your organization and space.
- For SAP CP CF Trial account you need to bind a shared SAP HANA tenant database service.
- For SAP XSA the SAP HANA database instance is provided out of the box.
- Clone the repository
$ git clone https://github.com/SAP/cloud-hdi-zdm-reference-app.git && cd ./cloud-hdi-zdm-reference-app
- 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=CF --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
- 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=CF --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
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.
- Deploy blue version
$ cf bg-deploy ./cloud-hdi-zdm-ref-app.blue/mta-jee/cloud-hdi-zdm-ref-app-blue-<version>.mtar -e config.mtaext
-
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>"}}`
- Deploy green version
$ cf bg-deploy ./cloud-hdi-zdm-ref-app.green/mta-jee/cloud-hdi-zdm-ref-app-green-<version>.mtar -e config.mtaext
-
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>"}}`
-
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 forUse "cf bg-deploy -i <process id> -a resume" to resume the process.
. After you found it you should execute it:
$ cf bg-deploy -a resume -i <process id>
-
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`
- 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.
If you need any support, have any question or have found a bug, please report it in the GitHub bug tracking system.
This project is licensed under SAP SAMPLE CODE LICENSE AGREEMENT except as noted otherwise in the LICENSE file.