sap-samples / cf-mta-examples

The repository contains multitarget application (MTA) examples for SAP BTP, Cloud Foundry environment. Examples demonstrate how to achieve different goals using MTAs and show the capabilities of MTA deployment service in the Cloud Foundry environment.

Description

The repository contains Multitarget Application (MTA) examples for SAP Business Technology Platform Cloud Foundry environment. Examples demonstrate how to achieve different goals using MTAs and what are the capabilities of SAP Cloud Deployment service in Cloud Foundry environment.

Before you start with the examples, please make sure that:

• You are familiar with the basic concepts of Cloud Foundry, such as Cloud Foundry applications, services, service bindings

• You are familiar with the basic concepts of MTA modeling, such as MTA modules, resources and dependencies between them. For more information, you may refer to official documentation for Multitarget Applications for the Cloud Foundry Environment on the SAP Help Portal: Multitarget Applications for the Cloud Foundry Environment

Requirements

• Access to SAP Business Technology Platform Cloud Foundry environment. There you need to have account. MTA examples will be deployed in some of the account’s organization and space.

• Installed CloudFoundry CLI - ensure that CloudFoundry CLI is installed and working. For more information about installation of CloudFoundry CLI, please visit the official CloudFoundry Documentation. For the examples, CloudFoundry CLI v8 is supported.

• Installed MultiApps CF CLI Plugin - ensure that MultiApps CF CLI Plugin is installed and working. For more information, please visit the official GitHub Page

• [Optional] Installed Cloud MTA Build Tool - the tool is used in some of the listed use cases. For more information please visit the official Cloud MTA Build Tool Documentation

Download and Installation

Clone the repository, following the instructions.

MTA use case examples

Deploy CF Apps

• Simple CF app example, managing app attributes & deploy parameters

• Docker images as cf apps

• Managing cf app routes

• Sharing configuration values between apps

SAP Content Deployment

• SAP Content Deployment

  • HTML5 Application Content Deployment

  • Content Deployment with an Existing Service Key

  • Content Deployment to a User-Provided Service

Manage CF Services

• Service and Binding creation

• Manage User-Provided Service Instances

• Optional and Active Service Instances

Share configuration values between MTAs via a configuration registry

• Cross MTA Configurations

Managing deployment configurations

• Modifying an assembled MTA archive

• Configure same MTA for different environments

• Externalize service parameters to file

Parallel deployment

Optimize deploy time by executing deploy operations in parallel

• Parallel module deployment

Sequential resource processing

• Sequential resource processing

Zero downtime update

• Legacy Blue-green deployment

• Deploy with Blue-green strategy

Idle host and domain during blue-green deployment

• Idle route(s), idle host(s) and idle domain(s)

Solution development efficiency

• Build/Assemble & Deploy only a parts of an MTA

Preserve manually modified app state

• Keep exisiting routes on update

• Keep exisiting service bindings on update

• Keep exisiting app env variables on update

Deploy a remote MTAR

• Deploy with a URL reference

Limitations

Most examples are generic for MultiApps Controller that is the standard MTA Deployment service for Cloud Foundry. Some, however are runnable only on SAP Business Technology Platform Cloud Foundry, because of speciffic service offerings or functionalities available only there.

Known Issues

Not detected issues

How to obtain support

Create an issue, following the instructions.

License

Copyright (c) 2020 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the [LICENSE](LICENSES/Apache-2.0.txt) file.

cf-mta-examples's Issues

[rl-readme_file-1] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-readme_file-1
Explanation: Does it have a README file? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

Partial deploy - link deployed CF app to MTA version

Hello,
I am looking to use the partial deploy feature.
The problem we face is when trying to map the CF applications to the last MTA version with which it was deployed.

e.g.
Lets say an MTA has 5 modules - A, B, C, D, E

• MTA version 1.0 - deploys all 5 to CF
• Code change 1
• Deploy A, B to CF. MTA version 1.1
• Code change 2
• Deploy B, C, D to CF. MTA version 1.2

Now looking at the apps in CF,
how do I identify that A was deployed on MTA version 1.1, but E is still on version 1, while B,C,D were updated with version 1.2

The 'cf mta' command only prints out the associated apps, but without any information on the version.

Thanks,
Yogesh

Example: Content deployment - no information on the structure of the content.zip archive

The readme file only mentions that there should be a zip archive containing the web apps but it doesn't specify more. I went ahead and downloaded the archive from https://github.com/SAP-samples/cf-mta-examples/tree/master/content-deployment/content to investigate its internal structure.

I saw that it uses the following structure:

content.zip
|── webapp1.zip
|── webapp2.zip
|── webapp3.zip
|   |── manifest.json
|   |── xs-app.json
|   |──  ...

My ask would be to add this information to the readme to make it easier to find.

