MultiApps logo

MultiApps Controller Build Status

The MultiApps Controller (formerly known as deploy service) for Cloud Foundry is based on the Multi-Target Application (MTA) model in which CF applications are modeled as modules, while CF services as resources. The MTA model enables the delivery of packaged applications, where any target specific configuration could be specified on deployment time without changing application code. CF MultiApps Controller provides the possibility to operate (deploy, update, undeploy) MTA modeled applications via a single command, while ensuring the consistency and completeness of the different application components.

Getting started with MultiApps

You can find more information about what the MultiApps Controller offers in the way of functionality as well as information about creating MTA archives on the MultiApps Controller Wiki. If you are planning to deploy on the SAP cloud you can find even more information in the official SAP Help Documentation under Multitarget Applications.

The project has also provided schema support in the open Schema Store which would provide auto-completion, tooltips, synthax checking and more when writing MultiApps descriptors.

Components

com.sap.cloud.lm.sl.cf.api

Contains the swagger-generated definitions of the REST API models and endpoints. The complete swagger definitions can be found at: https://app.swaggerhub.com/apis/SAP53/mtarest/1.0.0

com.sap.cloud.lm.sl.cf.core

Contains the domain model, persistence and other core services and utilities.

com.sap.cloud.lm.sl.cf.client

Extends the Java Client Library for Cloud Foundry with additional domain model objects and attributes, OAuth token providers and retrying functionality.

com.sap.cloud.lm.sl.persistence

Contains utilities for upload and processing of file artifacts. These are used for initial upload of the MTA archive and descriptors and their processing as part of the deployment.

com.sap.cloud.lm.sl.cf.process

Contains the concrete workflow definitions for MTA operations like deploy, undeploy, blue-green deploy, etc. These are modeled via Activiti BPMN process definitions. The process definitions have steps, where each step logic uses the com.sap.cloud.lm.sl.cf.client to call the Cloud Controller API from Cloud Foundry.

com.sap.cloud.lm.sl.cf.web

Contains REST API implementations for:

The result from the build of this component is a WAR file which is the deployable assembly of the MultiApps Controller.

Building

Build tools

All components are built with Java 8 and Apache Maven, version 3.3.9 or newer.

Make sure that your Maven is configured to use Java 8 by configuring the JAVA_HOME env to point to the correct Java JDK.

Compiling and Packaging

To build all components, run the following command from the root directory of the project:

$ mvn clean install

The deployable result from building components is a WAR file, located at com.sap.cloud.lm.sl.cf.web/target/com.sap.cloud.lm.sl.cf.web-<version>.war.

Additionally, the project uses Immutables to generate value objects. As a result, it won't compile in IDEs like Eclipse or IntelliJ unless you also have an enabled annotation processor. See this guide for instructions on how to configure your IDE.

There is also a certain preprocessing of the manifest.yml that creates a version of the manifest with information about the newly built MultiApps-Controller such as version and path to the built WAR file.

This manifest is located at com.sap.cloud.lm.sl.cf.web/target/manifests/manifest.yml.

Deploying

The CF Multiapps Controller is deployed as a standard application in Cloud Foundry. So first you have to get access to a Cloud Foundry instance, then login to the CF API and target a org and space, where the CF deploy service application is to be deployed.

If you do not have a Cloud Foundry instance you can sign up for SAP Cloud Platform trial here.

Configuration

The manifest.xml located at com.sap.cloud.lm.sl.cf.web/target/manifests/manifest.yml is used to configure the deployment of the Multiapps Controller to the Cloud Foundry as well as some of it's functionality.

Property Sample Value Description
host deploy-service The entry can be changed to define a different host name for the application.
memory 1024M This setting can be further tuned depending on the expected load. If you set the memory to too low the application might fail to start due to JVM heap memory shortage.
instances 1 The CF MultiApps Controller can also scale by instances. The default number of instances is set to 1 to avoid consuming too much resources.

Required services

In order to function the CF Multiapps Controller requires a PostgreSQL service instance for persistence. So, this should first be created by running the create-service command:

$ cf cs <postgresql-service> <postgresql-service-plan> deploy-service-database

For example if you are deploying the CF Multiapps Controller on the SAP Cloud Platform the parameters should look like this:

$ cf cs postgresql v9.6-dev deploy-service-database

Other platforms might have different names and plans for the PostgreSQL service.

Push the application

Push the CF Multiapps Controller application to Cloud Foundry by running the following command from the com.sap.cloud.lm.sl.cf.web directory:

$ cf push -f target/manifests/manifest.yml

After the push operation completes then the CF Multiapps Controller should be up and running.

Usage via CF MTA plugin

In order to use the CF MultiApps Controller you should install the CF MTA plugin, so follow the instructions in the Download and installation section there. For the set of supported operations and examples refer to the Usage section.

If using a different host than the default for your CF Multiapps Controller either set the following env DEPLOY_SERVICE_URL=<deploy-service-app-url> or run CF MTA plugin commands with -u <deploy-service-app-url> so that they are executed against your instance(s) of the Multiapps Controller.

You could use a modified spring-music application, which is extended and adapted to the MTA model to test your newly deployed Multiapps Controller.

How to contribute

Further reading

Presentations, documents, and tutorials:

License

Copyright (c) 2017 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, v. 2 except as noted otherwise in the LICENSE file.