multitarget-application-commands-for-the-cloud-foundry-environment-65ddb1b.md

Multitarget Application Commands for the Cloud Foundry Environment

A list of additional commands to deploy multitarget applications (MTA) to the Cloud Foundry environment.

Note:

The expiration time for all MTA operations in Cloud Foundry is 3 days. If an operation is still active when time limit is reached, it is automatically aborted.

Caution:

Due to the missing shared domains in certain regions, as China (Shanghai), the URL of the SAP Cloud Deployment service should be specified by each multitarget application developer who uses MultiApps CF CLI plugin older that 3.0.0. If you are using MultiApps CF CLI plugin newer than 3.0.0, you do not need additional settings. You can do this by using the environment variable MULTIAPPS_CONTROLLER_URL, or the -u option specified in the commands listed below.

The URL of the deploy-service that needs to be set is in the following format: deploy-service.cf.<domain> The domain is derived from the Cloud Foundry API endpoint that you can find in the SAP BTP Cockpit in the Overview of your subaccount. For more information, see Deploying Applications inRegions and Regions and API Endpoints Available for the Cloud Foundry Environment.

If you are using the -u option, make sure you have the MultiApps CLI Plugin version 2.1.3 or higher

If you are using region CN40 with API Endpoint api.cf.cn40.platform.sapcloud.cn, you need to specify the URL as follows: export MULTIAPPS_CONTROLLER_URL=deploy-service.cf.cn40.platform.sapcloud.cn

Commands for the Cloud Foundry Environment Overview

Command	Alias	Description
deploy		Deploy a new Multitarget Application (MTA) or synchronize changes to an existing MTA.
bg-deploy		Deploy a Multitarget Application using “blue-green” (zero-downtime) deployment.
undeploy		Undeploy a Multitarget Application (MTA).
mta		Display information about a deployed Multitarget Application (MTA).
mtas		List all deployed Multitarget Applications (MTA).
mta-ops		List all active operations for Multitarget Applications.
download-mta-op-logs	dmol	Download the log files for one or more operations concerning Multitarget Applications.
purge-mta-config		Purge all configuration entries and subscriptions, which are no longer valid.

Note:

By default, large multitarget applications are not uploaded as a single unit, but are split up into smaller chunks of 45 MBs that are uploaded separately. Configure the chunk size as described in Configuration.

deploy

Deploy a new MTA or synchronize changes to an existing one. You have the following options for doing this:

Usage

• Deployment using a path to a directory

  You have the option to deploy or synchronize an MTA, the source of which is contained in a local directory:

  cf deploy MTA_ARCHIVE | DIRECTORY_PATH [-e EXT_DESCRIPTOR[,...]] [-t TIMEOUT] 
  [--version-rule VERSION_RULE] [-u URL] [-f] [--retries RETRIES] [--no-start] [--namespace NAMESPACE] 
  [--apply-namespace-app-names true/false] [--apply-namespace-service-names true/false] 
  [--apply-namespace-app-routes true/false] [--apply-namespace-as-suffix true/false ] 
  [--delete-services] [--delete-service-keys] [--delete-service-brokers] [--keep-files] 
  [--no-restart-subscribed-apps] [--do-not-fail-on-missing-permissions] [--abort-on-error] 
  [--strategy STRATEGY] [--skip-testing-phase] [--skip-idle-start] [--apps-start-timeout TIMEOUT] 
  [--apps-stage-timeout TIMEOUT] [--apps-upload-timeout TIMEOUT] [--apps-task-execution-timeout TIMEOUT]
  

• Deployment using a URL to the MTA archive

  You have the option to deploy or synchronize an MTA, the source of which is contained at a URL address.When you use this command, the request prompts the backend to download the archive and then dеploy it:

  Caution:

  This option is currently experimental.

  <write MTA archive URL to STDOUT> | cf deploy [-e EXT_DESCRIPTOR[,...]] 
  [-t TIMEOUT] [--version-rule VERSION_RULE] [-u MTA_CONTROLLER_URL] [--retries RETRIES] [--no-start] 
  [--namespace NAMESPACE] [--apply-namespace-app-names true/false] [--apply-namespace-service-names true/false] 
  [--apply-namespace-app-routes true/false] [--apply-namespace-as-suffix true/false ] [--delete-services] 
  [--delete-service-keys] [--delete-service-brokers] [--keep-files] [--no-restart-subscribed-apps] 
  [--do-not-fail-on-missing-permissions] [--abort-on-error] [--strategy STRATEGY] [--skip-testing-phase] 
  [--skip-idle-start] [--apps-start-timeout TIMEOUT] [--apps-stage-timeout TIMEOUT] 
  [--apps-upload-timeout TIMEOUT] [--apps-task-execution-timeout TIMEOUT]
  

  Caution:

  There is no possibility for you to check if there are running ongoing operations on the MTA that you want to deploy using a URL.

  Note:

  • The URL to the MTA archive must include the https://\ prefix.
  • You can use an locally present extension descriptor along with this deployment method.

