With this tutorial, you can deploy the fortune teller application in the CF platform. You can experience both - the classic cf push way of doing this and the new cf deploy. Even do a zero downtime update of the app with cf bg-deploy.
The name says it all - this simple example app will tell you a new fortune each time you refresh it’s web ui. No cookies are given yet. It’s setup consists of a few java spring apps and services depicted in the diagram.
Apps:
-
The fortune-teller-ui application serves some java script & static html ui and polls random 'fortunes' from the fortune service.
-
The fortune-teller-service application serves a fortune rest api, providing a single random fortune or the complete list of all fortunes. It consumes a backing database service.
-
The fortune-teller-hystrix-dashboard app is an optional component, providing a dashboard of the ui app’s circuit breaker
Services:
-
postgresql backing service - database holding the list of fortunes. For the purposes of this tutorial we’ll use a postgresql provided by the SAP Cloud Platform.
-
application logging service - integration with SCP collecting logs from applications and making them available on an ELK stack
This tutorial requires some resources in the cloud. If you don’t already have an Sap Cloud Platform user/account just open a landscape and one will automatically be created for you:
-
Open the SCP cockpit for an eu landscape and log on with your sap email and i/c/d-user password: https://account.hana.ondemand.com ; TODO: work out account reuse/authentication
Clone the repository, no account in github is required.
git -c http.sslVerify=false clone https://github.wdf.sap.corp/internetcafe/cf.push-cf.deploy.git cd cf.push-cf.deploy
|
Note
|
Changing the source code won’t be required. However, if you want to make changes, you can always rebuild the deployable content with maven. Maven may or may not be available on your machine. If it is, just run mvn clean install to build.
|
This tutorial requires the following command line tools which you already have pre-installed:
Before beginning, login to the platform and create your self a space to work in
cf api https://api.cf.eu10.hana.ondemand.com cf login -u <user.email>@sap.com -o cafe_mta / cf auth ... in case of technical user cf create-space <i/c/d/-user> -o cafe_mta cf target -o cafe_mta -s <i/c/d-user>
|
Important
|
The commands in the tutorial should be executed in the root of the repository |
|
Note
|
If already familiar with cf push via manifests, you may only review the [ manifest file ](manifest) and jump directly to: [3. Do the mta build & cf deploy] |
Let’s push to the cloud, the standard cf way.
|
Tip
|
Of the instructions below, creation of the app entities is possible with a single command cf push -f manifest. However, service creation, app reconfiguration and restart would still have to be executed manually. Follow the steps below to work on each, one step at a time.
|
The cf client marketplace command lists all available backing services SCP provides in your space. The services command lists all created service instances in the space.
The following create an application logs service instance with plan lite named 'fortune-logs' and a postgresql database one with a dev plan and name: 'fortune-service-database' .
cf marketplace cf create-service application-logs lite fortune-logs cf create-service postgresql v9.6-dev fortune-service-database cf services
*logs traced by apps, bound to an application logs service can be browsed in the platform’s application logging service 'kibana' ui
Now push the front-end application fortune-teller-ui with the following
cf push -f ./manifest-ui
*a cf push manifest file describes one or many apps with their properties like environment variables, memory configurations, bound services etc.
You can check out how your app looks like at it’s platform generated route.
List the app details to see it’s route and open it in a browser. look for route: <>
cf app ./fortune-teller-ui
The app url is constructed as the https protocol on that route: https://<route>; e.g. https://fortune-teller-ui-grumpy-wombat.cfapps.eu10.hana.ondemand.com
The app has no back-end to provide content yet; It’s circuit breaker(hystrix) should fall back to a default message and no new fortunes will come with refreshing. Let’s add a hystrix dashboard app to monitor how it behaves:
cf push -f ./manifest-hystrix
Let’s configure the dashboard with the front end app url via an environment variable:
cf set-env fortune-teller-hystrix-dashboard UIURL https://<fortune-teller-ui app route> cf restart fortune-teller-hystrix-dashboard
*a restart is required in order for the app to read it’s newly set environment variable.
|
Tip
|
Open the dashboard app in a browser too. You may verify that it works by refreshing the ui app page a few times while the dashboard page is opened. |
Let’s continue building the application with it’s back-end app. The previously created db service will automatically bind to the app as described in the manifest
cf push -f ./manifest-service
Now let’s tell the front end app where to reach the back end. You already found the ui app’s route. Find the backend app’s route and amend :443 (https port). Set it as FORTUNE_SERVICE_FQDN variable to the ui app:
|
Tip
|
the backend application route can be acquired with cf app fortune-teller-service as described in [ 2.3 Try the UI ].
|
cf set-env fortune-teller-ui FORTUNE_SERVICE_FQDN <route>:443 #e.g. cf set-env fortune-teller-ui FORTUNE_SERVICE_FQDN fortune-teller-service-wacky-potato.cfapps.eu10.hana.ondemand.com:443 cf restart fortune-teller-ui
Go back to the ui app and refresh it a couple times - each time a random fortune should be displayed for your destiny to follow.
Congratulations, you brought your application to life 🎉 !
The Multi Target Application model provides a powerful abstraction, capable of depicting complicated relationship between different platform entities. You may find detailed information in the SCP online documentation.
Have a look how the fortune teller app is described. Look for the mtad.yaml file in the root of the repository.
This descriptor is used when assembling, deploying/updating the application.
Let’s assemble an MTA archive! The mta archive is a (zip)package, containing the application’s full or partial deployable content. It is deployed at once with a single command. It’s versioned and may easily be transported and consistently applied to multiple environments e.g. dev/test/prod.
Assemlbe with the already installed mta build tool mbt:
mbt assemble
You’ll find a new directory mta_archives created in the project root. Inside is the new *.mtar archive.
|
Note
|
You can also assemble a complete mta archive on the fly just before deploying with the cf deploy --all-moduels --all-resources
|
Now simply deploy it to the cloud with the following command ⚡ :
cf deploy mta_archives/fortune-teller_0.0.1.mtar
That is it 🎉 !
|
Note
|
If you review the cf deploy command output, you’ll notice that application creation is happening in parallel, to optimize making deploy-times. Order may be controlled via modelling 'deployed-after' parameters in the mtad.yaml. |
|
Note
|
No additional reconfiguration is required either, as the dependencies are modelled in the mtad.yaml and the deployer takes care of them during the app creation. |
Ok, you did an initial deployment. Want to see how to update your app? This can be done with no down time by the mta blue green deployment 📗 📘 !
|
Note
|
There is a branch in this repo, with a modified fortune teller app. If you’d like to do your own changes to the app by changing the source and rebuilding ( mvn clean install ; mbt assemble ) .
|
git checkout 'green-version'
Instead of cf deploy this time run cf bg-deploy
cf bg-deploy mta_archives/fortune-teller_0.0.1.mtar
You now have two versions of the app running in parallel on different routes(idle and live). You may examine the new version of the application and verify it’s working correctly before switching the live version’s traffic to it. You should see minor changes in ui’s style & a cheesy message appended to the fortunes by the backend app.
After making sure it works as expected, run the following command. Find the deploy process id printed in the bg-deploy command output or via the cf mta-ops command.
cf bg-deploy -a resume -i <process_id>
Enjoy your new app version, deployed without down time 👏 !
|
Tip
|
You can run the blue-green deployment in one go, without manual test & resume. Leverage the 'zero downtime update' with the --no-confirm option
|
You’re almost done! To free up resources after the exercise, please remove everything created with the following:
cf undeploy fortune-teller --delete-services
Thank you for running through the cf push → cf deploy lab! We hope the experience was fun and useful.
TODO: elaborate on the value of cf push/cf deploy & cf bg-deploy.
If you have any feedback, don’t hasitate to find us in the project’s [slack channel](https://cloudfoundry.slack.com/?redir=%2Fmessages%2Fmultiapps-dev) or leave an issue at [project’s github.com repo](https://github.com/cloudfoundry-incubator/multiapps-controller/issues)
Find out more about the topic: