Skip to content

cf Multiapps tutorial over a slightly modified fortune-teller app fork

License

Notifications You must be signed in to change notification settings

ddonchev/multiapps-handson

Repository files navigation

From cf push to cf deploy

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.

About the fortune teller

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.

FortuneTeller

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

0 Prerequisites

Account in cf

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:

  1. 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

This repository

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.

Command line tools

This tutorial requires the following command line tools which you already have pre-installed:

1. Login to the platform

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 ⚠️

2. Do the cf push

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.

2.1 Backing services creation.

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

2.2 UI app

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.

2.3 Try the UI

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

2.4 Hystrix dashboard

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.

2.5 Backend

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

2.6 Test it

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 🎉 !

2.7 Clean up

Now let’s delete everything to free the resources.

cf delete -f fortune-teller-ui
cf delete -f fortune-teller-service
cf delete -f fortune-teller-hystrix-dashboard
cf delete-service -f fortune-service-database
cf delete-service -f fortune-teller-logs

3. Do the mta build & cf deploy

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.

3.1 Assemble an MTAR

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

3.2 cf deploy

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.

3.3 Examine your MTA

You may find info of the mta with the following commands

cf mtas
cf mta fortune-teller
Note
You can check how your app is behaving in the same way as in 2.6

Congratulations on your first mta deployment 👏 !

4. Do the blue-green deploy

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 📗 📘 !

4.1 A new MTA version

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'

4.2 Blue-green deployment

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

5. Do the undeploy

You’re almost done! To free up resources after the exercise, please remove everything created with the following:

cf undeploy fortune-teller --delete-services

6. FINISH

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:

About

cf Multiapps tutorial over a slightly modified fortune-teller app fork

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published