• Deployment from your current directory

  You have the option to deploy the content of the directory you are currently in. The MultiApps CLI plugin packages the content in accordance with the deployment descriptor definition, so that the Cloud Deployment service can then upload and deploy the MTA.

  cf deploy [-e <EXT_DESCRIPTOR_1>[,<EXT_DESCRIPTOR_2>]] 
  [-u <URL>] [-t <TIMEOUT>] [-v <VERSION_RULE>]
  [--no-start] [--namespace]
  [--delete-services] [--delete-service-keys] [--delete-service-brokers] 
  [][--keep-files] [--no-restart-subscribed-apps] [--do-not-fail-on-missing-permissions] [--skip-idle-start]
  cf deploy ...[--retries <RETRIES>]
  

In additon to deployment, you can also interact with an active MTA deploy operation, for example, by performing an action:

cf deploy  [-i <OPERATION_ID>] [-a <ACTION>] 

Arguments

The Cloud Deployment service uses the content of the mtad.yaml descriptor, and based its contained info assembles an MTA archive in that directory before deploying it.

Command Arguments Overview

Argument	Description
<MTA_ARCHIVE>	The path to (and name of) the archive or the directory containing the Multitarget Application to deploy; the application archive must have the format (and file extension) mtar, for example, MTApp1.mtar. If the value of this argument is a directory, the checks if an mtad.yaml file exists in that directory, and based on it assembles an MTA archive before deploying it. If no argument exists, the current directory is used.
<DIRECTORY_PATH>	The Cloud Deployment service also accepts a path to a directory where an mtad.yaml is maintained with path elements, for example, cf deploy ./.
<--retries>	Retry the operation specified number of times in case a non-content error (default 3).

Options

Command Options Overview