Example for: Triggering Tasks at deploy process events (Hooks feature)

Hooks feature documentation: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/b9245ba90aa14681a416065df8e8c593.html

TLDR: Run a CF task before/after an app get's started or on other steps of the deploy-process in order to achieve capabilities as triggering long graceful shutdown, pre-processing data in DB etc.

Example: SAP CP Destinations

Create an example showing the modelling & creation of SAP CP "destinations" with an mta deploy.
The example should cover both:

• instance level destinations and sub-account level destinations
• destinations to service instances (keys) & destinations to a route of an app within the same MTA

Example for: Activating/Disabling the consumption of a service with an extension descriptor

Example for: Route discovery of applications in an MTA

A missing example: Sharing a dynamically generated route of one app to the environment of another app during MTA deployment.

Hide Role Collections From Subscriber Subaccount

Dear Colleagues, 
 
I am part of the SAP ETD-Cloud team which is working on a multi-tenant application that is deployed  in Cloud Foundry.
 
For authentication, authorization, application routing and role generation we use XSUAA. The roles are created from the mta.yaml which resides in the SAP Application Router. The application is part of the Cloud Foundry subscription and it is multi-tenant based.
 
Is there any possibility to hide custom roles for the subscribed accounts? We would like to have certain roles visible only to our central tenant while others should be available for all the subscribers, including us.
 
Regards,
Borcea Cristian.

[rl-assigned_teams-3] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-assigned_teams-3
Explanation: Does it have enough admins on GitHub? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

Example for: Deployment from directory `cf deploy ./`

Showcase deployment from directory with a mtad.yaml maintained (cf deploy ./myprojectdir/ ) - featuring the least intrusive way to introduce mta deployment to an existing project.

[rl-assigned_teams-2] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-assigned_teams-2
Explanation: Does it have an admin team on GitHub? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

How to bind route to a user-provided service?

Hi guys, this is a very helpful repo to better understand MTA implementation. I looked through the examples, but couldn't find any example for my particular case. I'm creating this issue so future devs that have the same problem can search and hopefully find a solution in this issue.

I have a user-provided app rate-limiter that is bound to the route of a route service. It serves as a proxy to add rate limiting to multiple applications. I can bind my application to this route service by running cf bind-route-service and I do get the rate limited. My question is how can I do this via the MTA file?

I've tried adding the service under requires and adding the rate-limiter as a resource:

modules:
  - name: my-app
    type: java
    path: /
    requires:
      - name: rate-limiter

resources:
  - name: rate-limiter
    type: org.cloudfoundry.user-provided-service

This does bind the service to the app as I get this in the deployment output:

Binding service instance "rate-limiter" to application "my-app"...

However, it doesn't actually bind the route. My app doesn't get rate limited and when I run cf unbind-route-service it outputs this:

➜  ~ cf unbind-route-service my-app-domain rate-limiter --hostname my-app-host

Unbinding may leave apps mapped to route my-app-host.my-app-domain vulnerable; e.g. if service instance rate-limiter provides authentication. Do you want to proceed?> y
Unbinding route my-app-host.my-app-domain from service instance rate-limiter in org * / space * as [email protected]...
Route my-app-host.my-app-domain was not bound to service instance rate-limiter.
OK

Thanks 🙏

remove property using extension descriptor

Hi,
I have tried to make use of the feature to remove a property/parameter using the extension descriptor.
Following the sample https://github.com/SAP-samples/cf-mta-examples/tree/main/parameter-and-property-metadata#deploy-mta-with-not-null-property-and-remove-it-in-the-extension-descriptor
I haven't succeeded to remove the property "not-null-property".

What I did:
1.modified the mtar archive and edited inside the mtad.yml file, saved the archive
2. deploy
3. redeploy using an extension.yaml with
properties:
not-null-property:

Can you please test and confirm?

I'm using the latest plugin version 3.2.2.

Example for: plugin(s) <-> framework MTA deployments

feature doc: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/791e17e5501849b28061718c8bec7384.html

This capability allows for applications in one (framework)MTA to get updated changes of info in their environments & restarted, when other MTAs (plugins) get deployed. The goal is to achieve service discovery between MTA deployments.

Example for: Placeholder and reference resolution order

• Document case when required dependencies have properties and parameters which of them are visible in the consumer 
• Document case when MTA reference point to parameter of the same module, if it is visible
• Document case when MTA reference point to property of the same module, if it is visible
• Document restrictions when read-only parameters default-xxx are used in combination with host, domain

Example for: Parameters & properties, overwriting and extension descriptor resolution chain

features docs:

• https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/791e17e5501849b28061718c8bec7384.html
• https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/fca2cedcb79649e7a8f51234faea1142.html

The tutorial should feature how extension descriptors can be chained, the rules/order of overwriting values. The parameters-metadata features for controlling overwriting (optional/overwritable) should be featured.

