Configuring multiple Applications with a single Manifest¶
MindSphere Cloud Foundry requires multiple applications to be described with a single Manifest file. This file contains properties for all applications, e.g. application name, memory limit, service bindings and routes, and allows to deploy them with a single
cf push command. For more information on using
cf push, see Cloud Foundry documentation.
The Operator Cockpit uses the single manifest to automatically register your applications in the production system. This section describes the necessary attributes in the manifest and provides a short checklist for transferring your application to the production system.
Application Components and Cloud Foundry applications¶
MindSphere enables you to design and create Software as a Service. Most applications consist of multiple services that in combination are accessible through a single entry point, e.g. by clicking on an icon on the Launchpad. While accessing the application multiple resources are loaded and many requests are made. Those requests and resources might be delivered by different internal services in the background which are not visible for a customer or client.
To achieve this behavior MindSphere has an integrated application gateway that sits between clients and services. It acts as a reverse proxy and is routing requests from client to the different services. When mapping this to Cloud Foundry, the services are the individual Cloud Foundry applications running within the same Cloud Foundry Space.
During deployment each application gets a route assigned, except if you want to have a service that is completely internal and only communicates with Backing Services. To avoid accidental exposure of unprotected services on the internet, you must register each route in the Developer Cockpit in order to access it. In the Developer Cockpit we use the term "components" to name a single service that maps to one Cloud Foundry application. The name of the component must match the name of the Cloud Foundry application which is defined in the Cloud Foundry manifest configuration file.
Configuring the manifest file¶
Defining random routes and explicit routes¶
Cloud Foundry provides multiple ways for defining a route for applications. You can either use the CLI or the
routes attribute in the Manifest to define the route for your application. The preferred way for defining routes is using random routes that are generated automatically from the application name.
route attributes in the manifest file are deprecated. Only
random-route is supported.
Offline Buildpacks for region China 1
MindSphere Cloud Foundry services in region China 1 should use Offline Buildpacks to avoid potential failure caused by downloading external dependencies from unstable international network access.
You can run
cf buildpacks to check the buildpack name to be used in the manifest file. As an example, you should configure the manifest file with
java_buildpack_offline instead of
Deploying an app with a manifest
To deploy an app with a manifest file, see Deploy an App with a Manifest.
App Manifest Attribute Reference
To refer the list of attributes available for app manifests, see App Manifest Attribute Reference.
For example, if you have the application with the name
monitorservice the configuration could look like this:
applications: - name: monitorservice stack: cflinuxfs3 instances: 1 random-route: true buildpacks: - java_buildpack path: /monitorservice/target/monitorservice-0.0.1.BUILD-SNAPSHOT.jar memory: 1GB services: - mypostgresql - name: monitorui stack: cflinuxfs3 instances: 1 random-route: true buildpacks: - staticfile_buildpack path: /monitorui/www memory: 1GB
Once we have deployed the application with the above configuration Cloud Foundry is going to create a route similar to this:
monitorservice-grateful-jaguar.apps.myRegion.mindsphere.io. As long as the application or the route is not deleted the generated random route will be reused.
In the next example we are using explicit route definitions like
monitorservice-myTenant.apps.myRegion.mindsphere.io for one of our applications. This is beneficial if you need to make calls between Cloud Foundry applications. However, it requires you to add the tenant name in the route to avoid route conflicts. When applying this to our previous example we end up with the following configuration:
applications: - name: monitorservice stack: cflinuxfs3 instances: 1 buildpacks: - java_buildpack routes: - route: monitorservice-myTenant.apps.myRegion.mindsphere.io path: /monitorservice/target/monitorservice-0.0.1.BUILD-SNAPSHOT.jar memory: 1GB services: - mypostgresql - name: monitorui instances: 1 routes: - route: monitorui-myTenant.apps.myRegion.mindsphere.io buildpacks: - staticfile_buildpack path: /monitorui/www memory: 1GB
In a final step the generated routes are used to configure the components in the Developer Cockpit. Each component requires
- a name which must match the Cloud Foundry application name and
- a Cloud Foundry URL which is the route.
Please be aware that you cannot reuse the same route in the development and production system. Therefore, we advise to either use random routes or to suffix the route with a tenant name. You can use the
cf check-route ROUTE command to check whether is available.
Adding bindings for Backing Services¶
Next to the route configuration the manifest might also include the bindings for one or more Backing Services. Ensure that you add all bindings in the manifest file and to configure the required Backing Service plans with the correct instance name in the Developer Cockpit.
We recommend to use a directory structure in which each application resides in a sub directory. You can use the
path attribute to point to the correct directory for each application. The example route configurations from the previous section already reflect this structure and use the correct
├───monitorservice │ ├───src │ └───target ├───monitorui │ └───www ├───.cfignore └───manifest.yml
Use the same structure for creating the ZIP file to avoid any problems with the deployment on the production system.
Preparing applications for operator deployment¶
After successfully testing your application you can transfer it to the application repository for productive usage. The following checklist and directory structure guide will help you preparing a productive version.
For transferring an application to the application repository and eventually assigning it to an operator, you should check the following points to avoid any problems:
- [ ] Each component name has a matching Cloud Foundry application (name) as defined in the manifest file
- [ ] All bindings are present in the manifest file.
- [ ] Cloud Foundry manifest does not contain
- [ ] Routes are still available and/or inform an operator about the required route changes (e.g. replacing the tenant name).
- [ ] Configure the correct amount of memory for each application.
- [ ] All required environment parameters are set.
- [ ] All
pathvalues match your directory structure.
- [ ] Define the
stackto use for your application.
- [ ] Explicitly define the buildpack, especially when using
- [ ] Set your fixed dependencies to specific versions or use wildcards for patch versions.
- [ ] Test the deployment at least once with the single manifest file.
- [ ] Use the directory structure mentioned above.
If you want to use auto-deployment option to deploy your applications in Operator Cockpit, then make sure that:
buildpackis available. Currently, this parameter is supported.
binary_buildpackis available. Out of all the
buildpacks is present in the
manifest file, the key will be removed from the
manifest file during upload, and therefore auto-deployment will be disabled. However, you can still deploy the application manually by using the CF CLI commands. For more information on auto-deployment support in Operator Cockpit, refer Operator Cockpit FAQs.
Any questions left?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.