Option	Description
-e <EXT_DESCRIPTOR_1>[,<EXT_DESCRIPTOR_2>]	Define one or more extensions to the deployment descriptors; multiple extension descriptors must be separated by commas.
-u <URL>	Specify the URL for the deployment-service end-point that is to be used for the deployment operation.
-t <TIMEOUT>	Specify the maximum amount of time (in seconds) that the service must wait for before starting the deployed application.
-v <VERSION_RULE>	Specify the rule to apply to determine how the application version number is used to trigger an application-update deployment operation, for example: “HIGHER”, “SAME_HIGHER”, or “ALL”.
-i <OPERATION_ID>	Specify the ID of the deploy operation that you want to perform an action on.
-a <ACTION>	Specify the action to perform on the deploy operation, for example, “abort”, “retry”, or “monitor”, or “resume”.
-f	Force deployment without requiring any confirmation about aborting any conflicting processes.
--no-start	Do not start application after deployment.
--apps-upload-timeout <TIMEOUT>	Defines how long, in seconds, you can upload your application binary before the MTA operation times out. See Application-Specific Timeouts . Note: This applies to all applications.
--apps-stage-timeout <TIMEOUT>	Defines how long, in seconds, your application can take during staging before the MTA operation times out. See Application-Specific Timeouts . Note: This applies to all applications.
--apps-start-timeout <TIMEOUT>	Defines how long, in seconds, your application can take to start before the MTA operation times out. See Application-Specific Timeouts . Note: This applies to all applications.
--apps-task-execution-timeout <TIMEOUT>	Defines how long, in seconds, your application can take to execute a task before the MTA operation times out. See Application-Specific Timeouts . Note: This applies to all applications.
--delete-services	Re-create changed services and delete discontinued services.
--delete-service-keys	Delete the existing service keys and apply the new ones.
--delete-service-brokers	Delete discontinued service brokers.
--keep-files	Keep the files used for deployment.
--no-restart-subscribed-apps	Do not restart subscribed applications that are updated during the deployment.
--do-not-fail-on-missing-permissions	Perform the deployment, even if required administrator permissions are missing for some operations (for example, the creation of service brokers).
--abort-on-error	If an operation fails, the corresponding process is automatically aborted and cannot be retried using the option -a retry. However, if you run a new operation for the same MTA, you will not receive an error message that there is an ongoing process for the MTA and ask you if you want to abort it.
-m <module name>	Deploy only the module with the specified name. Note: It can be used multiple times.
--all-modules	Deploy all modules. Note: Any -m options are ignored.
-r <resource name>	Deploy only the resource with the specified name Note: It can be used multiple times.
--all-resources	Deploy all resources. Note: Any -r options are ignored.
--strategy	Announce to the platform a special deployment approach, for example when performing a “blue-green” or an “incremental-blue-green” deployment. See Blue-Green Deployment Strategy and (Experimental) Incremental Blue-Green Deployment Strategy. Using this option, you will not be asked to manually confirm the deletion of the older version of the MTA applications. This means that the deployment process is performed without any interruptions and you are not prompted to confirm the switch of routes to the new version of the MTA applications.
--skip-testing-phase	When using the --strategy option for “blue-green” or “incremental-blue-green” deployment, you can choose to skip the testing phase and you will not be asked to manually confirm the deletion of the older version of the MTA applications. The deployment process is performed without any interruptions and you are not prompted to confirm the switch of routes to the new version of the MTA applications. Note: This option is equivalent to --no-confirm from “bg-deploy”.
--namespace Note: This option is currently experimental.	Namespace for the MTA. They are also applied to the application and service names. For more information, see (Experimental) Namespaces.
--apply-namespace-app-names true/false Note: This option is currently experimental.	Apply namespace to application names. If the namespace value is not provided in the CLI options, it is not applied. Note: This applies to all applications.
--apply-namespace-service-names true/false Note: This option is currently experimental.	Apply namespace to service names. If the namespace value is not provided in the CLI options, it is not applied. Note: This applies to all services.
--apply-namespace-app-routes true/false Note: This option is currently experimental.	Apply namespace to application routes. If the namespace value is not provided in the CLI options, it is not applied. Note: This applies to all application routes.
--apply-namespace-as-suffix true/false Note: This option is currently experimental.	Apply namespace as suffix. If the namespace value is not provided in the CLI options, it is not applied. Note: This applies to all applications, services, and application routes.
--skip-idle-start Note: This option is currently experimental.	When using the --strategy option for “blue-green”, you can choose to skip the starting of the newly deployed applications on idle routes. This means that the newly deployed applications will be mapped directly to live routes. Under the hood this option includes --skip-testing-phase.

Note:

• If any of the options -m, --all-modules, -r, --all-resource is used, only the specified modules and resources will be deployed. Otherwise, everything will be deployed by default.
• If the options for the module deploying ( -m, --all-modules) are used, the modules need to contain a path element on an MTA module level, which points to the content of the module. In case the module has some requires dependency section to a resource that needs a configuration file, then the requires section should have a path parameter, which points to the configuration file.
• If the options for the resource deploying (-r, --all-resource) are used, then any resources that have some configuration files need to contain a path parameter in their parameters section, which points to the configuration file.
• The path element or parameter value should be relative to the MTA directory.

An example of an MTA deployment descriptor, containing all variants of the path elements and parameters can be found at Defining Multitarget Application Deployment Descriptors for Cloud Foundry.

bg-deploy

Deploy a new Multitarget Application (MTA) using “blue-green” (zero-downtime) deployment.

Note:

You can also perform this deployment type using the deploy command by using the experimental --strategy blue-green flag. See above for details.

“Blue-green” deployment is a release technique that reduces application downtime and the resulting risk by running two identical target deployment environments called “blue” and “green”. Only one of the two target environments is “live” at any point in time and it is much easier to roll back to a previous version after a failed (or undesired) deployment.

Usage

Deploy a new Multitarget Application using “blue-green” deployment:

cf bg-deploy <MTA_ARCHIVE>  
[-e <EXT_DESCRIPTOR_1>[,<EXT_DESCRIPTOR_2>]] 
[-u <URL>] [-t <TIMEOUT>] [-v <VERSION_RULE>]
[--no-start] [--use-namespaces] [--no-namespaces-for-services]
[--delete-services] [--delete-service-keys] [--delete-service-brokers] 
[--keep-files] [--no-restart-subscribed-apps] [--no-confirm] [--do-not-fail-on-missing-permissions][--skip-idle-start]
cf deploy ...[--retries <RETRIES>]