[rl-license_file-1] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-license_file-1
Explanation: Does it have a license file? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

Example: Content deployment - Invalid webapps in content.zip

It seems that all web apps in https://github.com/SAP-samples/cf-mta-examples/tree/master/content-deployment/content specify destinations in the xs-app.json file. If these destinations are not set up, the webapps cannot be used as the approuter will throw an exception.

So the sample is ok if it should only be used to demonstrate the cf deploy ./ but it's not suited to show how to use the html5 app repo.

My ask would be to remove the destinations from the xs-app.json files

Example for: consuming a single service instance in multiple MTA deployments in a single space

In some specific scenarios such capabilities are required:

• e.g. in development a single (and costly) service instance may need to be shared by multiple apps consuming it for the purpose of testing
• in production, when defined by architecture, a few MTA solutions are sharing consumption of a service instance but have otherwise independent lifecycle

In MTA modelling one can achieve this by:
A: ignoring the validations for ownership: each MTA's operations would "manage" (create/update/...) the service instance
B: Determining a single MTA to own the service instance, and all others would expect it to be already existing when deployed

Example for: Orchestrating build with MBT

Orchestrating a complex polyglot build with mbt

Example for: Managing service keys in MTA deployment

feature docs: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/32297f15898f47329df76b706447fc3e.html

Example: Content deployer

There is a typo in "Oficial" and the link which is supposed to point to the help page, doesn't point anywhere:
https://github.com/SAP-samples/cf-mta-examples/tree/master/content-deployment#oficial-documemtation-in-help-sap-portal

blue-green strategy does not keep existing service bindings

Hello,

I tried blue-green deployment strategy with

modules:
  - name: myName
    parameters:
      keep-existing:
        service-bindings: true

but service bindings were not transferred to the new "-idle" instance of the app.

When I try the same without "blue-green" strategy the existing, manually created service bindings are unbound and rebound as expected.

Example for: Marking services as optional, to be consumed only if available in the current environment; Marking resources as active/inactive

SAP-samples / cf-mta-examples / extension-descriptor-different-environments

Hello @ALL,

is there a way to differenciate between the environments when using SAP cloud transport management?

This example just shows this for command line
https://github.com/SAP-samples/cf-mta-examples/tree/e222cebb1a700a7dd753d9d33e1dd17c519e648e/extension-descriptor-different-environments

Any info how this can be achieved in SAP TMS?

[rl-vulnerability_alerts-1] Violation against OSS Rules of Play

The OSPO bot created this issue by mistake - It did not have enough priviledge to check the vulnerability alerts, So I am closing this issue now. Sorry for any inconvenience.

Example for development flow - deploying a small code change of an MTA module in development

this example should feature initial environment configuration with 'cf deploy' & consequent app updates with cf push --no-manifest -p <path to built app bits>

Consider splitting this topic to multiple examples in which the build is orhcestrated:

• with mbt
  Showcase partial mbt module build+ mtad.yaml generation; partial deploy along with cf push;
• with standard tooling (maven/grunt/gradle/..)
  Showcase deploy from directory cf deploy ./ along with cf push

Example for: using properties/parameters Metadata to mark sensitive/mandatory/optional content

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/fca2cedcb79649e7a8f51234faea1142.html

Example for: Running CF Tasks during MTA deploy

MTA deployment-service feature docs: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/a1c184c585f24c1c8dfaf4d1fcc2fde7.html
Details on CF tasks:
https://docs.cloudfoundry.org/devguide/using-tasks.html
https://blogs.sap.com/2019/05/01/cloudfoundryfun-4-fetch-football-scores-periodically/

Example for modifying host(s),domain(s),routes with an *.mtaext(s)

How to set parameter to update credentails for a service

Hi Team,

This is more of a question.

I want to know, how can I use the parameters to update service credentials.

UseCase:
There are a few services for which when we deploy using the mta.yaml, the credentials gets updated eg: Object Store, Credential Store Service on BTP.
I want to have the same behavior for the Hana service as well.
Basically on every deployment, it should update the schema password.

Hence I wanted to know, is there an option to do this using some parameter?

Thanks,
Nitin

[rl-assigned_teams-1] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-assigned_teams-1
Explanation: Does it have enough teams on GitHub? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html

Example for: Consuming / binding to an already existing service

feature docs: https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/6ef40dfc2ef14bb08c28cd53b4de4c0b.html

resources of type: org.cloud-foundry.existing-service, treated as not managed(read-only) but bound/deployed to.

[rl-reuse_tool-1] Violation against OSS Rules of Play

A violation against the OSS Rules of Play has been detected.

Rule ID: rl-reuse_tool-1
Explanation: Does README mention REUSE? No

Find more information at: https://sap.github.io/fosstars-rating-core/oss_rules_of_play_rating.html