diff --git a/README.adoc b/README.adoc index 82086aa..a707fa5 100644 --- a/README.adoc +++ b/README.adoc @@ -31,7 +31,7 @@ Clone the repository, following the link:https://help.github.com/en/github/creat ## SAP Content Deployment * link:/content-deployment/[SAP Content Deployment] ** link:/content-deployment/html5-content-deployment/[HTML5 Application Content Deployment] -** link:/content-deployment/html5-content-deployment/with-existing-key[Content Deployment to an Existing Service Key] +** link:/content-deployment/html5-content-deployment/with-existing-key[Content Deployment with an Existing Service Key] ** link:/content-deployment/html5-content-deployment/with-user-provided-service[Content Deployment to a User-Provided Service] ## Manage CF Services diff --git a/active-optional-resources/README.adoc b/active-optional-resources/README.adoc index 7525911..51add94 100644 --- a/active-optional-resources/README.adoc +++ b/active-optional-resources/README.adoc @@ -2,20 +2,21 @@ # Active and Optional Resources -This example shows how to mark service resources as optional/mandatory or active/inactive in order to influence the deployment behaviour +This example shows how to mark service resources as optional/mandatory or active/inactive in order to influence the deployment behaviour. -Orchestration of the following CF features is covered: +Orchestration of the following Cloud Foundry features is covered: - creation of service instances: https://docs.cloudfoundry.org/devguide/services/managing-services.html - creation of app bindings to service instances https://docs.cloudfoundry.org/devguide/services/application-binding.html#bind -## Modelling +## Modeling ### Service instances -Service instances are modelled as MTA resources of type `org.cloudfoundry.managed-service`. +Service instances are modeled as MTA resources of type `org.cloudfoundry.managed-service`. ### Optional service instances -In case a service instance is not mandatory for a deployment but should be used if availalble, it can be marked as optional in the mta(d).yaml descriptor +If a service instance is not mandatory for a deployment but you want it to be used if availalble, it can be marked as `optional` in the `mta(d).yaml` descriptor: + .... ... - name: my-cf-service-instance-resource @@ -25,11 +26,12 @@ In case a service instance is not mandatory for a deployment but should be used ... .... -NOTE: the value of the `optional` resource attribute can be changed for each deployment by link:https://github.com/SAP-samples/cf-mta-examples/tree/main/extension-descriptor-different-environments[using an extension descriptor] +NOTE: The value of the `optional` resource attribute can be changed for each deployment by link:https://github.com/SAP-samples/cf-mta-examples/tree/main/extension-descriptor-different-environments[using an extension descriptor]. ### Including/excluding services from deployment -To give fine control over what get's deployed or not, resources representing service instances can be marked as active or not. This will cause the MTA deployer to process/not-process them at deploy time. +Service instance resources can be marked as active or inactive to provide finer control over what is deployed. Depending on their status, the MTA deployer will either process or ignore these resources when deploying. + .... ... - name: my-cf-service-instance-resource @@ -39,40 +41,45 @@ To give fine control over what get's deployed or not, resources representing ser ... .... -NOTE: the value of the `active` resource attribute can be changed for each deployment by link:https://github.com/SAP-samples/cf-mta-examples/tree/main/extension-descriptor-different-environments[using an extension descriptor] +NOTE: The value of the `active` resource attribute can be changed for each deployment by link:https://github.com/SAP-samples/cf-mta-examples/tree/main/extension-descriptor-different-environments[using an extension descriptor]. -NOTE: the `active` attribute can also be specified for resources of type `org.cloudfoundry.existing-service`. In that case it determines if app bindings to the service would be created or not. I.e. if an app module has a reference to an existing-service resource via `requires: ...` and the resource has `active: false`, a service binding between them will not be created during deployment. +NOTE: The `active` attribute can also be specified for resources of type `org.cloudfoundry.existing-service`. In that case it determines if app bindings to the service would be created or not. If an app module has a reference to an existing-service resource via `requires: ...` and the resource has `active: false`, a service binding between them will not be created during deployment. ## Related examples -- service instance and binding creation(configurations) management with MTAs -- update of service instances and bindings [updating parameters, changing plans and labels; recreation ] +- service instance and binding creation (configurations) management with MTAs +- update of service instances and bindings [updating parameters, changing plans and labels; recreation] ## Requirements -- access to a CF space with quota for creation of service instances +- access to a Cloud Foundry space with quota for creation of service instances -## Oficial documemtation in Help SAP Portal +## Official documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9e34487b1a8643fb9a93ae6c4894f015.html[Resources] - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/a36df26b36484129b482ae20c3eb8004.html[Service creation parameters] - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/c7b09b79d3bb4d348a720ba27fe9a2d5.html[Service binding parameters] -## Try out +## Try it out ### Deploy the MTA -The example can be run with 2 approaches for building an MTA. Bothj lead to the same result. +The example demostrates 2 different approaches that lead to the same result. -#### A. Deeploying from a directory -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: +#### Deploying from a directory +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: ``` bash -cf deploy ./ -f ; +$ cf deploy ./ -f ; ``` _OR_ -First assemble an MTA archive using the link:mtad.yaml[mtad.yaml]` and then deploy the archive: +You can assemble an MTA archive using the `link:mtad.yaml[mtad.yaml]` by running the following command: ``` bash -mbt assemble -t ./ ; -cf deploy my-mta_0.0.0.mtar ; +$ mbt assemble -t ./ ; +``` + +Then deploy the assembled archive: + +``` bash +$ cf deploy my-mta_0.0.0.mtar ; ``` NOTE: See link:mtad.yaml[mtad.yaml] for the modelling @@ -80,22 +87,26 @@ NOTE: See link:mtad.yaml[mtad.yaml] for the modelling NOTE: please adjust the service label and plan values to match the available in your environment -#### B. Build and Deploy -The approach is using development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build MTAR. -Then the MTAR is deployed. +#### Build and deploy +This approach uses development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build an MTAR archive. ``` bash -mbt build -p cf -t . ; -cf deploy a.cf.app_0.0.0.mtar -f ; +$ mbt build -p cf -t . ; ``` -NOTE: See link:mta.yaml[mta.yaml] for the concrete modelling +The built MTAR archive is then deployed: + +``` bash +$ cf deploy my-mta_0.0.0.mtar -f ; +``` + +NOTE: See link:mta.yaml[mta.yaml] for the specific modeling ## Deploy with an inactive resource ```bash -cf deploy ./ +$ cf deploy ./ ... Operation ID: 7c8d9c49-badf-11ea-9455-eeee0a9e129b Deploying in org "deploy-service" and space "********" @@ -106,7 +117,7 @@ Deployed MTA version: "0.0.0" Service "my-cf-service-instance-resource" is inactive and will not be processed ... ``` -The cf application get's created. Since the service's resource is inactive, the service is not created and not bound to the app +The Cloud Foundry application gets created. Since the service's resource is inactive, the service is not created and not bound to the app. ## Deploy with an active optional & misconfigured service resource @@ -114,7 +125,7 @@ Let's enable the resource and mark it optional, but make sure to make the servic See how this is done in link:active_optional.mtaext[active_optional.mtaext] ```bash -cf deploy ./ -f -e active_mandatory.mtaext  6895 +$ cf deploy ./ -f -e active_optional.mtaext  6895 Deploying multi-target app archive /Users/********/dev/repos/ds/cf-mta-examples/active-optional-resources/my-mta.mtar in org deploy-service / space ******** as ********... Uploading 1 files... @@ -133,7 +144,7 @@ Processing service "my-cf-service-instance-resource"... Updating application "my-mta-managed-app-module"... ... ``` -The cf application get's created. Since the service's resource is inactive, the service is not created and not bound to the app +The Cloud Foundry application gets created. Since the service's resource is inactive, the service is not created and not bound to the app. ## Deploy with an active properly configured service resource @@ -141,7 +152,7 @@ Let's enable the resource with an extension descriptor See how this is done in link:active_mandatory.mtaext[active_mandatory.mtaext] ```bash -cf deploy ./ -f -e active_mandatory.mtaext +$ cf deploy ./ -f -e active_mandatory.mtaext ... Operation ID: 6cc12802-bae0-11ea-9455-eeee0a9e129b Deploying in org "deploy-service" and space "********" @@ -153,13 +164,13 @@ Processing service "my-cf-service-instance-resource"... Updating application "my-mta-managed-app-module"... ... ``` -The service instance & app get created and bound as expected +The service instance & app get created and bound as expected. ## Print the MTA details to confirm the deployment At any step you can check the created deployment with the following: ``` bash -$cf mta my-mta +$ cf mta my-mta Showing health and status for multi-target app my-mta in org deploy-service / space ******** as ********... OK Version: 0.0.0 @@ -172,3 +183,9 @@ Services: name service plan bound apps last operation my-cf-service-instance-resource application-logs lite my-mta-managed-app-module create succeeded ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/app-routes/README.adoc b/app-routes/README.adoc index b01fb8d..c2ff968 100644 --- a/app-routes/README.adoc +++ b/app-routes/README.adoc @@ -4,36 +4,36 @@ ## Overview This example shows how to model network route mapping to a CF application. The SAP Cloud Deployment service can create, map and unmap CF app routes. -There a three major ways to do the modelling: +There are three major ways to do the modeling: * <> parameter (*recommended*) * <> / *protocol* / *domain* parameters * <> / *domains* parameters [#routes] -## 1. Using *routes* +## Using *routes* -This is the recommended way of modelling routes, both when using cf app manifests and the mtad.yaml. +This is the recommended way of modeling routes, both when using CF app manifests and the mtad.yaml. NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] in the current directory. Those examples include: -* modelling of two custom routes for a cf app +* modeling of two custom routes for a CF app * consumption of the relevant default/generated parameter values as environment variables -The deployer will read the 'routes' parameter in a way consistent with cf App Manifest files. It will interpret everything up to the first '.' as the host, then everything up the '/' as the domain and the rest (if present) as the path. +The deployer will read the 'routes' parameter in a way consistent with CF app manifest files. It will interpret everything up to the first '.' as the host, then everything up to the '/' as the domain, and the rest (if present) - as the path. -### 1.1a Deploy -directly from an mtad.yaml +### Deploy +There are two ways of deploying the MTA. The first one is using an `mtad.yaml` deployment descriptor: ```bash $ cf deploy ./ -f ; ``` -or start from an mta.yaml: +Alternatively, you can use an `mta.yaml` development descriptor and deploy the built `mtar` archive afterwards: ```bash $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 1.2 Check out the result +### Check out the result List the routes in the space and look for ones bound to your app ```bash $ cf routes @@ -45,7 +45,7 @@ Getting routes for org ... List the environment variables in your app to see what the routing related paramters were resolved to during deployment ```bash -cf env my-cf-app +$ cf env my-cf-app ... default-domain: cfapps.sap.hana.ondemand.com default-host: --my-app-module @@ -57,27 +57,27 @@ secondRoute: --my-app-module-with-custom-suffix.cfapps.sap ``` [#no-hostname] -## 2. Deploy apps to hostless domains -If you want an app to be to bound to a route that is a subdomain of an existing domain without having a host attached, you need to use the 'routes' parameter in combination with 'no-hostname'. Note that 'no-hostname' is a boolean parameter, and must be included with each route it affects - if you have 2 or more hostless routes in your MTA then you need to add that parameter under each of those routes. If the parameter is not present for a route the default value taken will be 'false'. +## Deploy apps to hostless domains +If you want an app to be to bound to a route that is a subdomain of an existing domain, without having a host attached, you need to use the `routes` parameter in combination with `no-hostname`. Note that `no-hostname` is a boolean parameter and must be included with each route it affects - if you have 2 or more hostless routes in your MTA, you need to add that parameter under each of those routes. If the parameter is not present for a route, the default value taken will be `false`. NOTE: See link:no_hostname/mta.yaml[no_hostname/mta.yaml] or link:no_hostname/mtad.yaml[no_hostname/mtad.yaml]. WARNING: The MTA deployer will attempt to create the subdomain if it doesn't exist, but cannot resolve any specific corner cases about subdomain/domain ownership permissions. If the subdomain has already been created - the deployer will simply map the application to it. -### 2.1 Deploy -directly from an mtad.yaml +### Deploy +Using an `mtad.yaml` deployment descriptor: ```bash - $cd no_hostname ; + $ cd no_hostname ; $ cf deploy -f ; ``` -or start from an mta.yaml +Using an `mta.yaml` development descriptor and deploying the built `mtar` archive afterwards: ```bash - $cd no_hostname ; + $ cd no_hostname ; $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 2.2 Check out the result -Note the different routes mapped to the app +### Check out the result +Note the different routes mapped to the app: ```bash $ cf apps Getting apps in org / space as ... @@ -87,8 +87,8 @@ name requested state instances memory disk urls my-app-module started 1/1 1G 1G host2.some-domain.com, host1.some-domain.com, subdomain.some-domain.com ``` -### 2.3 Check out the registered domain -Running the following commands you can verify that one of the attached routes contains no host and has been registered as a domain +### Check out the registered domain +By running the following commands you can verify that one of the attached routes contains no host and has been registered as a domain: ```bash $ cf routes Getting routes for org / space as ... @@ -107,29 +107,31 @@ name ... subdomain.some-domain.com owned ``` -NOTE: Upon undeploying the mta, the deployer makes no attempt to delete this new domain. This action is left to the end user if desired + +NOTE: Upon undeploying the MTA, the deployer makes no attempt to delete this new domain. This action is left to the end user if desired. [#host] -## 3. Using *host* -This is a *NOT* recommended way of modelling routes in CF. +## Using *host* +This is *NOT* a recommended way of modeling routes in CF. -NOTE: See link:modelled_with_host_and_domain/mta.yaml[modelled_with_host_and_domain/mta.yaml] or link:modelled_with_host_and_domain/mtad.yaml[modelled_with_host_and_domain/mtad.yaml]. Those examples include the use of single *host*, *domain*, *protocol* parameters +NOTE: See link:modelled_with_host_and_domain/mta.yaml[modelled_with_host_and_domain/mta.yaml] or link:modelled_with_host_and_domain/mtad.yaml[modelled_with_host_and_domain/mtad.yaml]. Those examples include the use of single *host*, *domain*, *protocol* parameters. -WARNING: When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. E.g. *4 hosts* definitions x *4 domain* definitions would result in *16 unique reoutes being mapped to your application* +WARNING: When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. For example *4 hosts* definitions x *4 domain* definitions would result in *16 unique routes being mapped to your application*. -### 3.1 Deploy -directly from an mtad.yaml +### Deploy +Using an `mtad.yaml` deployment descriptor: ```bash - $cd modelled_with_host_and_domain ; + $ cd modelled_with_host_and_domain ; $ cf deploy -f ; ... Application "my-app-module" started and available at "my-single-host-value.internal.cfapps.sap.hana.ondemand.com" ... ``` -or start from an mta.yaml: + +Using an `mta.yaml` development descriptor and deploying the built `mtar` archive afterwards: ```bash -$cd modelled_with_host_and_domain ; +$ cd modelled_with_host_and_domain ; $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ... @@ -137,7 +139,7 @@ Application "my-app-module" started and available at "my-single-host-value.inter ... ``` -### 3.2 Check out the result +### Check out the result You can see that a route with the defined host and domain was created and mapped to the module's app: ```bash $ cf routes @@ -148,24 +150,24 @@ space host domain ``` [#hosts] -## 4. Using *hosts* -This is a *NOT* recommended way of modelling routes in CF. +## Using *hosts* +This is *NOT* a recommended way of modelling routes in CF. -NOTE: See link:modelled_with_hosts_and_domains/mta.yaml[modelled_with_hosts_and_domains/mta.yaml] or link:modelled_with_hosts_and_domains/mtad.yaml[modelled_with_hosts_and_domains/mtad.yaml]. Those examples include the use of *hosts* and *domains* parameters +NOTE: See link:modelled_with_hosts_and_domains/mta.yaml[modelled_with_hosts_and_domains/mta.yaml] or link:modelled_with_hosts_and_domains/mtad.yaml[modelled_with_hosts_and_domains/mtad.yaml]. Those examples include the use of *hosts* and *domains* parameters. -WARNING: When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. E.g. *4 hosts* definitions x *4 domain* definitions would result in *16 unique reoutes being mapped to your application* +WARNING: When defining both hosts and domains the MTA deployer will generate a route for each host.domain combination. E.g. *4 hosts* definitions x *4 domain* definitions would result in *16 unique reoutes being mapped to your application*. -### 4.1 Deploy -directly from an mtad.yaml: +### Deploy +Using an `mtad.yaml` deployment descriptor: ```bash - $cd modelled_with_hosts_and_domains ; + $ cd modelled_with_hosts_and_domains ; $ cf deploy -f ; ``` -or start from an mta.yaml: +Using an `mta.yaml` development descriptor and deploying the built `mtar` archive afterwards: ```bash - $cd modelled_with_hosts_and_domains ; + $ cd modelled_with_hosts_and_domains ; $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ... @@ -173,7 +175,7 @@ Application "my-app-module" started and available at "my-single-host-value.inter ... ``` -### 4.2 Check out the result +### Check out the result You can see that the cartesian product of the hosts and routes was created in the form of routes: ```bash @@ -204,25 +206,27 @@ space host domain |=== [#deploy-apps-with-no-routes] -## 5. Deploy apps with no routes -If you want an app to be scheduled in CF but don't want it reachable via HTTP, you can explicitly use the `no-route` parameter +## Deploy apps with no routes +If you want an app to be scheduled in CF but don't want it reachable via HTTP, you can explicitly use the `no-route` parameter. NOTE: See link:no_route/mta.yaml[no_route/mta.yaml] or link:no_route/mtad.yaml[no_route/mtad.yaml]. -### 5.1 Deploy -directly from an mtad.yaml +### Deploy +Using an `mtad.yaml` deployment descriptor: ```bash - $cd no_route ; + $ cd no_route ; $ cf deploy -f ; ``` -or start from an mta.yaml + +Using an `mta.yaml` development descriptor and deploying the built `mtar` archive afterwards: ```bash - $cd no_route ; + $ cd no_route ; $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 5.2 Check out the result -Note that no route(url) was mapped to that app + +### Check out the result +Note that no route(url) was mapped to that app: ```bash $ cf apps Getting apps in org / space as ... @@ -233,26 +237,27 @@ my-routless-cf-app started 1/1 1G 1G ``` [#http2-routes] -## 5. Deploy app with HTTP2 route -If you want to enable http2 routing traffic to applications you can use `protocol: http2` parameter on route level +## Deploy app with HTTP2 route +If you want to enable http2 routing traffic to applications you can use `protocol: http2` parameter on route level. NOTE: See link:http2-routes/mta.yaml[http2-routes/mta.yaml] or link:http2-routes/mtad.yaml[http2-routes/mtad.yaml]. -### 5.1 Deploy -directly from an mtad.yaml +### Deploy +Using an `mtad.yaml` deployment descriptor: ```bash $ cd http2-routes ; $ cf deploy -f ; ``` -or start from an mta.yaml +Using an `mta.yaml` development descriptor and deploying the built `mtar` archive afterwards: ```bash $ cd http2-routes ; $ mbt build -p cf -t . ; $ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 5.2 Check out the result -Note that the app-protocol is http2 +### Check out the result +Note that the app-protocol is `http2`: ```bash +$ cf routes Getting routes for org / space space host domain port path protocol app-protocol apps service instance @@ -262,21 +267,25 @@ space host domain port path protocol app-protocol ap ``` In the example above two routes were created. One of them uses `http1` app protocol for communication with the application and the other uses `http2`. -Keep in mind that if no protocol is specified the default protocol is `http1`, but if you already have configured an existing route to use `http2` and re-deploy the MTA using normal deployment (not blue-green) it will continue to work this way if you do not change it explicitly. +Keep in mind that if no protocol is specified, the default protocol is `http1`, but if you already have configured an existing route to use `http2` and re-deploy the MTA using normal deployment (not blue-green) it will continue to work this way unless you change it explicitly. [#keep-existing] -## 6. Keep-existing-routes +## Keep-existing-routes Feature is used if you don't want the deployment to unmap existing routes, which are not maintained in the MTA description, Activated in 3 ways: * global `keep-existing-routes:true` parameter -* module level `keep-existing-routes:true parameter` +* module level `keep-existing-routes:true` parameter * module level `keep-existing: [routes:true]` parameter -keep-existing-routes preservers the app-protocol as well. +Parameter `keep-existing-routes` preserves the app-protocol as well. link:../keep-existing-routes[See examples here] - +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/blue-green-deploy-legacy/README.adoc b/blue-green-deploy-legacy/README.adoc index d96801c..e7ea92d 100644 --- a/blue-green-deploy-legacy/README.adoc +++ b/blue-green-deploy-legacy/README.adoc @@ -1,32 +1,33 @@ :toc: # Legacy Blue-Green Deployment -Blue-green deployment is a technique that reduces downtime and risk by running two identical production environments called Blue and Green. +Blue-green deployment is a technique that reduces downtime and risk by running two identical production environments called **Blue** and **Green**. -At any time, only one of the environments is live, with the live environment serving all production traffic. For this example, Blue is currently live and Green is idle. +At any time, only one of the environments is live, with the live environment serving all production traffic. In this example **Blue** is live and **Green** is idle. -As you prepare a new version of your software, deployment and the final stage of testing takes place in the environment that is not live: in this example, Green. Once you have deployed and fully tested the software in Green, you switch the router so all incoming requests now go to Green instead of Blue. Green is now live, and Blue is idle. +As you prepare a new version of your software, the deployment and final stage of testing take place in a non-live environment: in this example, **Green**. This way, your regular operations on **Blue**, containing the current version, stay uninterrupted. Once you have deployed and fully tested the software in **Green**, you switch the router so all incoming requests now go to **Green** instead of **Blue**. In other words - **Green** is now live, and **Blue** is idle. -This technique can eliminate downtime due to app deployment. In addition, blue-green deployment reduces risk: if something unexpected happens with your new version on Green, you can immediately roll back to the last version by switching back to Blue. +This technique can eliminate downtime due to app deployment. In addition, blue-green deployment reduces risk: if something unexpected happens with your new version on **Green**, you can immediately roll back to the last version by switching back to **Blue**. -The example will demonstrate how to acomplish blue-green deployment using MTA. +The example will demonstrate how to accomplish blue-green deployment using an MTA. -MTA blue-green deployment is separeted in two phases. -First phase, so called validation is phase setup the next color environment, in order to be tested. The new environment version, in this case GREEN, is not accessible on the production routes but on temporary `-idle` routes. The validation phase is used to verify that new version of environment is operational. +MTA blue-green deployment is separeted in two phases: -During second phase all new applications are assigned to production routes and the new MTA color become productive. +The first phase, known as validation, involves setting up the new color environment, in this case **Green**, for testing. **Green** is not accessible via the production routes but rather via temporary `-idle` routes. The purpose of the validation phase is to ensure the new version of the environment is fully operational. + +During the second phase all new applications are assigned to production routes and the new MTA color, in this case **Green**, becomes productive. ## Requirements -* Awarenes of blue green deploy in Cloud Foundry: link:https://docs.cloudfoundry.org/devguide/deploy-apps/blue-green.html[Using Blue-Green Deployment to Reduce Downtime and Risk] +* Awarenes of blue-green deployment in Cloud Foundry: link:https://docs.cloudfoundry.org/devguide/deploy-apps/blue-green.html[Using Blue-Green Deployment to Reduce Downtime and Risk] ## Official documemtation * SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/764308c52e68488dac848bae93e9137b.html[Legacy Blue-Green Deployment] -# Try out +# Try it out -The example will demonstrate blue-green deployment of one MTA comprised of two applications. The first applcation, called "hello-backend", serves as backend and the second one, called "hello-router", serves as front end. +The example will demonstrate blue-green deployment of one MTA comprised of two applications. The first application, called `hello-backend`, serves as back end and the second one, called `hello-router`, serves as front end. -The idea is to have sample MTA which seems very similar to standard business applications that are comprised of frontend, backend and backing services. In the example "hello-backend" will play the combined role between backend and backing services, where the customer data is stored. +The idea is to have sample MTA which seems very similar to standard business applications that are comprised of front end, back end and backing services. In the example `hello-backend` will play the combined role of back end and backing services, where the customer data is stored. In terms of the example, we are using Java applications which communicate using REST interface. Both applications are simple web projects containing only one servlet. @@ -45,117 +46,135 @@ In terms of the example, we are using Java applications which communicate using ## Execute initial blue-green deployment of the BLUE environment -Initial blue green deployment is very similar to standard deployment because there are not existing applications. One difference is that temporary routes will be added during the deployment. Finally, the standard routes are assigned to the applications. +Initial blue green deployment is very similar to standard deployment because there are no previously existing applications. One difference is that temporary routes will be added during the deployment. Finally, the standard routes are assigned to the applications. -In the end of this part, you wil have similar environment: +In the end of this part, you will have a similar environment: image::diagrams/initial-bg-deploy-blue.png[] ### Deploy -You can try 3 different approaches, that will lead to the same result and the same output during the deployment. -The differences are how the deploymnet is trigger. +You can try 3 different approaches that will lead to the same result and the same output during the deployment. +The differences are how the deployment is triggered. #### Using existing .mtar + ```bash - $ cf bg-deploy hello-blue/hello.mtar -f - ... - No deployed MTA detected - this is initial deployment - New MTA color: BLUE - ... - Starting application "hello-backend-blue"... - Application "hello-backend-blue" started and available at "--hello-backend-idle.cfapps.sap.hana.ondemand.com" - ... - Starting application "hello-router-blue"... - Application "hello-router-blue" started and available at "--i076083-2-hello-router-idle.cfapps.sap.hana.ondemand.com" - ... - Application "hello-backend-blue" started and available at "--hello-backend.cfapps.sap.hana.ondemand.com" - ... - Application "hello-router-blue" started and available at "--hello-router.cfapps.sap.hana.ondemand.com" +$ cf bg-deploy hello-blue/hello.mtar -f +... +No deployed MTA detected - this is initial deployment +New MTA color: BLUE +... +Starting application "hello-backend-blue"... +Application "hello-backend-blue" started and available at "--hello-backend-idle.cfapps.sap.hana.ondemand.com" +... +Starting application "hello-router-blue"... +Application "hello-router-blue" started and available at "--i076083-2-hello-router-idle.cfapps.sap.hana.ondemand.com" +... +Application "hello-backend-blue" started and available at "--hello-backend.cfapps.sap.hana.ondemand.com" +... +Application "hello-router-blue" started and available at "--hello-router.cfapps.sap.hana.ondemand.com" ``` #### Using deploy from directory with .mtad -The approach will use deployment descriptor `hello-blue/mtad.yaml` and already built application bineries `hello-blue/router.war` and `hello-blue/backend.war` +The approach uses deployment descriptor `hello-blue/mtad.yaml` and already built application binaries `hello-blue/router.war` and `hello-blue/backend.war`: + ```bash - $ cf bg-deploy hello-blue/ -f +$ cf bg-deploy hello-blue/ -f ``` #### Build and deploy -The approach will use development descriptor `hello-blue/mta.yaml` to build bineries from source code folders `hello-blue/router/` and `hello-blue/backend/`. Then builded MTAR will be deployed. +The approach uses development descriptor `hello-blue/mta.yaml` to build bineries from source code folders `hello-blue/router/` and `hello-blue/backend/`: NOTE: The Cloud MTA Build Tool is usiing maven to build Java applications by default. ```bash - $ mbt build -p cf -s hello-blue - ... - INFO validating the MTA project - INFO building the "hello-router" module... - INFO executing the "mvn -B package" command.. - ... - INFO the build results of the "hello-router" module will be packed and saved in the "/mta_examples/blue-green-deploy/hello-blue/.hello-blue_mta_build_tmp/hello-router" folder - INFO building the "hello-backend" module... - INFO executing the "mvn -B package" command... - ... - [INFO] BUILD SUCCESS - [INFO] ------------------------------------------------------------------------ - [INFO] Total time: 1.301 s - [INFO] Finished at: xxxx - [INFO] ------------------------------------------------------------------------ - INFO the build results of the "hello-backend" module will be packed and saved in the "/mta_examples/blue-green-deploy/hello-blue/.hello-blue_mta_build_tmp/hello-backend" folder - INFO generating the metadata... - INFO generating the MTA archive... - INFO the MTA archive generated at: /mta_examples/blue-green-deploy/hello-blue/mta_archives/hello_0.1.0.mtar - $ cf bg-deploy hello-blue/mta_archives/hello_0.1.0.mtar +$ mbt build -p cf -s hello-blue +... +INFO validating the MTA project +INFO building the "hello-router" module... +INFO executing the "mvn -B package" command.. +... +INFO the build results of the "hello-router" module will be packed and saved in the "/mta_examples/blue-green-deploy/hello-blue/.hello-blue_mta_build_tmp/hello-router" folder +INFO building the "hello-backend" module... +INFO executing the "mvn -B package" command... +... +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 1.301 s +[INFO] Finished at: xxxx +[INFO] ------------------------------------------------------------------------ +INFO the build results of the "hello-backend" module will be packed and saved in the "/mta_examples/blue-green-deploy/hello-blue/.hello-blue_mta_build_tmp/hello-backend" folder +INFO generating the metadata... +INFO generating the MTA archive... +INFO the MTA archive generated at: /mta_examples/blue-green-deploy/hello-blue/mta_archives/hello_0.1.0.mtar + +The built MTAR archive is then deployed: + +```bash +$ cf bg-deploy hello-blue/mta_archives/hello_0.1.0.mtar ``` + ### Examine the result + Verify that front-end `hello-router` returns BLUE: + ```bash - $ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router +$ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router BLUE ``` ## Execute blue-green deployment of the GREEN environment and entering the validation phase -In the end of this part, you wil have similar environment: +In the end of this part, you wil have a similar environment: image::diagrams/bg-deploy-green-validation.png[] ### Deploy -You can try 3 different approaches, that will lead to the same result +You can try 3 different approaches, that will lead to the same result. + +#### Using existing `.mtar` -#### Using existing .mtar ```bash - $ cf bg-deploy hello-green/hello.mtar -f - ... - Deployed MTA color: BLUE - New MTA color: GREEN - ... - Starting application "hello-backend-green"... - Application "hello-backend-green" started and available at "--hello-backend-idle.cfapps.sap.hana.ondemand.com" - ... - Starting application "hello-router-green"... - Application "hello-router-green" started and available at "--hello-router-idle.cfapps.sap.hana.ondemand.com" - Process has entered validation phase. After testing your new deployment you can resume or abort the process. - Use "cf bg-deploy -i xxxx -a abort" to abort the process. - Use "cf bg-deploy -i xxxx -a resume" to resume the process. - Hint: Use the '--no-confirm' option of the bg-deploy command to skip this phase. +$ cf bg-deploy hello-green/hello.mtar -f +... +Deployed MTA color: BLUE +New MTA color: GREEN +... +Starting application "hello-backend-green"... +Application "hello-backend-green" started and available at "--hello-backend-idle.cfapps.sap.hana.ondemand.com" +... +Starting application "hello-router-green"... +Application "hello-router-green" started and available at "--hello-router-idle.cfapps.sap.hana.ondemand.com" +Process has entered validation phase. After testing your new deployment you can resume or abort the process. +Use "cf bg-deploy -i xxxx -a abort" to abort the process. +Use "cf bg-deploy -i xxxx -a resume" to resume the process. +Hint: Use the '--no-confirm' option of the bg-deploy command to skip this phase. ``` -#### Using deploy from directory with .mtad -The approach will use deployment descriptor `hello-green/mtad.yaml` and already built application bineries `hello-green/router.war` and `hello-green/backend.war` +#### Using deploy from directory with `.mtad` +This approach uses deployment descriptor `hello-green/mtad.yaml` and already built application bineries `hello-green/router.war` and `hello-green/backend.war`: + ```bash - $ cf bg-deploy hello-green/ -f +$ cf bg-deploy hello-green/ -f ``` #### Build and deploy -The approach will use development descriptor `hello-green/mta.yaml` to build bineries from source code folders `hello-green/router/` and `hello-green/backend/`. Then builded MTAR will be deployed. +This approach uses development descriptor `hello-green/mta.yaml` to build bineries from source code folders `hello-green/router/` and `hello-green/backend/`: + +```bash +$ mbt build -p cf -s hello-blue +``` + +The builded MTAR is then deployed: + ```bash - $ mbt build -p cf -s hello-blue - $ cf bg-deploy hello-blue/mta_archives/hello_0.1.0.mtar +$ cf bg-deploy hello-blue/mta_archives/hello_0.1.0.mtar ``` ### Examine the result -Verify that both application version are now available +Verify that both application version are now available: + ```bash - $ cf a +$ cf a Getting apps in org xxx / space xxx as xxx... OK @@ -165,21 +184,25 @@ hello-backend-green started 1/1 512M 256M ---hello-router-idle.cfapps.sap.hana.ondemand.com hello-backend-blue started 1/1 512M 256M --hello-backend.cfapps.sap.hana.ondemand.com ``` + Verify that BLUE environment is still the productive one: + ```bash - $ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router +$ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router BLUE ``` + Verify that GREEN environment can be accessed and validated on temporary `-idle` routes: + ```bash - $ curl https://--hello-router-idle.cfapps.sap.hana.ondemand.com/router +$ curl https://--hello-router-idle.cfapps.sap.hana.ondemand.com/router GREEN ``` NOTE: In case of a problem, the bg-deploy can be aborted without influencing the production environment. To stop the process copy-paste the suggested command by MTA CF CLI plugin: `cf bg-deploy -i xxxx -a abort` ## Make GREEN environment the productive one -At some point of time, you wil have similar environment, where both BLUE and GREEN applications are mapped to production routes. +At some point in time, you wil have a similar environment, where both BLUE and GREEN applications are mapped to production routes. image::diagrams/bg-deploy-green-temp.png[] @@ -187,7 +210,8 @@ In the end of this part, you wil have similar environment: image::diagrams/bg-deploy-green-final.png[] ```bash - $ cf bg-deploy -i 1b59ca36-007e-11ea-bbed-eeee0a9e6b19 -a resume +$ cf bg-deploy -i 1b59ca36-007e-11ea-bbed-eeee0a9e6b19 -a resume + Executing action 'resume' on operation xxxx... ... Updating application "hello-backend-green"... @@ -213,8 +237,9 @@ Process finished. ``` ### Examine the result Verify that old BLUE applications are deleted and new GREEN applications are assigned to production routes: + ```bash - $ cf a +$ cf a Getting apps in org xxx / space xxx as xxx... OK @@ -224,7 +249,7 @@ hello-router-green started 1/1 512M 256M ---hello-router.cfapps.sap.hana.ondemand.com/router +$ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router GREEN ``` ## Execute blue-green deployment of the BLUE environment without confirmation @@ -235,7 +260,7 @@ In the end of this part, you wil have similar environment: image::diagrams/initial-bg-deploy-blue.png[] ```bash - $ cf bg-deploy hello-blue -f --no-confirm +$ cf bg-deploy hello-blue -f --no-confirm ... Deployed MTA color: GREEN New MTA color: BLUE @@ -258,16 +283,24 @@ Use "cf dmol -i xxx" to download the logs of the process. ### Examine the result Verify that old GREEN applications are deleted and new BLUE applications are assigned to production routes: ```bash - $ cf a +$ cf a Getting apps in org xxx / space xxx as xxx... OK name requested state instances memory disk urls -hello-backend-blue started 1/1 512M 256M --hello-backend.cfapps.sap.hana.ondemand.com -hello-router-blue started 1/1 512M 256M --hello-router.cfapps.sap.hana.ondemand.com +hello-backend-blue started 1/1 512M 256M --hello-backend.cfapps.sap.hana.ondemand.com +hello-router-blue started 1/1 512M 256M --hello-router.cfapps.sap.hana.ondemand.com ``` + Verify that BLUE environent is the production one and serves on the production routes: + ```bash - $ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router +$ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router BLUE ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/blue-green-deploy-strategy/README.adoc b/blue-green-deploy-strategy/README.adoc index 995b52f..cd7ae69 100644 --- a/blue-green-deploy-strategy/README.adoc +++ b/blue-green-deploy-strategy/README.adoc @@ -282,3 +282,9 @@ Verify that the BLUE environent is the productive one and serves on the producti $ curl https://--hello-router.cfapps.sap.hana.ondemand.com/router BLUE ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/cf-app-docker/README.adoc b/cf-app-docker/README.adoc index 691ebc1..af12bd1 100644 --- a/cf-app-docker/README.adoc +++ b/cf-app-docker/README.adoc @@ -1,24 +1,24 @@ :toc: -# Deploying docker images as CF Apps with an MTA +# Deploying docker images as Cloud Foundry applications with an MTA -This example shows how to model a CF application running a docker image, as an MTA. Cloud foundry container runtime brings the capability to download docker images from a registry as dockerhub and to spin up containers from such. Those containers are managed just as regular cf apps. -Documentated in the CF docs: link:https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html[Deploying an App with Docker] +This example shows how to model a Cloud Foundry application (CF app), running a docker image, as an MTA. Cloud Foundry container runtime brings the capability to download docker images from registries such as Docker Hub and to spin up containers from such registries. Those containers are managed as regular Cloud Foundry apps. +Documentated in the Cloud Foundry documentation: link:https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html[Deploying your App with Docker] -The actual image getting deployed is of a cf sample app written in go: https://github.com/cloudfoundry-samples/test-app.git +The actual image getting deployed is of a CF sample app written in Go: https://github.com/cloudfoundry-samples/test-app.git -NOTE: See link:mtad.yaml[mtad.yaml] for up-to-date details on the attributes and environment and deployer parameters used. See link:mta.yaml[mta.yaml] for up-to-date details on the required build parameters. +NOTE: See link:mtad.yaml[mtad.yaml] for up-to-date details on the attributes, environment and deployer parameters used. See link:mta.yaml[mta.yaml] for up-to-date details on the required build parameters. # Try it out -## Deploy an MTA containing a cf app referencing a docker image. +## Deploy an MTA containing a CF app referencing a docker image -The example demostrate 2 different approaches that lead to the same result. +The example demostrates 2 different approaches that lead to the same result. ### Deploy directly from directory -That approach uses deployment descritpr `mtad.yaml` : +This approach uses deployment descritpr `mtad.yaml` : ```bash $ cf deploy ./ Deploying multi-target app archive /Users/******/dev/repos/ds/cf-mta-examples/cf-app-docker/a.docker.cf.app.mtar in org ****** / space ****** as ******... @@ -37,32 +37,32 @@ Application "my-mta-managed-app" started and available at "${org}-${space}-${app ... Process finished. ``` -### Or Create an MTA archive and deploy it +### Create an MTA archive and deploy it To generate the MTA archive based on the design time MTA decriptor link:mta.yaml[mta.yaml] use the Cloud MTA Build tool link:https://sap.github.io/cloud-mta-build-tool/usage/#one-step-build['build'] command that creates the MTAR from the project sources: ```bash -mbt build +$ mbt build ``` To generate the MTA archive based on the deployment time MTA decriptor link:mtad.yaml[mtad.yaml] use the Cloud MTA Build tool link:https://sap.github.io/cloud-mta-build-tool/usage/#how-to-build-an-mta-archive-from-the-modules-build-artifacts['assemble'] command that assembles the MTAR from already built binaries: ```bash -mbt assemble +$ mbt assemble ``` -Then the newly generated MTAR is used for deployment. +Then use the newly generated MTAR for deployment. ```bash -cf deploy mta_archives/a.docker.cf.app_0.0.0.mtar ; +$ cf deploy mta_archives/a.docker.cf.app_0.0.0.mtar ; ``` ## Examine the result -### List the deployed mta +### List the deployed MTA ```bash $ cf mta a.docker.cf.app Showing health and status for multi-target app a.docker.cf.app in org ****** / space ****** as ******... @@ -76,7 +76,7 @@ my-mta-managed-app started 1/1 1G 1G ${org}-${spac ### List app status and attributes ```bash -$cf app my-mta-managed-app +$ cf app my-mta-managed-app Showing health and status for app my-mta-managed-app in org ****** / space ****** as ******... name: my-mta-managed-app @@ -91,11 +91,16 @@ Find the route assigned to the app in the previous output (of `cf deploy`, `cf m - Directly open it in a browser as https:// -- Or execute a get request from the command line +- Or execute a GET request from the command line ```bash -curl https://${org}-${space}-${app-name}.${domain}/index +$ curl https://--./index 0 echo $? 0 ``` +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy a.cf.app -f --delete-services +``` diff --git a/cf-app/README.adoc b/cf-app/README.adoc index d75f76b..deb0021 100644 --- a/cf-app/README.adoc +++ b/cf-app/README.adoc @@ -1,34 +1,38 @@ :toc: -# Managing CF Apps with an MTA +# Managing CF apps with an MTA -This example shows how to model a simple CF application in an MTA, deploy it set some attributes and configure the deployer behavior +This example shows how to model a simple Cloud Foundry application (CF app) in an MTA, deploy it, set specific attributes and configure the deployer behavior. -# Try out +# Try it out -## Deploy an MTA containing an cf app. +## Deploy an MTA containing a CF app -The example demostrate 2 different approaches that lead to the same result. +The example demostrates 2 different approaches that lead to the same result. ### Deploy from directory -That approach uses deployment descritpr `mtad.yaml` and ready application binaries `appBits.zip`: +This approach uses deployment descriptor `mtad.yaml` and ready application binaries `appBits.zip`: ``` bash -cf deploy ./ -f ; +$ cf deploy ./ -f ; ``` -### Build and Deploy -The approach is using development descriptor `mta.yaml`and application binaries `appBits.zip` to build MTAR. -Then the MTAR is deployed. +### Build and deploy +This approach uses development descriptor `mta.yaml` and application binaries `appBits.zip` to build an MTAR archive: ``` bash -mbt build -p cf -t . ; -cf deploy a.cf.app_0.0.0.mtar -f ; +$ mbt build -p cf -t . ; +``` + +The built MTAR is then deployed: + +``` bash +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] for details on the attributes and environment and deployer parameters used. ## Examine the result -### List the deployed mta +### List the deployed MTA ```bash $ cf mta a.cf.app ; Showing health and status ... @@ -41,7 +45,7 @@ my-cf-app started 1/1 1G 1G orgname-spacename-my-m ### List app status and attributes ``` bash -$cf app my-cf-app ; +$ cf app my-cf-app ; Showing health and status for app my-cf-app in org ********** / space ******** as **********... name: my-cf-app @@ -60,8 +64,14 @@ memory usage: 1024M ### List app env variables and find the defined properties in the User Provided section ``` bash -$cf env my-cf-app | grep "MY_CF_APP_ENV_VARIABLE" ; +$ cf env my-cf-app | grep "MY_CF_APP_ENV_VARIABLE" ; MY_CF_APP_ENV_VARIABLE: HELLO MTA -$cf env my-cf-app | grep "A_MORE_COMPLEX_VAR" ; +$ cf env my-cf-app | grep "A_MORE_COMPLEX_VAR" ; A_MORE_COMPLEX_VAR: { "can be an entire":"json object", "with": [ "nested": { "elements": "https://each-host-is-registered-for-all-specified-domans.cfapps.sap.hana.ondemand.com" } ] ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy a.cf.app -f --delete-services +``` diff --git a/content-deployment/README.adoc b/content-deployment/README.adoc index 667a069..0b05c12 100644 --- a/content-deployment/README.adoc +++ b/content-deployment/README.adoc @@ -4,12 +4,12 @@ ## Overview -An MTA archive deployed in SAP Business Technology Platform Cloud Foundry environment may contain multiple types of contnet. The section covers SAP specific types of `application content` that excludes link:../cf-app[standard CF applications]. +An MTA archive deployed in SAP Business Technology Platform Cloud Foundry environment may contain multiple types of content. The section covers SAP specific types of `application content` that excludes link:../cf-app[standard CF applications]. Various types of `application content` are deployed using two different approaches: -* Using temprary deployer application which will receive the content and deploy it to the final backing service. -* Using service instance and directly deploy content in the final destination +* Using temprary deployer application which will receive the content and deploy it to the final backing service +* Using service instance and directly deploying content in the final destination The following types are supported: @@ -19,7 +19,7 @@ The following types are supported: * HDI content - using deployer application * Business Loggging content - using deployer application -## Official documemtation in Help SAP Portal +## Official documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/d3e23196166b443db17b3545c912dfc0.html[Content Deployment] -- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_mtaModuleTypes[Modules] -> MTA Module Types +- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_mtaModuleTypes[MTA Module Types] diff --git a/content-deployment/content-deployment-with-recreatable-key/README.adoc b/content-deployment/content-deployment-with-recreatable-key/README.adoc index aa9355c..f38fd65 100644 --- a/content-deployment/content-deployment-with-recreatable-key/README.adoc +++ b/content-deployment/content-deployment-with-recreatable-key/README.adoc @@ -14,17 +14,17 @@ image::service_keys_rotation.png[] More detailed explanation: -1. A user starts the deploy process, passing a mtad.yaml descriptor containing a module of type `com.sap.application.content` indicating content dpeloy (for example - a single content module, and multiple required services, only one of which is marked as the content service with parameter `content-target: true`) -2. Deploy Service detects the services and service keys part of the MTA that already exist in the target space and org via names and metadata (this includes the content service and any other services required for the deployment) -3. Deploy Service calculate the required service keys for the deployment from the mtad.yaml modelling (both explicitly defined service keys and implicit ones following the `${moduleName}-${resourceName}-credentials` naming convention). Then compares the calculated keys to the existing ones detected in the previous step - any required keys that are not existing will be created during deploy, any non-required keys that are existing will be deleted after the successful deploy -4. Deploy Service creates the content service if necessary (in the case of first deploy) -5. Deploy Service creates all missing service keys and fetches existing keys' credentials (as part of the content service's credentials there is a `content_endpoint` parameter, used for the content deploy) -6. Deploy Service performs the content deploy - making calls to the content_endpoint and passing service keys' credentials as configuration -7. After successful content deploy, Deploy Service deletes the existing service keys that weren't part of the MTA model in mtad.yaml (assuming keys were part of old deployment) +1. A user starts the deploy process, passing a `mtad.yaml` descriptor containing a module of type `com.sap.application.content` indicating content deploy. For example - a single content module and multiple required services, only one of which is marked as the content service with parameter `content-target: true`. +2. Deploy Service detects the services and service keys part of the MTA that already exist in the target space and org via names and metadata. This includes the content service and any other services required for the deployment. +3. Deploy Service calculates the service keys that are required for the deployment from the `mtad.yaml` modeling. This includes service keys that are explicitly defined and ones that are implied, following the `${moduleName}-${resourceName}-credentials` naming convention. It then compares the calculated keys to the existing ones detected in the previous step. Any required keys that do not exist will be created during deployment. The existing non-required keys will be deleted after the successful deployment. +4. If the MTA is deployed for the first time, Deploy Service creates the content service. +5. Deploy Service creates all missing service keys and fetches existing keys' credentials. As part of the content service's credentials there is a `content_endpoint` parameter, used for the content deployment. +6. Deploy Service performs the content deployment - making calls to the `content_endpoint` and passing service keys' credentials as configuration. +7. After successful content deployment, Deploy Service deletes the existing service keys that weren't part of the MTA model in the `mtad.yaml` file, assuming keys were part of an old deployment. ## Manual Modeling -Since the recreation mechanism works by comparing the keys by name, all implicit service keys will be reused, keeping existing behaviour in place. Any explicitly named service keys in mtad.yaml that were manually renamed in descriptor will be recreated. For explicit service keys, you can either use the `service-key` parameter in the required section or use an `existing-service-key` typed resource. E.g. +Since the recreation mechanism works by comparing the keys by name, all implicit service keys will be reused, keeping existing behaviour in place. Any explicitly named service keys in the `mtad.yaml` descriptor, that were manually renamed, will be recreated. For explicit service keys, you can either use the `service-key` parameter in the required section or use an `existing-service-key` typed resource. See the example below: ```yaml ... @@ -51,9 +51,10 @@ resources: ## Automated Modeling -To use a more automated way of flagging a service key for recreation without the need for manual renaming you can use the system parameter `${timestamp}` as part of its name. This ensures that key will be unique at time of deployment and considered a new key, while the older one will be detected and deleted (the deletion happens after the new one is created and content deplpoyment finished so as not to invalidate any credentials in use). The parameter `${timestamp}` is resolved to the current timestamp when the MTA module is processed in the beginning of the MTA deployment. +To use a more automated way of flagging a service key for recreation without the need for manual renaming you can use the system parameter `${timestamp}` as part of its name. This ensures that key will be unique at the time of deployment and will be considered a new key, while the older one will be detected and deleted. The deletion happens after the new service key is created and the content deplpoyment is finished. This approach ensures that no currently used credentials become invalidated. The parameter `${timestamp}` is resolved to the current timestamp when the MTA module is processed in the beginning of the MTA deployment. + +Example of this modeling also used in the provided example `mtar` descriptor: -Example of this modeling (also used in the provided example mtar descriptor) ```yaml ... modules: @@ -69,14 +70,17 @@ modules: ... ``` + ## Try it out -Deploy the provided mtar in cf to demo the automated service key rotation +Deploy the provided `mtar` in Cloud Foundry to demo the automated service key rotation: + ```bash cf deploy ./test-destination-gacd-x509.mtar ``` -Verify the destination service key that was created +Verify the destination service key that was created: + ```bash cf service-keys my_destination_service ... @@ -84,7 +88,8 @@ cf service-key my_destination_service ... ``` -Do a redeploy of the same mta (observe the messages in the process log), e.g. +Do a redeploy of the same MTA and observe the messages in the process log: + ```bash cf deploy ./test-destination-gacd-x509.mtar ... @@ -94,7 +99,8 @@ Deleting old service keys for content deploy "[]".. ... ``` -Verify the destination service key that was created +Verify the destination service key that was created: + ```bash cf service-keys my_destination_service ... @@ -102,7 +108,13 @@ cf service-key my_destination_service ... ``` -## Official related documemtation in Help SAP Portal +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` + +## Official related documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/d3e23196166b443db17b3545c912dfc0.html[Content Deployment] -- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_mtaModuleTypes[Modules] -> MTA Module Types +- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_mtaModuleTypes[MTA Module Types] diff --git a/content-deployment/html5-content-deployment/README.adoc b/content-deployment/html5-content-deployment/README.adoc index f853160..640cd38 100755 --- a/content-deployment/html5-content-deployment/README.adoc +++ b/content-deployment/html5-content-deployment/README.adoc @@ -5,13 +5,13 @@ The example will deployment of HTML5 Application Content via MTA. It demonstrates how to deploy content using directly HTML5 Application Repository service -## Oficial documemtation in Help SAP Portal +## Official documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/d3e23196166b443db17b3545c912dfc0.html[Content Deployment] ## Usage -The following MTA modeling in development (mta.yaml) or deployment (mtad.yaml) descriptors utilizes the feature +The following MTA modeling in development (`mta.yaml`) or deployment (`mtad.yaml`) descriptors utilizes the feature: ```yaml ... @@ -26,28 +26,28 @@ resources: - name: content-consuming-service-instance type: org.cloudfoundry.existing-service ``` -The module, representing the content, is defined of `type: com.sap.application.content`. The service(s) to which content is deployed are listed in the module's `requires` list and are depicted with a parameter `content-target: true` +The module, representing the content, is defined by `type: com.sap.application.content`. The service(s) to which content is deployed are listed in the module's `requires` list and are depicted with a parameter `content-target: true`. -The required resource should be of type coresponding to a CF service instance, be it `org.cloudfoundry.existing-service`, `org.cloudfoundry.managed-service`, or any type extending managed-service. +The required resource should be of type corresponding to a Cloud Foundry service instance, be it `org.cloudfoundry.existing-service`, `org.cloudfoundry.managed-service`, or any type extending managed-service. ### Usage with existing service keys -While the above example would create a service key in order to take the service credentials needed to deploy the content to the target service, it is also possible to model the MTA to use an already existing service key as shown in link:with-existing-key[Generic Application Content Deployment With Existing Key] +While the example above would create a service key in order to take the service credentials needed to deploy the content to the target service, it is also possible to model the MTA to use an already existing service key as shown in link:with-existing-key[Generic Application Content Deployment With Existing Key]. ## Example of content deployment -In the current directory you'll find example MTA. It contains a single zip archive, which in term containing three other archives of HTML5 Application content. +In the current directory you'll find example MTA. The zip archive contains three other archives of HTML5 Application content. * deployment descriptor: link:mtad.yaml[mtad.yaml] -NOTE: Though the example showcases HTML5 Application content, this generic modelling and mechanism works with a variaty of SCP service contents +NOTE: Though the example showcases HTML5 Application content, this generic modeling and mechanism works with a variety of SCP service contents. ## Try it out The example demonstrates 2 different approaches, leading to the same result. ### Deploy directly from directory -The approach uses deployment descriptor `mtad.yaml` and existing app binary. +This approach uses deployment descriptor `mtad.yaml` and existing app binary. -In the current directory, run `cf deploy`. This will automatically assemble an MTA archive and deploy it +In the current directory, run `cf deploy`. This will automatically assemble an MTA archive and deploy it: ```bash $ cf deploy ./ Deploying multi-target app archive */mta-examples/ui5MTA.mtar in org ******** / space ******** as ********... @@ -67,11 +67,12 @@ Deploying content module "ui5module" in target service "ui5-repo-service-instanc Skipping deletion of services, because the command line option "--delete-services" is not specified. Process finished. ``` + ### Assemble MTA archive and deploy -The approach uses deployment descriptor `mtad.yaml` and Cloud MTA Build Tool uses it to package the ready binaries in MTAR. -Then the newly generated MTAR is used for deployment. +This approach uses deployment descriptor `mtad.yaml` and Cloud MTA Build Tool uses it to package the ready binaries into an MTAR archive. +The newly generated MTAR is then deployed. -First use `mbt assemble` to create the *.mtar and than deploy it with `cf deploy`. +First use `mbt assemble` to create the *.mtar archive and than deploy it with `cf deploy`: ```bash $ mbt assemble @@ -87,11 +88,11 @@ $ cf deploy mta_archives/ui5MTA_0.0.1.mtar ## Build MTA archive via mta.yaml -If you maintain you project's sources in an MTA format and have the mta.yaml descriptor where content module is modeled as described above, you can create an MTA archive for this project using a regular build command of the MTA build tool of your choice. Since we recommend the new link:https://github.com/SAP/cloud-mta-build-tool[Cloud MTA Build tool] for buiding MTA projects, here is the example of such command: `mbt build`. +If you maintain you project's sources in an MTA format and have the `mta.yaml` descriptor where content module is modeled as described above, you can create an MTA archive for this project using a regular build command of the MTA build tool of your choice. Since we recommend the new link:https://github.com/SAP/cloud-mta-build-tool[Cloud MTA Build Tool] for buiding MTA projects, the command in our example is `mbt build`. ### Modeling and building of HTML5 modules -If you have several HTML5 modules in your project and would like to deploy their content into HTML5 repository, you need to adjust the build process as follows: +If you have several HTML5 modules in your project and would like to deploy their content into a HTML5 repository, you need to adjust the build process as follows: * The build scripts of each HTML5 module should produce a `zip` archive. For example, if you are using a Grunt build based on `@sap/grunt-sapui5-bestpractice-build`: diff --git a/create-managed-services/README.adoc b/create-managed-services/README.adoc index 516e54a..bacf653 100644 --- a/create-managed-services/README.adoc +++ b/create-managed-services/README.adoc @@ -7,13 +7,13 @@ This example shows how to create a service instance and a service binding for an Orchestration of the following CF features is covered: - creation of service instances: https://docs.cloudfoundry.org/devguide/services/managing-services.html -- creation of app bindings to service instances https://docs.cloudfoundry.org/devguide/services/application-binding.html#bind +- creation of app bindings to service instances: https://docs.cloudfoundry.org/devguide/services/application-binding.html#bind -## Modelling +## Modeling ### Service instances -Service instances are modelled as MTA resources of type `org.cloudfoundry.managed-service`. -Parameters in the config parameter can be specified to configure the service instance on it's creation or update +Service instances are modeled as MTA resources of type `org.cloudfoundry.managed-service`. +The service instance can be configured on it's creation or update via the `config` parameter. .... ... @@ -55,9 +55,9 @@ Parameters in the config parameter can be specified to configure the service ins ### Service Bindings -Service instances are modelled as in the MTA moduels describing the bound apps. -A binding is created/updated when a resource, describing a service instance is depicted as required by an app module. -Parameters in the config parameter can be specified to configure the service binding on it's creation or update +Service instances are modeled as in the MTA modules describing the bound apps. +A binding is created or updated when a resource, describing a service instance, is required by an app module. +The service instance can be configured on it's creation or update via the `config` parameter. .... ... @@ -86,24 +86,24 @@ modules: # Related examples - service instance and binding parameters(configurations) management with MTAs -- update of service instances and bindings [updating parameters, changing plans and labels; recreation ] +- update of service instances and bindings [updating parameters, changing plans and labels; recreation] ## Requirements -- access to a CF space with quota for creation of service instances +- access to a Cloud Foundry space with quota for creation of service instances -## Oficial documemtation in Help SAP Portal +## Official documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9e34487b1a8643fb9a93ae6c4894f015.html[Resources] - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/a36df26b36484129b482ae20c3eb8004.html[Service creation parameters] - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/c7b09b79d3bb4d348a720ba27fe9a2d5.html[Service binding parameters] -# Try out +# Try it out ## Deploy the MTA The example demostrates 2 different approaches that lead to the same result. NOTE: you can adjust the service label and plan values to match the available in your environment ### Deploy with a deployment descriptor (mtad.yaml) -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: ``` bash cf deploy ./ -f ; @@ -111,7 +111,7 @@ cf deploy ./ -f ; _OR_ -First assemble an MTA archive using the `mtad.yaml` and then deploy the archive: +First assemble an MTA archive using the `mtad.yaml` deployment descriptor and then deploy the archive: ``` bash mbt assemble -t ./ ; @@ -121,19 +121,19 @@ cf deploy my-mta_0.0.0.mtar ; NOTE: See link:mtad.yaml[mtad.yaml] for the modelling ### Build and Deploy -The approach is using development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build MTAR. -Then the MTAR is deployed. +This approach uses development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build an MTAR archive. +The built MTAR is then deployed: ``` bash mbt build -p cf -t . ; -cf deploy a.cf.app_0.0.0.mtar -f ; +cf deploy my-mta_0.0.0.mtar -f ; ``` NOTE: See link:mta.yaml[mta.yaml] for the concrete modelling ## Examine the result -### List the deployed mta +### List the deployed MTAs ``` bash $ cf services @@ -156,3 +156,8 @@ bound apps: name binding name status message my-mta-managed-app-module create succeeded ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services diff --git a/cross-mta-configurations/README.adoc b/cross-mta-configurations/README.adoc index 67bae9c..8e7493a 100644 --- a/cross-mta-configurations/README.adoc +++ b/cross-mta-configurations/README.adoc @@ -1,44 +1,47 @@ # Cross MTA configurations -Cross MTA configurations is a feature, allowing for consumption of external string values in the mta(d).yaml during deploy time. -The values are usually provided by other MTAs during their deployments and most-often contain alocated routes mapped to apps in those mtas. Thus a 'service discovery' is achieved at deploy-time. +Cross MTA configurations is a feature, allowing for consumption of external string values in the `mta(d).yaml` during deployment time. +The values are usually provided by other MTAs during their deployments and most often contain alocated routes mapped to apps in those MTAs. Thus a 'service discovery' is achieved at deployment time. -Since the SAP Cloud Deployment service persists those configurations until the providing MTA is undeployed, they can be used to also hold arbitrary configuration data - e.g. org/space speciffic settings which don't fit an extension descriptor. +Since the SAP Cloud Deployment service persists those configurations until the providing MTA is undeployed, they can be used to also hold arbitrary configuration data like org/space specific settings which don't fit an extension descriptor. -## Oficial documemtation +## Official documentation * SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/b8e1953a618e47e1bd3c3a60c213226e.html[Cross-MTA Dependencies] -# Try out +# Try it out ## Deploy provider MTA -To deploy the MTA providing the configurations, from the current directory run: +To deploy the MTA providing the configurations, run the following command from the current directory: + ``` bash - cf deploy provider/ -f ; +$ cf deploy provider/ -f ; ``` NOTE: See provider/mtad.yaml for details on the provided configuration values/names/scopes. ## Deploy consumer MTA -To consume the config values, from the current directory: +To consume the config values, run the following command from the current directory: + ```bash -cd consumer ; -cf deploy -f ; +$ cd consumer ; +$ cf deploy -f ; ``` -NOTE: See how configurations are applied in mtad.yaml in the current directory. +NOTE: See how configurations are applied in `mtad.yaml` in the current directory. ### Examine the result Check how the configuration value was consumed: -```text -cf services: + +```bash +$ cf services: name service plan bound apps last operation broker upgrade available myDevService application-logs lite staticapp create succeeded sleeve-broker ``` -NOTE: the service name came as configuration +NOTE: The service name came as configuration. -```text -cf env staticapp +```bash +$ cf env staticapp ... System-Provided: { "VCAP_SERVICES": {"application-logs": [{ @@ -57,15 +60,15 @@ via-param-in-requires: myDevService.inRequiresParam.inRequiresProperty NOTE: those env variable values can as configuraiton -## Consume a different configuration value by using an ext.descriptor +## Consume a different configuration value by using an `ext.descriptor` ```bash - cd consumer; - cf deploy -f -e ci.mtaext ; +$ cd consumer; +$ cf deploy -f -e ci.mtaext ; ``` -NOTE: see how the provided configuration was selected with provider/ci.mtaext +NOTE: See how the provided configuration was selected with provider/ci.mtaext. Result: -```text +```bash name service plan bound apps last operation broker upgrade available myCIService application-logs lite staticapp create succeeded sleeve-broker ... @@ -80,4 +83,10 @@ via-param-in-requires: myCIService.inRequiresParam.inRequiresProperty ``` -NOTE: Provided configurations can also target a cpeciffic org & space, which could avoid the need of using an extension descriptor if the configurations are space speciffic and apply to all mtas consuming them in that space. +NOTE: Provided configurations can also target a specific org & space. This could avoid the need of using an extension descriptor if the configurations are space specific and apply to all MTAs consuming them in that space. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/deploy-with-sequential-resources/README.adoc b/deploy-with-sequential-resources/README.adoc index e95e7b6..3f8419a 100644 --- a/deploy-with-sequential-resources/README.adoc +++ b/deploy-with-sequential-resources/README.adoc @@ -1,19 +1,21 @@ :toc: -# Deploy an MTAR using sequential Resource processing +# Deploy an MTAR using sequential resource processing -This example shows how to make use of the resource parameter 'processed-after' in order to influence the order of resource processing. +This example shows how to make use of the resource parameter `processed-after` in order to influence the order of resource processing. -- creation of service instances: https://docs.cloudfoundry.org/devguide/services/managing-services.html -- creation of app bindings to service instances https://docs.cloudfoundry.org/devguide/services/application-binding.html#bind +- Creation of service instances: https://docs.cloudfoundry.org/devguide/services/managing-services.html +- Creation of app bindings to service instances: https://docs.cloudfoundry.org/devguide/services/application-binding.html#bind -## Modelling +## Modeling ### Service instances having processed-after parameter -Whenever order of service processing is necessary, the 'processed-after' parameter comes handy. By using the parameter, we create a sequence of services (an order) in which the services should be processed. -For example let's say service 'A' requires service 'B' and service 'C' to be processed first. On the other hand both service 'B' and service 'C' require service 'D' to be pocessed first. Service 'D' does not require any other service. So the order for processing should be: - D -> B, C -> A. -We can achieve this with the following mtad.yaml: +Whenever order of service processing is necessary, the `processed-after` parameter comes handy. By using the parameter, we create a sequence of services (an order) in which the services should be processed. + +For example let's say service `A` requires service `B` and service `C` to be processed first. On the other hand both service `B` and service `C` require service `D` to be pocessed first. Service `D` does not require any other service. So the order for processing should be: +`D -> B, C -> A`. + +We can achieve this with the following `mtad.yaml`: .... ... @@ -39,9 +41,9 @@ resources: ... .... -NOTE: If the parameter 'processed-after' is not specified, the resources are processed in parallel. +NOTE: If the parameter `processed-after` is not specified, the resources are processed in parallel. -NOTE: The 'processed-after' parameter is supported from schema version 3 onwards. If it's used in a descriptor with schema version 2 or lower, the following message should appear: +NOTE: The `processed-after` parameter is supported from schema version 3 onwards. If it's used in a descriptor with schema version 2 or lower, the following message should appear: ``` bash Entities from class "Resource" with schema version "2" do not support this operation. At least "3" is required. ``` @@ -57,20 +59,20 @@ Resource "{0}" is required by itself for processing ``` ## Requirements -- access to a CF space with quota for creation of service instances +- Access to a Cloud Foundry space with quota for creation of service instances. -## Oficial documemtation in Help SAP Portal +## Official documentation is SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9e34487b1a8643fb9a93ae6c4894f015.html[Resources] -## Try out +## Try it out ### Deploy the MTA The example can be run with 2 approaches for building an MTA. Both lead to the same result. -#### A. Deeploying from a directory -That approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: +#### Deploying from a directory +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: ``` bash -cf deploy ./ -f +$ cf deploy ./ -f ... Deploying multi-target app archive /Users/*****/*****/cf-mta-examples/deploy-with-sequential-resources/multiple-anatz.mtar in org deploy-service / space ***** as *********************... @@ -111,35 +113,42 @@ Use "cf dmol -i ee6a0cf1-3005-11ec-bf71-eeee0a90baae" to download the logs of th ... ``` -_OR_ +Alternatively, you can first assemble an MTAR using the link:mtad.yaml[mtad.yaml]`: -First assemble an MTA archive using the link:mtad.yaml[mtad.yaml]` and then deploy the archive: +``` bash +$ mbt assemble -t ./ ; +``` + +And then deploy the assembled MTAR archive: ``` bash -mbt assemble -t ./ ; -cf deploy multiple-anatz_0.0.0.mtar ; +$ cf deploy multiple-anatz_3.0.0.mtar ; ``` -NOTE: See link:mtad.yaml[mtad.yaml] for the modelling +NOTE: See link:mtad.yaml[mtad.yaml] for the modeling. + +NOTE: Please adjust the service label and plan values to match the ones available in your environment. + +#### Build and deploy +This approach uses development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build an MTAR archive: -NOTE: please adjust the service label and plan values to match the available in your environment +``` bash +$ mbt build -p cf -t . ; +``` -#### B. Build and Deploy -The approach is using development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build MTAR. -Then the MTAR is deployed. +The built MTAR archive is then deployed: ``` bash -mbt build -p cf -t . ; -cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy multiple-anatz_3.0.0.mtar -f ; ``` -NOTE: See link:mta.yaml[mta.yaml] for the concrete modelling +NOTE: See link:mta.yaml[mta.yaml] for the specific modeling. ## Print the MTA details to confirm the deployment -At any step you can check the created deployment with the following: +At any step you can check the created deployment with the following command: ``` bash -$cf mta multiple-anatz +$ cf mta multiple-anatz Showing health and status for multi-target app multiple-anatz in org deploy-service / space ******** as ********... OK Version: 3.0.0 @@ -155,4 +164,11 @@ serviceA auditlog standard create succeeded serviceB auditlog standard create succeeded serviceC auditlog standard create succeeded serviceD auditlog standard create succeeded -``` \ No newline at end of file +``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: + +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/deploy-with-url/README.adoc b/deploy-with-url/README.adoc index dc3fbba..6830eda 100644 --- a/deploy-with-url/README.adoc +++ b/deploy-with-url/README.adoc @@ -2,21 +2,21 @@ # Deploy an MTAR referenced by a remote URL -This example shows how to deploy an mtar that isn't present on your local system. +This example shows how to deploy an MTAR that isn't present on your local system. NOTE: With this scenario, the Deploy Service *will not* check for any ongoing operations with the current MTA. -# Try out +# Try it out ## Deploy the MTA ``` bash -echo "https://github.com/SAP-samples/cf-mta-examples/blob/main/deploy-with-url/anatz.zip?raw=true" | cf deploy ; +$ echo "https://github.com/SAP-samples/cf-mta-examples/blob/main/deploy-with-url/anatz.zip?raw=true" | cf deploy ; ``` ## Examine the result -### List the deployed mta +### List the deployed MTA ``` bash $ cf mta anatz ; @@ -49,3 +49,10 @@ memory usage: 64M state since cpu memory disk details #0 running 2021-02-03T09:34:39Z 0.5% 13.8M of 64M 6M of 1G ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` + diff --git a/extension-descriptor-different-environments/README.adoc b/extension-descriptor-different-environments/README.adoc index 7a940b8..830c95f 100644 --- a/extension-descriptor-different-environments/README.adoc +++ b/extension-descriptor-different-environments/README.adoc @@ -2,27 +2,27 @@ # Configure same MTA for different environments -Configuration of the MTA is done with the standard approach using MTA extension descriptors. Extension descriptors are complementary files to the main deployment descriptor that provide additional data. They have file extension .mtaext and are external for MTA archive .mtar. Extension descriptors can be used to provide deployment specific information, for example credentials to external services. +Configuration of the MTA is done with the standard approach using MTA extension descriptors. Extension descriptors are complementary files to the main deployment descriptor that provide additional data. They have file extension `.mtaext` and are external for MTA archive `.mtar`. Extension descriptors can be used to provide deployment specific information, for example credentials to external services. -For the test purpose of the example, we will use a MTA containing a simple application, simple service and binding between them. -The MTA will be deployed in DEV and PROD environments using different extension descriptors, that result in different set-ups. +For the test purpose of the example, we will use an MTA containing a simple application, simple service and binding between them. +The MTA will be deployed in DEV and PROD environments using different extension descriptors resulting in different set-ups. ## [Optional] Requirements - Quota for application -- Quota for different service plans. The example use service offering "application-logs", free service plan "lite" and paid service plan "standard". You can try out with different service offering and plan at your convenience. +- Quota for different service plans. The example uses service offering "application-logs", free service plan "lite" and paid service plan "standard". You can try it out with a different service offering and plan at your convenience. ## Official documentation in SAP Help Portal - link:https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/50df803465324d36851c79fd07e8972c.html[Defining MTA Extension Descriptors] -# Try out +# Try it out ## Deploy MTAR without extension descriptors -The first step of the example, shows unsuccessful attempt to deploy the MTA without extension descriptor. +The first step of the example shows an unsuccessful attempt to deploy the MTA without an extension descriptor. -### Deploy with a deployment descriptor (mtad.yaml) +### Deploy with a deployment descriptor (`mtad.yaml`) -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: ``` bash $ cf deploy -f @@ -31,7 +31,7 @@ Error building cloud model: Service "my-service" has missing required parameter: ... ``` -Note that deployment fails expectedly because MTA defines required parameter `service-plan` for resource `my-service`, that represents service instance. This is done with MTA parameter metadata, called `optional`. By default, `optional` is `false` and setting it to `true`, make certain parameter optional and can be declared empty in the descriptor. +Note that deployment fails expectedly because the MTA defines as required the parameter `service-plan` for resource `my-service`, which represents a service instance. This is done with the MTA parameter metadata called `optional`. By default, the `optional` parameter is set to `false`. Setting it to `true` makes the parameter it refers to optional. Thus the field `service-plan` can be left empty in the descriptor. ```text - name: my-service @@ -45,7 +45,7 @@ Note that deployment fails expectedly because MTA defines required parameter `se ``` -The idea is to oblige the operator, who deploys the MTA to specify the service plan according to the region, organization and space. For example in DEV env free and small service plan is used where in PROD environment, paid and supported plan is used. +The goal is to make the operator deploying the MTA match the service plan to the specific region, organization and space. For example, in a development working environment (DEV), it's usually the free and small service plan that is used. In production environment (PROD), on the other hand, the service plans used are paid and supported. ### Verify the result @@ -53,9 +53,9 @@ Make sure that nothing is created in the space with `cf apps` and `cf services`. ## Deploy MTAR in DEV environment -This step of the example shows how the MTA is deployed in DEV enviroment where the goal is to use minimal resources for application and use free service plan. +This step of the example shows how the MTA is deployed in DEV environment where the goal is to use minimal resources for the application and use a free service plan. -### Deploy with a deployment descriptor (mtad.yaml) +### Deploy with a deployment descriptor (`mtad.yaml`) That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]`, ready application binaries `link:appBits.zip[appBits.zip]` and extension descriptor for DEV env `link:dev.mtaext[dev.mtaext]`: @@ -84,25 +84,25 @@ Starting application "my-app"... ### Verify the result -Check that app and service instance are created, and service has the plan `lite`, defined in the extension descriptor: +Check that the app and service instance are created, and service plan is `lite`, defined in the extension descriptor: ``` bash $ cf s ... -name service plan bound apps last operation ... -my-service application-logs lite my-app create succeeded ... +name offering plan bound apps last operation ... +my-service application-logs lite my-app create succeeded ... $ cf a ... -name requested state instances memory disk urls -my-app started 1/1 1G 1G ... +name requested state processes routes +my-app started web:1/1 ... ``` NOTE: The application has 1 instance, that is defined in the `mtad.yaml`. It uses 1G memory and 1G disk that is default for the platform. ## Deploy MTAR in PROD environment -This step of the example shows how the MTA is deployed in PROD enviroment using `link:prod.mtaext[prod.mtaext]`. The goal is that app and service can handle more load without performance issues. The application is scaled horizontally on 2 instances and the service uses stable paid service plan `standard`: +This step of the example shows how the MTA is deployed in PROD enviroment using `link:prod.mtaext[prod.mtaext]`. The goal is that app and service can handle more load without performance issues. The application is scaled horizontally on 2 instances and the service uses the stable paid service plan `standard`: .prod.mtaext ```text @@ -123,11 +123,11 @@ resources: ``` -NOTE: Extension descriptor extends deployment descriptor id `extends: my-mta` +NOTE: The extension descriptor extends the deployment descriptor id `extends: my-mta` ### Deploy with a deployment descriptor (mtad.yaml) -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]`, ready application binaries `link:appBits.zip[appBits.zip]` and extension descriptor for PROD env `link:prod.mtaext[prod.mtaext]`: +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]`, ready application binaries `link:appBits.zip[appBits.zip]` and extension descriptor for PROD environment `link:prod.mtaext[prod.mtaext]`: ``` bash $ cf deploy -f -e prod.mtaext @@ -154,23 +154,23 @@ Starting application "my-app"... ### Verify the result -Check that app and service instance are created, and service has the plan `standard`, defined in the extension descriptor: +Check that app and service instance are created and service has the plan `lite` defined in the extension descriptor: ``` bash $ cf s ... -name service plan bound apps last operation ... -my-service application-logs standard my-app create succeeded ... +name offering plan bound apps last operation ... +my-service application-logs lite my-app create succeeded ... $ cf a ... -name requested state instances memory disk urls -my-app started 2/2 1G 1G ... +name requested state processes routes +my-app started web:2/2 ... ``` ## Deploy MTAR in PROD environment, scale vertically -This step of the example shows how the MTA is deployed in PROD enviroment using 2 extension descriptors `link:prod.mtaext[prod.mtaext]` and `link:prod-scale-vertically.mtaext[prod-scale-vertically.mtaext]`. The goal is that app and service can handle more load without performance issues. The application is scaled horizontally on 2 instances and vertically using 2G memory: +To handle an increased workload without compromising performance, the application and service will be deployed to the PROD environment using two extension descriptors: `link:prod.mtaext[prod.mtaext]` and `link:prod-scale-vertically.mtaext[prod-scale-vertically.mtaext]`. The application is scaled horizontally on 2 instances and vertically using 2G of memory: .prod-scale-vertically.mtaext ```text @@ -185,13 +185,13 @@ modules: memory: 2G ``` -NOTE: `prod-scale-vertically.mtaext` extends `prod.mtaext` that extends deployment descriptor `mtad.yaml`. It makes extension descriptor chain. +NOTE: `prod-scale-vertically.mtaext` extends `prod.mtaext` that extends deployment descriptor `mtad.yaml`. It makes an extension descriptor chain. NOTE: `memory` parameter is not defined in the deployment descriptor, however it is considered during deployment. -### Deploy with a deployment descriptor (mtad.yaml) +### Deploy with a deployment descriptor (`mtad.yaml`) -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]`, ready application binaries `link:appBits.zip[appBits.zip]` and extension descriptors for PROD env `link:prod.mtaext[prod.mtaext]` and `link:prod-scale-vertically.mtaext[prod-scale-vertically.mtaext]`: +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]`, ready application binaries `link:appBits.zip[appBits.zip]` and 2 extension descriptors for PROD environment: `link:prod.mtaext[prod.mtaext]` and `link:prod-scale-vertically.mtaext[prod-scale-vertically.mtaext]`: ``` bash $ cf deploy -f -e prod.mtaext,prod-scale-vertically.mtaext @@ -224,11 +224,17 @@ Check that app and service instance are created, and app has values defined in b ``` bash $ cf s ... -name service plan bound apps last operation ... -my-service application-logs standard my-app create succeeded ... +name offering plan bound apps last operation ... +my-service application-logs lite my-app create succeeded ... $ cf a ... -name requested state instances memory disk urls -my-app started 2/2 2G 1G ... +name requested state processes routes +my-app started web:2/2 ... +``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services ``` diff --git a/externalize-services-configurations/README.adoc b/externalize-services-configurations/README.adoc index 17482d8..5d07d37 100644 --- a/externalize-services-configurations/README.adoc +++ b/externalize-services-configurations/README.adoc @@ -2,17 +2,17 @@ # Externalize service parameters to file -This example shows how to maintain service instance configuration in dedicated json files, apart the development/deployment yaml. -The content of those files gets merged with the additional configurations defined in the mta(d).yaml and gets used as service instance creation/update parameters +This example shows how to maintain service instance configuration in dedicated json files, apart from the development/deployment yaml. +The content of those files gets merged with the additional configurations defined in the `mta(d).yaml` and gets used as service instance creation/update parameters. -## Modelling +## Modeling ### Service instances -Service instances are modelled as MTA resources of type `org.cloudfoundry.managed-service`. The parameters used for their creation and update can be specified in two places: +Service instances are modeled as MTA resources of type `org.cloudfoundry.managed-service`. The parameters used for their creation and update can be specified in two places: -- in the `config` parameter of the resource -- in an external .json file, referenced in the `path` parameter of the resource +- In the `config` parameter of the resource +- In an external `.json` file, referenced in the `path` parameter of the resource ```yaml resources: @@ -25,48 +25,57 @@ resources: #... ``` -NOTE: The content from the external file and the config parametr's are merged. In case of conflict during merging, the `config` parameter content is overwriting the other. +NOTE: The content from the external file and `config` parameter are merged. In case of conflict during merging, the `config` parameter content will overwrite the other. # Related examples - link:../create-managed-services/README.adoc[Service instance and binding creation with MTAs] ## Requirements -- access to a CF space with quota for creation of service instances +- Access to a Cloud Foundry space with quota for creation of service instances -## Oficial documemtation in Help SAP Portal +## Official documentation in SAP Help Portal - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9e34487b1a8643fb9a93ae6c4894f015.html[Resources] - link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/a36df26b36484129b482ae20c3eb8004.html[Service creation parameters] -# Try out +# Try it out ## Deploy the MTA -The example demostrate 2 different approaches that lead to the same result. -NOTE: please adjust the service label, plan and parameter values to match the available in your environment +The example demostrates 2 different approaches that lead to the same result. +NOTE: Please adjust the service label, plan and parameter values to match the ones available in your environment -### Deploy with a deployment descriptor (mtad.yaml) -That approach uses deployment descritpr `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: +### Deploy with a deployment descriptor (`mtad.yaml`) +This approach uses deployment descriptor `link:mtad.yaml[mtad.yaml]` and ready application binaries `link:appBits.zip[appBits.zip]`: ``` bash -cf deploy ./ -f ; +$ cf deploy ./ -f ; ``` -Alternatively first assemble an MTA archive using the `mtad.yaml` and then deploy the archive: +Alternatively, you can assemble an MTA archive, using the `mtad.yaml` file first: ``` bash -mbt assemble -t ./ ; -cf deploy my-mta_0.0.0.mtar ; +$ mbt assemble -t ./ ; ``` -NOTE: See link:mtad.yaml[mtad.yaml] for the modelling +And then deploy the assembled archive: + +``` bash +$ cf deploy my-mta_0.0.0.mtar ; +``` + +NOTE: See link:mtad.yaml[mtad.yaml] for the modeling ### Build and Deploy -The approach is using development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build MTAR. -Then the MTAR is deployed. +This approach uses development descriptor `link:mta.yaml[mta.yaml]` and application binaries `link:appBits.zip[appBits.zip]` to build an MTAR archive: ``` bash -mbt build -p cf -t . ; -cf deploy a.cf.app_0.0.0.mtar -f ; +$ mbt build -p cf -t . ; +``` + +The MTAR archive is then deployed: + +``` bash +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` NOTE: See link:mta.yaml[mta.yaml] for the concrete modelling @@ -79,8 +88,8 @@ NOTE: See link:mta.yaml[mta.yaml] for the concrete modelling $ cf services Getting services in org deploy-service / space ****** as ******... name service plan -my-service-instance xsuaa application -my-user-provided-service-instance user-provided +my-service-instance xsuaa application +my-user-provided-service-instance user-provided ``` ### List the user provided service instance credentials @@ -98,4 +107,10 @@ $ cf curl /v2/user_provided_service_instances/$(cf service my-user-provided-serv ... ``` -Notice that the user provided service has the properly merged content in the credentials field. \ No newline at end of file +Notice that the user provided service has the properly merged content in the credentials field. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/idle-parameters/README.adoc b/idle-parameters/README.adoc index b72fa43..5b8df0e 100644 --- a/idle-parameters/README.adoc +++ b/idle-parameters/README.adoc @@ -9,47 +9,48 @@ All idle parameters are applicable only for modules that represent Cloud Foundry Idle parameters are used in the validation phase of blue-green deployment where new application versions are mapped to temporary routes, also called idle routes. Idle parameters are used to define explicitly temporary routes. -NOTE: *The reccomended way to create idle route(s) is by using `idle-routes` parameter! All other combinations are possible but should be avoided and used carefully if needed!* +NOTE: *The recommended way to create idle route(s) is by using `idle-routes` parameter! All other combinations are possible but should be avoided and used carefully if needed!* When idle parameter are not defined the SAP Cloud Deployment service will use default behavior to calculate the temporary idle routes: ```text ${org}-${space}-${app-name}-idle.${default-domain} ``` -All these parameters `org`, `space`, `app-name` and `default-domain` are read-only and their values depends on the Cloud Foundry region, org and space. +All these parameters `org`, `space`, `app-name` and `default-domain` are read-only and their values depend on the Cloud Foundry region, org and space. -In Cloud Foundry application routes include a domain, an optional hostname, and an optional context path. In MTA blue-green deployment, idle routes consists of domain, so-called `idle-domain`, and hostname, so-called `idle-host`. Specifying any of the idle parameters influences the idle route(s). +In Cloud Foundry the application routes include a domain, an optional hostname, and an optional context path. In MTA blue-green deployment, idle routes consist of a domain, called `idle-domain`, and hostname, called `idle-host`. Specifying any of the idle parameters influences the idle route(s). Basically, the formula is: ```text idle-route = idle-host.idle-domain ``` -It is possible to define combinations of that parameters. However, if you specify `idle-routes` and one or more of the following parameters: `idle-host`,`idle-hosts`,`idle-domain`,`idle-domains`, only `idle-routes` will be used for blue-green deployment. The rest of specified parameters will be ignored during deployment. +It is possible to use combinations of these parameters. However, if you specify `idle-routes` and one or more of the following parameters: `idle-host`,`idle-hosts`,`idle-domain`,`idle-domains`, only `idle-routes` will be used for blue-green deployment. The rest of the specified parameters will be ignored during deployment. -It is possible to define multiple idle routes: -* Using parameter `idle-routes` and define multiple values -* Using "plural" idle parameters `idle-hosts` and/or `idle-domains`, where all idle routes are cartesian product of all idle hosts and all idle domains: +It is also possible to define multiple idle routes: +* Using parameter `idle-routes` and defining multiple values. +* Using "plural" idle parameters `idle-hosts` and/or `idle-domains`, where all idle routes are a cartesian product of all idle hosts and idle domains: ```text idle-routes = idle-hosts X idle-domains ``` -NOTE: *If you are using custom idle domain, make sure it is already created and existing in the org! The SAP Cloud Deployment service does not create idle domains. The point is applicable when you define any of parameters `idle-routes`, `idle-domain` or `idle-domains`.* +NOTE: *If you are using a custom idle domain, make sure it has already been created and is currently present in the org! The SAP Cloud Deployment service does not create idle domains. This is particularly important to remember when defining any of these parameters: `idle-routes`, `idle-domain` or `idle-domains`.* ## Requirements * Awareness of link:../blue-green-deploy-strategy[MTA blue-green deployment] -## Official documemtation -* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Modules] -> Table Module-Specific Parameters +## Official documentation +* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Module-Specific Parameters] * SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/772ab72204f04946b79ce2d962e64970.html[Blue-Green Deployment of Multitarget Applications] -# Try out +# Try it out -The examples below will demonstrate different combinations of idle parameters and their result. As input for all deployments, the same MTAR will be used but with different extension descriptors. Extension descriptors define idle parameters, so you can examine them. +The examples below will demonstrate different combinations of idle parameters and their result. As input for all deployments, the same MTAR will be used but with different extension descriptors. Extension descriptors define idle parameters so you can examine them. ## Using `idle-routes` -NOTE: *This is the reccomended way to create idle route(s)! You can ignore other optioins in most of the cases.* +NOTE: *This is the recommended way to create idle route(s)! You can ignore the other options in most of the cases.* + +When `idle-routes` is defined, the new app version will be mapped to one or many temporary routes depending on the number of `idle-routes`: -When `idle-routes` is defined, the new app version will be mapped to one or many temporary routes depending on the count of `idle-routes`: ```text parameters: idle-routes: @@ -65,7 +66,8 @@ parameters: | your.second.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-routes.mtaext -f ... @@ -74,7 +76,9 @@ Application "app-blue" started and available at "your-first-idle-hostname.your.f ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -86,9 +90,10 @@ xxxx your-second-idle-hostname our.second.idle.domain ## Using `idle-host` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <> .* +NOTE: *This is NOT the recommended way to create idle route(s)! See <> .* When `idle-host` is defined, the new app version will be mapped only to one temporary route using the `${default-domain}` as domain: + ```text parameters: idle-host: "your-idle-hostname" @@ -100,7 +105,8 @@ parameters: | ${default-domain} |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-host.mtaext -f ... @@ -109,7 +115,8 @@ Application "app-blue" started and available at "your-idle-hostname. app- ## Using `idle-hosts` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <> .* +NOTE: *This is NOT the recommended way to create idle route(s)! See <> .* When `idle-hosts` is defined, the new app version will be mapped to one or many temporary routes using the `${default-domain}` as domain: @@ -137,7 +144,8 @@ parameters: | ${default-domain} |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-hosts.mtaext -f ... @@ -146,7 +154,9 @@ Application "app-blue" started and available at "your-first-idle-hostname. a ## Using `idle-domain` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* When `idle-domain` is defined, the new app version will be mapped only to one temporary route using the `${default-host}-idle` as host: + ```text parameters: idle-domain: "your.idle.domain" @@ -172,7 +183,8 @@ parameters: | your.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-domain.mtaext -f ... @@ -181,7 +193,9 @@ Application "app-blue" started and available at "--app-idle.your.idl ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -192,9 +206,10 @@ xxxx --app-idle your.idle.domain app- ## Using `idle-domains` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* When `idle-domains` is defined, the new app version will be mapped only to one or many temporary routes using the ${default-host}-idle` as host: + ```text parameters: idle-domains: ["your.first.idle.domain", "your.second.idle.domain"] @@ -208,7 +223,8 @@ parameters: | your.second.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-domains.mtaext -f ... @@ -217,7 +233,9 @@ Application "app-blue" started and available at "--app-idle.your.idl ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -227,11 +245,12 @@ xxxx --app-idle your.idle.domain xxxx --app-idle your.second.idle.domain app-blue ``` -## Using combination of `idle-host` and `idle-domain` +## Using a combination of `idle-host` and `idle-domain` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* When both `idle-host` and `idle-domain` are defined, the new app version will be mapped only to one temporary route: + ```text parameters: idle-host: "your-idle-hostname" @@ -244,7 +263,8 @@ parameters: | your.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-host-idle-domain.mtaext -f ... @@ -253,7 +273,9 @@ Application "app-blue" started and available at "your-idle-hostname.your.idle.do ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -262,11 +284,12 @@ space host domain port path type apps s xxxx your-idle-hostname your.idle.domain app-blue ``` -## Using combination of `idle-host` and `idle-domains` +## Using a combination of `idle-host` and `idle-domains` + +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +When both `idle-host` and `idle-domains` are defined, the new app version will be mapped to one or more temporary routes depending on the number of `idle-domains`: -When both `idle-host` and `idle-domains` are defined, the new app version will be mapped to one or more temporary routes depending on th number of `idle-domains`: ```text parameters: idle-host: "your-idle-hostname" @@ -281,7 +304,8 @@ parameters: | your.second.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-host-idle-domains.mtaext -f ... @@ -290,7 +314,9 @@ Application "app-blue" started and available at "your-idle-hostname.your.first.i ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -300,9 +326,9 @@ xxxx your-idle-hostname your.first.idle.domain app- xxxx your-idle-hostname your.second.idle.domain app-blue ``` -## Using combination of `idle-hosts` and `idle-domain` +## Using a combination of `idle-hosts` and `idle-domain` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* When both `idle-hosts` and `idle-domain` are defined, the new app version will be mapped to one or more temporary routes depending on the number of `idle-hosts`: @@ -320,7 +346,8 @@ parameters: | your.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-hosts-idle-domain.mtaext -f ... @@ -329,7 +356,9 @@ Application "app-blue" started and available at "your-first-idle-hostname.your.i ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -339,19 +368,20 @@ xxxx your-idle-hostname your.idle.domain app-b xxxx your-second-idle-hostname your.idle.domain app-blue ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... space host domain port path type apps services -xxxx your-idle-hostname your.first.idle.domain app-blue -xxxx your-idle-hostname your.second.idle.domain app-blue +xxxx your-idle-hostname your.first.idle.domain app-blue +xxxx your-idle-hostname your.second.idle.domain app-blue ``` ## Using combination of `idle-hosts` and `idle-domains` -NOTE: *This is NOT the reccomended way to create idle route(s)! See <>.* +NOTE: *This is NOT the recommended way to create idle route(s)! See <>.* When both `idle-hosts` and `idle-domains` are defined, the new app version will be mapped to one or more temporary routes depending on the number of `idle-hosts` and `idle-domains`: @@ -373,7 +403,8 @@ parameters: | your.second.idle.domain |=== -### Execute Deploy +### Execute deploy + ```bash $ cf bg-deploy ./ -e idle-hosts-idle-domains.mtaext -f ... @@ -382,7 +413,9 @@ Application "app-blue" started and available at "your-first-idle-hostname.your.f ``` ### Examine the result -Check what are the created routes and which apps are mapped to them + +Check what are the created routes and which apps are mapped to them: + ```bash $ cf r Getting routes for org xxxx / space xxxx as xxx ... @@ -393,3 +426,9 @@ xxxx your-first-idle-hostname your.second.idle.domain xxxx your-second-idle-hostname your.first.idle.domain app-blue xxxx your-second-idle-hostname your.second.idle.domain app-blue ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/keep-existing-bindings/README.adoc b/keep-existing-bindings/README.adoc index 394cb63..bd12bdd 100644 --- a/keep-existing-bindings/README.adoc +++ b/keep-existing-bindings/README.adoc @@ -15,48 +15,78 @@ modules: ## Official Documentation -* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Modules] -> Table Module-Specific Parameters +* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Module-Specific Parameters] NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] in the current directory. -## Try out +## Try it out ### Initial deployment -In that part the MTA will be initially deployed when two applications are deployed and one service instance. There is not binding between them. +In this part the MTA will initially be deployed with two applications and one service instance. However, there is no binding between them. + +You can deploy it directly from an `mtad.yaml` file: + +```bash +$ cf deploy ./ -f ; +``` + +Alternatively, you can build an MTAR archive from the `mta.yaml` file: -directly from an mtad.yaml ```bash - $ cf deploy ./ -f ; +$ mbt build -p cf -t . ; ``` -or start from an mta.yaml: + +And then deploy the built MTAR archive: + ```bash - $ mbt build -p cf -t . ; - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` + ### Manually bind service instance + +Run the following commands: + ```bash - $ cf bind-service cf-app-keeping-bindings dummy-service - $ cf bind-service cf-app-resetting-bindings dummy-service +$ cf bind-service cf-app-keeping-bindings dummy-service +$ cf bind-service cf-app-resetting-bindings dummy-service ``` + #### Examine the result + +To examine the result, run the following command: + ```bash - $ cf services +$ cf services Getting services in org ... name service ... bound apps ... dummy-service user-provided cf-app-keeping-bindings, cf-app-resetting-bindings ``` + ### Re-deply to simulate update + ```bash - $ cf deploy -f ; - # or - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy -f ; +``` + +or + +```bash +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` #### Examine the result + Verify that app `cf-app-keeping-bindings` has the binding preserved and app `cf-app-keeping-bindings` has lost the binding. + ```bash - $ cf services +$ cf services Getting services in org ... name service ... bound apps ... dummy-service user-provided cf-app-keeping-bindings ``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/keep-existing-env/README.adoc b/keep-existing-env/README.adoc index 7a8ba2d..5e64c06 100644 --- a/keep-existing-env/README.adoc +++ b/keep-existing-env/README.adoc @@ -2,9 +2,9 @@ :toc: ## Overview -This example shows how to preserve manually set app environment variables during MTA deployment. The may be used used e.g. when an operator changes an app configuration, which should not be reverted, in case that configuration is not maintained in an *.mtaext extension descriptor given during deployment. +This example shows how to preserve manually set app environment variables during MTA deployment. This strategy may be useful, for instance, when an operator modifies an app configuration. The modifications should remain even if the configuration isn't maintained in a particular `*.mtaext` extension descriptor, which is provided during deployment. -Modelled via a module level parameter `keep-existing:...` +It is modeled via a module level parameter `keep-existing:...` ```bash modules: @@ -17,46 +17,58 @@ NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] in the current di ## Official Documentation -* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Modules] -> Table Module-Specific Parameters +* SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html#loio177d34d45e3d4fd99f4eeeffc5814cf1__section_moduleSpecificParameters[Module-Specific Parameters] -## Try out +## Try it out ### Initial deployment -directly from an mtad.yaml +You can deploy it directly from an `mtad.yaml` file: + ```bash - $ cf deploy ./ -f ; +$ cf deploy ./ -f ; ``` -or start from an mta.yaml: + +Or build an MTAR archive from an `mta.yaml`: + ```bash - $ mbt build -p cf -t . ; - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ mbt build -p cf -t . ; ``` + +And then deploy the built MTAR archive: + +```bash +$ cf deploy a.cf.app_0.0.0.mtar -f ; +``` + ### Examine the initial state + ```bash - $ cf env cf-app-keeping-env-changes +$ cf env cf-app-keeping-env-changes ... User-Provided: ... managed-env-variable: original-env-var-val ``` ```bash - $ cf env cf-app-resetting-env +$ cf env cf-app-resetting-env ... User-Provided: ... managed-env-variable: original-env-var-val ``` ### Manually set a new env variable + ```bash - $ cf set-env cf-app-keeping-env-changes new-env-variable new-env-var-val - $ cf set-env cf-app-keeping-env-changes managed-env-variable changed-env-var-val - $ cf set-env cf-app-resetting-env new-env-variable new-env-var-val - $ cf set-env cf-app-resetting-env managed-env-variable changed-env-var-val - +$ cf set-env cf-app-keeping-env-changes new-env-variable new-env-var-val +$ cf set-env cf-app-keeping-env-changes managed-env-variable changed-env-var-val +$ cf set-env cf-app-resetting-env new-env-variable new-env-var-val +$ cf set-env cf-app-resetting-env managed-env-variable changed-env-var-val ``` + ### Examine the change + ```bash - $ cf env cf-app-keeping-env-changes +$ cf env cf-app-keeping-env-changes ... User-Provided: ... @@ -64,23 +76,30 @@ managed-env-variable: changed-env-var-val new-env-variable: new-env-var-val ``` ```bash - $ cf env cf-app-resetting-env +$ cf env cf-app-resetting-env ... User-Provided: ... managed-env-variable: changed-env-var-val new-env-variable: new-env-var-val ``` + ### Re-deply to simulate update + ```bash - $ cf deploy -f ; - # or - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy -f ; +``` + +Or + +```bash +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` ### Check out the result + ```bash - $ cf env cf-app-keeping-env-changes +$ cf env cf-app-keeping-env-changes ... User-Provided: ... @@ -88,12 +107,19 @@ managed-env-variable: original-env-var-val new-env-variable: new-env-var-val ``` ```bash - $ cf env cf-app-resetting-env +$ cf env cf-app-resetting-env ... User-Provided: ... managed-env-variable: original-env-var-val ``` -Note that app `cf-app-keeping-env-changes` has the `new-env-variable` var kept, but has the `managed-env-variable` value's reset as defined in the mtad.yaml. +Note that app `cf-app-keeping-env-changes` has the `new-env-variable` var kept, but has the value of `managed-env-variable` reset as defined in the `mtad.yaml`. App `cf-app-resetting-env` has lost the custom env variable and also has the `managed-env-variable` value reset. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` + diff --git a/keep-existing-routes/README.adoc b/keep-existing-routes/README.adoc index f884812..7066205 100644 --- a/keep-existing-routes/README.adoc +++ b/keep-existing-routes/README.adoc @@ -2,9 +2,9 @@ :toc: ## Overview -This example shows how to preserve manual mappings of app routes during MTA deployment. The feature is usually used e.g. when tenant onboarding of multitenant apps creates a route for each tenant, and that route is not maintained e.g. in an *.mtaext - extension descriptor given to the MTA deployer. +This example shows how to preserve manual mappings of app routes during MTA deployment. This feature tends to be useful, for instance, when tenant onboarding for multitenant apps generates a separate route for each tenant and that route is not maintained in an *.mtaext extension descriptor given to the MTA deployer. -Activated in 3 ways: +It can be activated in 3 ways: * global parameter `keep-existing-routes: true` * module level parameter `keep-existing-routes: true` @@ -18,24 +18,36 @@ Activated in 3 ways: ``` NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] in the current directory. -### 1 Deploy -directly from an mtad.yaml +### Deploy + +You can deploy it directly from an `mtad.yaml` file: + +```bash +$ cf deploy ./ -f ; +``` + +Alternatively, you can build an MTAR archive from an `mta.yaml` file: + ```bash - $ cf deploy ./ -f ; +$ mbt build -p cf -t . ; ``` -or start from an mta.yaml: + +And then deploy the built MTAR archive: + ```bash - $ mbt build -p cf -t . ; - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 2 Manually map routes to the cf apps + +### Manually map routes to the Cloud Foundry apps + ```bash - $ cf map-route cf-app-unmapping-routes apps.internal --hostname "custom-host" - $ cf map-route cf-app-keeping-complex-param apps.internal --hostname "custom-host" - $ cf map-route cf-app-keeping-simple-param apps.internal --hostname "custom-host" +$ cf map-route cf-app-unmapping-routes apps.internal --hostname "custom-host" +$ cf map-route cf-app-keeping-complex-param apps.internal --hostname "custom-host" +$ cf map-route cf-app-keeping-simple-param apps.internal --hostname "custom-host" ``` -### 3 Examine the new routing +### Examine the new routing + ```bash $ cf apps Getting apps in org ... @@ -44,14 +56,20 @@ cf-app-keeping-complex-param started 1/1 1G 1G cus cf-app-keeping-simple-param started 1/1 1G 1G custom-host.apps.internal, --cf-app-keeping-simple-param. cf-app-unmapping-routes started 1/1 1G 1G custom-host.apps.internal, --cf-app-unmapping-routes. ``` -### 3 Re-deply to simulate update + +### Re-deply to simulate update + +```bash +$ cf deploy -f ; +``` +or: + ```bash - $ cf deploy -f ; - # or - $ cf deploy a.cf.app_0.0.0.mtar -f ; +$ cf deploy a.cf.app_0.0.0.mtar -f ; ``` -### 4 Check out the result +### Check out the result + ```bash $ cf apps Getting apps in org ... @@ -60,4 +78,11 @@ cf-app-keeping-complex-param started 1/1 1G 1G cus cf-app-keeping-simple-param started 1/1 1G 1G custom-host.apps.internal, --cf-app-keeping-simple-param. cf-app-unmapping-routes started 1/1 1G 1G --cf-app-unmapping-routes. ``` -Note that apps having 'keep-existing..' parameters activate, have the url `custom-host.apps.internal`. App `cf-app-unmapping-routes` has it unmapped. +Note that apps that have their 'keep-existing..' parameters activated have the url `custom-host.apps.internal`. However, in the app `cf-app-unmapping-routes` has the url unmapped. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` + diff --git a/parallel-deployment/README.adoc b/parallel-deployment/README.adoc index fe31839..cab2d72 100644 --- a/parallel-deployment/README.adoc +++ b/parallel-deployment/README.adoc @@ -2,11 +2,11 @@ # Parallel deployment -Parallel deployment is a feature that allows to speed-up the deploy proces by processing multiple MTA modules in parallel. The feature is applicable either for standard and blue-green deployment scenarios. +Parallel deployment is a feature that allows to speed-up the deployment proces by processing multiple MTA modules in parallel. The feature is applicable for standard and blue-green deployment scenarios. -Parallel deployment feature concerns SAP Business Technology Platform entities that are represented by MTA modules - applications and application contents. +Parallel deployment feature relates to SAP Business Technology Platform entities that are represented by MTA modules - applications and application contents. -The feature does not relate to entities represented by MTA resources, for instance Cloud Foundry services. By default Cloud Foundry servicecs are processed in parallel without need of any additional configuration. +The feature does not relate to entities represented by MTA resources, for instance Cloud Foundry services. By default Cloud Foundry servicecs are processed in parallel without the need of any additional configuration. ## Official Documentation * SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/177d34d45e3d4fd99f4eeeffc5814cf1.html[Modules] @@ -28,11 +28,11 @@ parameters: enable-parallel-deployments: true ... ``` -NOTE: Setting up the value of `enable-parallel-deployments` can be done in the mta.yaml, mtad.yaml or via an additional extension descriptor (*.mtaext) passed during deployment +NOTE: Setting up the value of `enable-parallel-deployments` can be done in the `mta.yaml`, `mtad.yaml` or via an additional extension descriptor (`*.mtaext`) passed during deployment ## Deployment order -When parallel deployment is activated, all modules are deployed simultaineously. There are cases when a module has a dependency to another - e.g. the module initializing the database should be deployed before the others consuming that same database. +When parallel deployment is activated, all modules are deployed simultaneously. There are cases when a module is dependent on another - for example the module initializing the database should be deployed before the others consuming that same database. The module element `deployed-after` should be used to declare that dependency and influence the order of behavior: @@ -50,7 +50,7 @@ modules: ``` # Try it out -In the current directory you'll find example cf app payload modelled to be deployed in parallel in both +In the current directory you'll find an example cf app payload modeled to be deployed in parallel in both: * development descriptor: link:mta.yaml[mta.yaml] * deployment descriptor: link:mtad.yaml[mtad.yaml] @@ -58,13 +58,14 @@ In the current directory you'll find example cf app payload modelled to be deplo ** enabling parallelization: link:hello-world-parallel.mtaext[hello-world-parallel.mtaext] ** disabling parallelization: link:hello-world-no-parallel.mtaext[hello-world-no-parallel.mtaext] -The example MTA contains 4 modules `hello-world`, `hello-world-first`, `hello-world-second` and `hello-world-third` where 3 of them does not have any dependency order and will be processed in parallel accordingly. Only `hello-world-third` depends on `hello-world`, so it will be processed after `hello-world` is completed. +The example MTA contains 4 modules: `hello-world`, `hello-world-first`, `hello-world-second` and `hello-world-third`. 3 of them do not have any dependency order and will be processed in parallel accordingly. Only `hello-world-third` depends on `hello-world`, so it will be processed after the deployment of `hello-world` is completed. ## Deploy directly from directory -In the current directory of the repository, run `cf deploy` that will use `mtad.yaml`. This will automatically assemble an MTA archive and deploy it +In the current directory of the repository, run the command `cf deploy`. It will use the existing `mtad.yaml` file to automatically assemble an MTA archive and deploy it. + ```bash -$cf deploy +$ cf deploy Deploying multi-target app archive ~/mta-examples/hello-world.mtar in org ****** / space ****** as ******... ... Updating application "hello-world-second"... @@ -73,8 +74,8 @@ Uploading application "hello-world-second"... ... ``` -## Assemble MTA archive via mtad.yaml and deploy -First use `mbt assemble` to create the *.mtar from development descritpror `mta.yaml` and than deploy it with `cf deploy`. +## Assemble an MTA archive via `mta.yaml` and deploy +First run the command `mbt assemble` to create the MTAR archive from development descriptor `mta.yaml`: ```bash $ mbt assemble @@ -84,14 +85,19 @@ $ mbt assemble INFO generating the MTA archive... INFO the MTA archive generated at: /mta_examples/parallel-deployment/mta_archives/hello-world_1.0.0.mtar INFO cleaning temporary files... - +``` + +Then deploy the assembled MTAR archive: + +```bash $ cf deploy mta_archives/hello-world_1.0.0.mtar Deploying multi-target app archive mta_archives/hello-world_1.0.0.mtar in org ****** / space ****** as ******... Uploading 1 files... ``` -## Build MTA archive via mta.yaml and deploy -First use `mbt build` to create the *.mtar and than deploy it with `cf deploy`. +## Build an MTA archive via `mta.yaml` and deploy +First run the command `mbt build` to create the MTAR archive: + ```bash $ mbt build INFO generating the "Makefile_20191029153016.mta" file... @@ -111,18 +117,29 @@ $ mbt build INFO generating the MTA archive... INFO the MTA archive generated at: /mta_examples/parallel-deployment/mta_archives/hello-world_1.0.0.mtar INFO cleaning temporary files... - +``` + +Then deploy the built MTAR archive: + +```bash $ cf deploy mta_archives/hello-world_1.0.0.mtar Deploying multi-target app archive mta_archives/hello-world_1.0.0.mtar in org ***** / space ****** as ******... Uploading 1 files... ... ``` -## Enable/disable parallel deployments with extension descriptors using created *.mtar file +## Enable/disable parallel deployments with extension descriptors using created MTAR file + ```bash -cf deploy mta_archives/hello-world_1.0.0.mtar -e hello-world-parallel.mtaext +$ cf deploy mta_archives/hello-world_1.0.0.mtar -e hello-world-parallel.mtaext ``` ```bash -cf deploy mta_archives/hello-world_1.0.0.mtar -e hello-world-no-parallel.mtaext +$ cf deploy mta_archives/hello-world_1.0.0.mtar -e hello-world-no-parallel.mtaext ``` Note the processing of the MTA in the command output of both commands. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` diff --git a/partial-build-deploy/README.adoc b/partial-build-deploy/README.adoc index e708fda..56adbf9 100644 --- a/partial-build-deploy/README.adoc +++ b/partial-build-deploy/README.adoc @@ -2,13 +2,13 @@ # Partial deployment -Partial deployment is a feature allowing fine control over which parts of the MTA are getting processed by the SAP Cloud Deployment service and which not. -One is able to select only certain module(s) and/or resource(s) for deployment. The SAP Cloud Deployment service takes care to orchestrate the deployment only for the selected parts and skips the rest. +Partial deployment is a feature allowing fine control over which parts of the MTA will get processed by the SAP Cloud Deployment service. +With this feature you can choose to deploy only certain module(s) and/or resource(s). The SAP Cloud Deployment service then orchestrates the deployment only for the selected parts while ignoring the rest. -WARNING: All descriptor validations and dependency cheks on the processed modules are always executed. If the MTA archive is invalid or e.g. an module has a missing dependency (i.e. service instance which should be bound to but does not exist), deployment fails. +WARNING: All descriptor validations and dependency checks on the processed modules are always executed. If the MTA archive is invalid or, for example, a module has a missing dependency (i.e. service instance which it should be bound to but does not exist), the deployment fails. ## Usage -To use feature, pass one of the following environment variablest to the `cf deploy` or `cf bg-deploy commands` +To use this feature, pass one of the following environment variablest to the `cf deploy` or `cf bg-deploy commands`: |=== |-m | @@ -24,22 +24,23 @@ Deploy all resources.ß |=== ## Partial build & assembly -Only selected moduels would be built and included in the MTA archive. This optimizes built & assembly time, the archive size and respectfully upload & processing time in the SAP Cloud Deployment service. + +Only selected modules would be built and included in the MTA archive. This optimizes built & assembly time, the archive size and respectively the upload & processing time in the SAP Cloud Deployment service. ### Partial build -If you only maintain a design time descriptor, the mta.yaml file, for your project or your module should be built before it can be deployed using the partial deployment commands, you can use link:https://sap.github.io/cloud-mta-build-tool/usage/#auxiliary-commands[the auxiliary commands of the Cloud MTA archive builder] to prepare the required artifacts: the modules build results and the deployment descriptor, the mtad.yaml file. +If you only maintain a design time descriptor for your project or module - the `mta.yaml` file, it needs to be built before you can deploy it using partial deployment commands. In order to prepare the required artifacts, which include the build results for the modules and the deployment descriptor, or the `mtad.yaml` file, you can use link:https://sap.github.io/cloud-mta-build-tool/usage/#auxiliary-commands[the auxiliary commands of the Cloud MTA archive builder]. -You can find a few tips about usage of the Cloud MTA Builder commands for the partial build in the "Build only specific MTA modules defined in the mta.yaml file and deploy them" section below. +You can find a few tips about usage of the Cloud MTA Builder commands for the partial build in the "Build only specific MTA modules defined in the `mta.yaml` file and deploy them" section below. ### Partial assembly -If staring from mtad.yaml, the cf deploy command is capable of assembling an MTA archive just before deployment. The list of modules passed to the (bg-)deploy command is used to select which would be included in the assembled archive. +If initiated from a `mtad.yaml`, the `cf deploy` command is capable of assembling an MTA archive just before deployment. The list of modules passed to the `(bg-)deploy` command is used to determine which would be included in the assembled archive. -NOTE: the modules `path` argument has to be maintained for assembly to work. All selected modules should have such pointing to properly build module bits. +NOTE: For the assembly to work properly, it's necessary to maintain the `path` argument in the modules. All selected modules should have this `path` argument pointing to the appropriate module bits. ## Partial deploy -In the current directory you'll find example cf app payload with the following structure: +In the current directory you'll find an example Cloud Foundry app payload with the following structure: image::MTAstructure.png[mta structure diagram] @@ -50,10 +51,12 @@ image::MTAstructure.png[mta structure diagram] ## Official Documentation * SAP Help Portal: link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/65ddb1b51a0642148c6b468a759a8a2e.html[Multitarget Application Commands for the Cloud Foundry Environment] -# Try out +# Try it out + +## Deploy directly from directory, via `mtad.yaml` + +In the current directory, run the command `cf deploy -m module-b -r service-2`. This will automatically assemble an MTA archive and deploy it: -## Deploy directly from directory, via mtad.yaml -In the current directory, run `cf deploy -m module-b -r service-2`. This will automatically assemble an MTA archive and deploy it ```bash $ cf deploy -m module-b -r service-2 Deploying multi-target app archive */mta-examples/hello-world.mtar in org ******** / space ******** as **** ... @@ -74,50 +77,58 @@ Application "module-b" started and available at "******-*-module-b.cfapps.sap.ha Skipping deletion of services, because the command line option "--delete-services" is not specified. Process finished. ``` -## Assemble MTA archive via mtad.yaml and deploy -First use `mbt assemble` to create the *.mtar and than deploy it with `cf deploy`. +## Assemble an MTA archive via `mtad.yaml` and deploy it + +First run the command `mbt assemble` to create the MTAR archive: -NOTE: This approach is less efficient, as all modules are included in the MTA archive and uploaded to the SAP Cloud Deployment service. Regardless that only the selected ones are processed. ```bash -$$ mbt assemble +$ mbt assemble INFO assembling the MTA project... INFO copying the MTA content... INFO generating the metadata... INFO generating the MTA archive... INFO the MTA archive generated at: /Users/i076083/git/mta_examples/partial-build-deploy/mta_archives/hello-world_1.0.0.mtar INFO cleaning temporary files... -$ cf deploy mta_archives/hello-world_1.0.0.mtar -m module-c -r service-3 - ... ``` -## Build only specific MTA modules defined in the mta.yaml file and deploy them -NOTE: Since partial deploymnet requires that all the modules' and resources' dependencies are resolved, we recommend you first build and deploy the complete MTA project (using the `mbt build` command to create the MTA archive (`mtar`) file and the `cf deploy` command to deploy it) and then build and deploy only the changing modules. +Then deploy the assembled MTAR archive: -The command for building specific modules using the Cloud MTA Builder Tool is: ```bash -`mbt module-build -m= [options]` +$ cf deploy mta_archives/hello-world_1.0.0.mtar -m module-c -r service-3 + ... ``` +NOTE: This approach is less efficient, as all modules are included in the MTA archive and uploaded to the SAP Cloud Deployment service, while only the selected ones are processed. -NOTE: We recommend you to always apply `-g` option that generates also the deployment descriptor, the `mtad.yaml` file. The `path` property for the selected deployable modules in this `mtad.yaml` will point to the build results of these modules, so you will be able to immediately run the partial deployment command as described in the "Deploy directly from directory, via mtad.yaml" section. +## Build only specific MTA modules defined in the `mta.yaml` file and deploy them +NOTE: Since partial deployment requires all the modules' and resources' dependencies to be resolved, we recommend that you first build and deploy the complete MTA project (using the `mbt build` command to create the MTA archive (`mtar`) file and the `cf deploy` command to deploy it) and then build and deploy only the changing modules. -In the examples below we demonstrate how to use the partial build command in different use cases. These examples are based on the project straucture described above and this link:mta.yaml[mta.yaml] file. +The command for building specific modules using the Cloud MTA Builder Tool is: +```bash +$ mbt module-build -m= [options]` +``` + +NOTE: We recommend that you always apply the `-g` option that also generates the deployment descriptor - the `mtad.yaml` file. The `path` property for the selected deployable modules in this `mtad.yaml` will point to the build results of these modules, so you will be able to immediately run the partial deployment command as described in the "Deploy directly from directory via mtad.yaml" section. + +In the examples below we demonstrate how to use the partial build command in different use cases. These examples are based on the project structure described above and this link:mta.yaml[mta.yaml] file. ### Building a single independent module + ```bash $ mbt module-build -m module-b -g ``` ### Buiding several independent modules + ```bash $ mbt module-build -m module-b,module-c -g - ``` + ### Buiding a module with build dependencies -Build dependencies are defined via the `requires` property of the `build-parameters` section in the `mta.yaml` file. For more information, read link:https://sap.github.io/cloud-mta-build-tool/configuration/#configuring-build-order[here]. +Build dependencies are defined via the `requires` property of the `build-parameters` section in the `mta.yaml` file. You can find more information link:https://sap.github.io/cloud-mta-build-tool/configuration/#configuring-build-order[here]. In the sample project, `module-a` depends on modules `module-b` and `module-c`. @@ -126,26 +137,28 @@ You can build the `module-a` module with all its dependencies using the followin ```bash $ mbt module-build -m module-a -a -g ``` + The `module-b` and `module-c` modules will be built before the tool builds the `module-a` module. -If you change now the `module-b` module and would like to re-build and re-deploy the `module-a` module, use the following command: +If you now change the `module-b` module and would like to re-build and re-deploy the `module-a` module, use the following command: ```bash $ mbt module-build -m module-a,module-b -g ``` + The tool will build the specified modules only in the correct order. -For the complete information about the Cloud MTA Build Tools partial build options, read link:https://sap.github.io/cloud-mta-build-tool/usage/#auxiliary-commands[here] +You can find the complete information about the Cloud MTA Build Tools partial build options link:https://sap.github.io/cloud-mta-build-tool/usage/#auxiliary-commands[here]. -Once you have your modules built and the mtad.yaml file generated, you can use the partial deployment command as described in the "Deploy directly from directory, via mtad.yaml" section. +Once you have your modules built and the `mtad.yaml` file generated, you can use the partial deployment command as described in the "Deploy directly from directory via mtad.yaml" section. ## Dependency validations -WARNING: When selecting an MTA module/resource for processing, make sure it's dependencies are also selected or are already existing. +WARNING: When selecting an MTA module/resource for processing, make sure its dependencies are also selected or are already existing. -E.g. If in a clean environment, only a module is selected, without the services it depends on - deployment would fail +If in a clean environment, for example, a module is selected without the services it depends on, the deployment would fail. ```bash $ cf undeploy hello-world --delete-services -f @@ -173,3 +186,10 @@ Application "module-b" started and available at "******-*-module-b.cfapps.sap.ha Process finished. ``` NOTE: If you expect to redeploy MTA modules/resources multiple times e.g. when doing minor adjustments to them - it may make sense to do a full deployment once and later only update the modules/resources you want. + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` + diff --git a/sharing-values-between-apps/README.adoc b/sharing-values-between-apps/README.adoc index f39d407..92b3798 100644 --- a/sharing-values-between-apps/README.adoc +++ b/sharing-values-between-apps/README.adoc @@ -2,7 +2,7 @@ # Sharing configuration values between apps -The MTA deployment descriptor allows for fixed or dynamically generated values to be shared between the described entities (modules & resources). For one module/resource to consume exposed variables from another, it has to declare it's dependency to ti in the `requires` element. As in MTAs apps are defined as modules, this mechanism can be used to e.g. share the url of one app in the environment of another: +The MTA deployment descriptor allows for fixed or dynamically generated values to be shared between the described entities (modules & resources). For one module/resource to consume exposed variables from another, it has to declare its dependency to it in the `requires` element. As in MTAs apps are defined as modules, this mechanism can be used to share the url of one app in the environment of another: ```yaml modules: @@ -30,17 +30,20 @@ modules: NOTE: See link:mta.yaml[mta.yaml] and link:mtad.yaml[mtad.yaml] as references for working development and deployment descriptors. ## Requirements -- understanding of how link:../cf-app/README.adoc[cf applications are modelled in an MTA] +- Understanding how link:../cf-app/README.adoc[Cloud Foundry applications are modeled in an MTA] -## Oficial documemtation in Help SAP Portal -- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/490c8f71e2b74bc0a59302cada66117c.html[Parameters and Properties page] +## Official documentation in the Help SAP Portal +- link:https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/490c8f71e2b74bc0a59302cada66117c.html[Parameters and Properties] + +# Try it out -# Try out ## Deploy -You can directly deploy the built app of this example from the current directory and the modelled link:mtad.yaml[mtad.yaml deployment descriptor] + +### Deploy from directory +You can directly deploy the built app of this example from the current directory and the modeled link:mtad.yaml[mtad.yaml deployment descriptor]: ```bash -$cf deploy ./ +$ cf deploy ./ Deploying multi-target app archive ********/sharing-values-between-apps/my-mta.mtar in org deploy-service / space ******** as ********... Uploading 1 files... ********/sharing-values-between-apps/my-mta.mtar @@ -49,38 +52,55 @@ Deploying in org "deploy-service" and space "********" ... Process finished. ``` -### Alternatively build & deploy the mta from mta.yaml - To build and deploy an MTA from a link:mta.yaml[mta.yaml development descriptor], instead of `cf deploy ./` run the following commands + +### Build and deploy from mta.yaml file +Alternatively, you can build & deploy the MTA from mta.yaml. To build and deploy an MTA from a link:mta.yaml[mta.yaml development descriptor], run the commands described below. + +First build & assemble the MTA archive: + ```bash -#first build & assemble the mta archive $ mbt build [2020-04-02 23:47:34] INFO Cloud MTA Build Tool version 1.0.8 [2020-04-02 23:47:34] INFO generating the "Makefile_20200402234734.mta" file... ... [2020-04-02 23:47:34] INFO the MTA archive generated at: ... -#then deploy the assembled package -$cf deploy mta_archives/my-mta_0.0.0-SNAPSHOT.mtar +``` + +Then deploy the assembled package: + +```bash +$ cf deploy mta_archives/my-mta_0.0.0-SNAPSHOT.mtar ... - ``` +``` ## Verify the result +Check the actual app url: + ```bash -#let's see the actuall app url -cf app providing-module | grep routes +$ cf app providing-module | grep routes routes: deploy-service-********-providing-module.cfapps.sap.hana.ondemand.com +``` + +Let's see the generated user value: -#let's see the generated user value +```bash $ cf env providing-module | grep my-generated-user my-generated-user: u]rPqDU-70y(-E0c +``` -# and let's see how the second app consumed the provided values +Finally, let's see how the second app consumed the provided values: +```bash $ cf env consuming-module | grep m1 m1-config: static-string-with-suffix m1-url: https://deploy-service-********-providing-module.cfapps.sap.hana.ondemand.com m1-user: u]rPqDU-70y(-E0c +``` + +## Clean up resources +It is recommended to stop or undeploy your MTAs when they are no longer needed. In order to do so, run the following command: +``` bash +$ cf undeploy -f --delete-services +``` -#consumed as expected :) - -``` \ No newline at end of file