Interact with an active MTA deploy operation, for example, by performing an action:

cf bg-deploy  [-i <OPERATION_ID>] [-a <ACTION>] 

Arguments

Command Arguments Overview

Argument	Description
<MTA_ARCHIVE> or <DIRECTORY_PATH>	The path to (and name of) the archive or the path to the directory containing the Multitarget Application to deploy. The application archive must have the format (and file extension) mtar, for example, MTApp1.mtar; the specified directory can be specified as a path (for example, myApp/ or . (current directory).
<--retries>	Retry the operation specified number of times in case a non-content error (default 3).

Options

Command Options Overview

Option	Description
-e <EXT_DESCRIPTOR_1>[,<EXT_DESCRIPTOR_2>]	Define one or more extensions to the deployment descriptors; multiple extension descriptors must be separated by commas.
-u <URL>	Specify the URL for the deployment-service end-point that is to be used for the deployment operation.
-t <TIMEOUT>	Specify the maximum amount of time (in seconds) that the service must wait for before starting the deployed application.
-v <VERSION_RULE>	Specify the rule to apply to determine how the application version number is used to trigger an application-update deployment operation, for example: “HIGHER”, “SAME_HIGHER”, or “ALL”.
-i <OPERATION_ID>	Specify the ID of the deploy operation that you want to perform an action on.
-a <ACTION>	Specify the action to perform on the deploy operation, for example, “abort”, “retry”, or “monitor”, or “resume”.
-f	Force deploy without requiring any confirmation for aborting any conflicting processes.
--no-start	Do not start application after deployment.
--use-namespaces	Use namespaces in application (and service) names during application deployment.
--no-namespaces-for-services	Do not use namespaces in service names.
--delete-services	Re-create changed services and delete discontinued services.
--delete-service-keys	Delete the existing service keys and apply the new ones.
--delete-service-brokers	Delete discontinued service brokers.
--keep-files	Keep the files used for deployment.
--no-restart-subscribed-apps	Do not restart subscribed applications that are updated during the deployment.
--no-confirm	Use this option to turn off the manual confirmation for deleting the older version of the MTA applications. Thus the deployment process is performed from start to finish uninterrupted, and you are not prompted to confirm the switch of routes to the new version of the MTA applications.
--do-not-fail-on-missing-permissions	Perform the deployment, even if required administrator permissions are missing for some operations (for example, the creation of service brokers).
--abort-on-error	If an operation fails, the corresponding process is automatically aborted and cannot be retried using the option -a retry.
-m <module name>. However, if you run a new operation for the same MTA, you will not receive an error message that there is an ongoing process for the MTA and ask you if you want to abort it.	Deploy only the module with the specified name. Note: It can be used multiple times.
--all-modules	Deploy all modules. Note: Any -m options are ignored.
-r <resource name>	Deploy only the resource with the specified name. Note: It can be used multiple times.
--all-resources	Deploy all resources. Note: Any -r options are ignored.
--skip-idle-start Note: This option is currently experimental.	You can choose to skip the starting of the newly deployed applications on idle routes. This means that the newly deployed applications will be mapped directly to live routes. Under the hood this option includes --no-confirm.

Note:

• If any of the options -m, --all-modules, -r, --all-resource is used, only the specified modules and resources will be deployed. Otherwise, everything will be deployed by default.
• If the options for the module deploying ( -m, --all-modules) are used, the modules need to contain a path element on an MTA module level, which points to the content of the module. In case the module has some requires dependency section to a resource that needs a configuration file, then the requires section should have a path parameter, which points to the configuration file.
• If the options for the resource deploying (-r, --all-resource) are used, then any resources that have some configuration files need to contain a path parameter in their parameters section, which points to the configuration file.
• The path element or parameter value should be relative to the MTA directory.

See the complete procedure in section Legacy Blue-Green Deployment.

An example of an MTA deployment descriptor, containing all variants of the path elements and parameters can be found at Defining Multitarget Application Deployment Descriptors for Cloud Foundry.

undeploy

Undeploy a Multitarget Application (MTA), or interact with an undeploy MTA operation.

Usage

Undeploy an MTA.

cf undeploy <MTA_ID>  
[-u <URL>] [-f] 
[--delete-services] [--delete-service-keys] [--delete-service-brokers] [--no-restart-subscribed-apps] 
[--do-not-fail-on-missing-permissions]
cf deploy ...[--retries <RETRIES>]

Interact with an undeploy MTA operation, for example, by performing an action.

cf undeploy [-i <UNDEPLOY_ID>] [-a <ACTION>]

Arguments

Command Arguments Overview

Argument	Description
<MTA_ID>	The ID of the MTA you want to undeploy
<--retries>	Retry the operation specified number of times in case a non-content error (default 3).

Options

Command Options Overview

Option	Description
-u <URL>	Specify the URL for the service end-point that is to be used for the undeployment operation.
-i <OPERATION_ID>	Specify the ID of the undeploy operation that you want to perform an action on.
-a <ACTION>	Specify the action to perform on the undeploy operation, for example, “abort”, “retry”, or “monitor”.
-f	Force completion of the undeploy operation without any system prompt or confirmation.
--delete-services	Delete any related services.
--delete-service-brokers	Delete discontinued service brokers.
--no-restart-subscribed-apps	Do not restart subscribed applications that are updated during the deployment.
--do-not-fail-on-missing-permissions	Perform the deployment, even if required administrator permissions are missing for some operations (for example, the creation of service brokers).
--abort-on-error	If an operation fails, the corresponding process is automatically aborted and cannot be retried using the option -a retry. However, if you run a new operation for the same MTA, you will not receive an error message that there is an ongoing process for the MTA and ask you if you want to abort it.
--delete-service-keys	Delete the existing service keys.

mta

Display information about a Multitarget Application (MTA). The information displayed includes the requested state, the number of instances, information about allocated memory and disk space, as well as details regarding the bound service (and service plan).

Usage

cf mta MTA_ID  
[-u <URL>]

Arguments

Command Arguments Overview

Argument	Description
<MTA_ID>	The ID of the MTA whose details you want to display

Options

Command Options Overview

Option	Description
-u <URL>	Specify the URL for the deployment-service end-point to use to obtain details of the selected MTA.

mtas

Display information about all available Multitarget Applications (MTA).

Usage

cf mtas [-u <URL>]

Options

Command Options Overview

Option	Description
-u <URL>	Specify the URL for the deployment-service endpoint to use to obtain details of the selected MTA.

mta-ops

Display information about all active operations for Multitarget Applications (MTA). The information includes the ID, type, status, the time the MTA-related operation started, as well as the name of the user that started the operation.

Usage

cf mta-ops [--mta <MTA>] [-u <URL>] [--last <NUM>] [--all]

Options

Command Options Overview

Option	Description
-u <URL>	Specify the URL for the deployment-service end-point to use to obtain details of the selected MTA operations.
--last <NUM>	List the last <NUM> active MTA operations.
--all	List all active MTA operations.
– mta <MTA>	Specify the MTA whose operations you want to list.

download-mta-op-logs

Download the log files for one or more operations concerning Multitarget Applications.

Usage

You have the following usage options:

cf download-mta-op-logs -i <OPERATION_ID> [-u ] [-d ]

-   ```
cf download-mta-op-logs --mta <MTA> [ --last <NUM>] [ -u <URL>] [ -d <DIRECTORY>]

Tip:

You can use the alias dmol in place of the download-mta-op-logs command.

Options

Command Options Overview

Option	Description
-u <URL>	Specify the URL for the deployment-service end-point to use to obtain details of the selected MTA operations.
-i <OPERATION_ID>	Specify the identity (ID) of the MTA operation whose logs you want to download.
-d <DIRECTORY>	Specify the path to the location where you want to save the downloaded MTA operation logs; by default, the location is ./mta-op-<OPERATION_ID>/.
--mta<MTA>	Specify the MTA whose logs you want to download. Note: This option is not compatible with the -i option.
--last<NUM>	Download the last <NUM> logs for the specified MTA.

purge-mta-config

Purge all configuration entries and subscriptions, which are no longer valid.

Usage

cf purge-mta-config   
[-u <URL>]

Invalid configuration entries are often produced when the application that is providing configuration entries is deleted by the user without using the deploy-service, for example, the cf delete command . In this case, the configuration remains in the deploy-service database even though the corresponding application is no longer available. This could lead to a failure during subsequent attempts to resolve the configuration entries.

Options

Command Options Overview

Option	Description
-u <URL>	The URL of the deploy service

Related Information

MultiApps CLI plugin

Cloud Foundry multitarget аpplication еxamples repository

Deploy an MTA archive referenced by a remote URL