This section contains information about the parameters and properties of a multitarget application (MTA).
The values of parameters and properties can be specified at design time, in the MTA development description (mta.yaml) or in the MTA deployment descriptor (mtad.yaml). In some cases, it is better to declare certain values depending on the deployment, for example, in an extension descriptor file (myDeployExtension.mtaext).
The values of parameters and properties might be literals. This way, the result of each deployment will be the same every time. However, by using the placeholders described below, the values might also be set as substitution variables and therefore each deployment might end in a different result depending on the environment or other configurations.
Regardless of the defined value - literal or substitution variable, in most cases the end value for each parameter or property is definitive and well-known before the deployment. This is because the substitution variable values represent a certain template and template resolving is done in the beginning of the MTA deployment.
The module level parameter ${default-host} follows the template ${org}-${space}-<module_name>. For example, when it is used in a module my-module and the deployment is done within org my-org, space my-space, the end value of ${default-host} will be my-org-my-space-my-module.
However, in some cases the parameter or property value is dynamic and cannot be predicted before the deployment. In these cases, the substitution variable is dynamic and is done in a later phase of the MTA deployment.
If you want to learn more about dynamically resolved parameters see the Dynamic parameters section below.
The values of properties and parameters are used during the deployment or at runtime of the MTA.
Both parameters and properties may have literal values, such as strings, integers, etc. This also applies to deeply nested structured values, such as arrays or maps.
- You can declare metadata for parameters and properties defined in the MTA deployment descriptor. The mapping is based on the parameter or property keys. For example, you can specify if a parameter is required (
optional: false) or can be modifiedoverwritable: true. For more information, see Metadata for Properties and Parameters.- Descriptors can contain so-called placeholders (also known as substitution variables), which can be used as sub-strings within property and parameter values. Placeholder names are enclosed by the dollar sign (
$) and curly brackets ({}). For example:${host}and${domain}. For each parameter “P”, there is a corresponding placeholder${P}. The value of <P> can be defined either by a descriptor used for deployment, or by the deploy service itself. Placeholders can also be used without any corresponding parameters; in this scenario, their value cannot be overridden in a descriptor. Such placeholders are read-only.
Parameters are reserved variables that affect the behavior of the MTA-aware tools, such as the Cloud MTA Build Tool (MBT) or SAP Cloud Deployment service.
Parameters might be used on various levels in the MTA descriptor - top-level, module level, resource level, and dependency level. Based on the parameter applicability it might be used in combination in several places, for example, both on resource and module levels.
The example below shows the parameter `
memory` on a module level which defines the amount of memory used by the Cloud Foundry application represented by the module `node-hello-world` during application runtime.modules: - name: node-hello-world type: javascript.nodejs path: web/ parameters: memory: 128M
Parameters can be “Read-Only” (also known as “System”) or “Write” (default value can be overwritten). All parameter values can be referenced as part of other property or parameter value strings. The value of a “Read-Only” parameter cannot be changed in descriptors. Only its value can be referenced using the placeholder notation. To reference a parameter value, use the placeholder notation ${<parameter>}, for example ${org}.
SAP Cloud Deployment service supports a list of parameters and their (default) values:
-
Top-Level Parameters (see table below) - Top-level parameters are generally applicable parameters that cover various scenarios and can be used in different parts of the MTA descriptors. They can be grouped into to categories - "Read-Only" and "Write":
-
- Top-level "Write" parameters are designed to impact the behavior of the whole MTA deployment or many parts of it. It is wise to use them in order to avoid duplication. Their values can be defined and controlled by the customer. These parameters can be referenced throughout the whole document.
-
Top-level "Read-Only" parameters are commonly used parameters that can only be referenced in different parts of the MTA descriptors.
-
Top-Level Parameters
|
Parameter |
Scope |
Read-Only / Write |
Description |
Default Value |
Example |
|---|---|---|---|---|---|
|
Top-Level |
Write |
Applies namespace to application names (app-names), service names (service-names), application routes (app-routes) as suffix or prefix (as-suffix). If the namespace value is not provided in the CLI options, it is not applied. See Fine-Grained Configuration.
|
true |
|
|
|
Top-Level |
Write |
Defines how long, in seconds, your application can take during staging before the MTA operation times out. See Application-Specific Timeouts .
|
1h |
|
|
|
Top-Level |
Write |
Defines how long, in seconds, your application can take to start before the MTA operation times out. See Application-Specific Timeouts .
|
1h |
|
|
|
Top-Level |
Write |
Defines how long, in seconds, your application can take to execute a task before the MTA operation times out. See Application-Specific Timeouts .
|
12h |
|
|
|
Top-Level |
Write |
Defines how long, in seconds, you can upload your application binary before the MTA operation times out. See Application-Specific Timeouts .
|
1h |
|
|
|
Top-Level |
Read-Only |
The authorization URL as specified in the cloud controller's |
Generated as described in the description. |
|
|
|
Top-Level |
Write |
Ensures that during the final phase of a blue-green deployment, idle applications are stopped and restarted in a dependency-aware order based on the dependencies defined in the
|
false |
|
|
|
Top-Level |
Read-Only |
The URL of the cloud controller |
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
The default domain of the target organization (configured in the Cloud Foundry environment). The value is coming from CF API endpoint Get default domain, and normally, it depends on the shared domains in the current organization. |
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
The domain of the current region. For more information, refer to the Domain column in Regions and API Endpoints Available for the Cloud Foundry Environment. When a region has multiple CF API endpoints, it will point to the domain of the respective endpoint used for the deployment.
|
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
The primary domain of a region. For more information, refer to the Domain column in Regions and API Endpoints Available for the Cloud Foundry Environment. When a region has multiple CF API endpoints, it will point to the primary domain (the first one).
|
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
The deploy service URL for the Cloud Foundry environment |
Generated as described in the description. |
`` |
|
|
Top-Level |
Write |
Defines if parallel deployment of modules is enabled. When enabled, modules without explicitly set |
no |
|
|
|
Top-Level |
Read-Only |
Randomly generated string value that is composed of 16 characters that may contain upper and lower case letters, digits and special characters (_, -, @, $, &, #, *). |
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
A generated user id that is composed of 16 characters that may contain upper and lower case letters, digits and special characters (_, -, @, $, &, #, *). |
Generated as described in the description. |
|
|
|
Top-Level |
Write |
When specified on module level, it indicates if the existing routes of the module's corresponding application should be kept even if they are not defined within the deployment and/or extension descriptors. When specified on top level, under the
|
|
|
|
|
Top-Level |
Read-Only |
Name of the target organization |
The current name of the target organization |
|
|
|
Top-Level |
Read-Only |
The protocol used by the Cloud Foundry environment. |
|
|
|
|
Top-Level |
Read-Only |
Name of the target organizational space |
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
Name of the current user |
Generated as described in the description. |
|
|
|
Top-Level |
Read-Only |
The XS type, Cloud Foundry or XS advanced |
CF |
|
|
|
Top-Level |
Read-Only |
GUID (Globally Unique Identifier) of the target organization |
N/A |
|
|
|
Top-Level |
Read-Only |
GUID (Globally Unique Identifier) of the target space |
N/A |
|
|
|
Top-Level |
Write |
The version of the MTA |
N/A |
|
|
|
Top-Level |
Write |
The ID of the MTA |
N/A |
|
These parameters can be used with the provides or requires dependencies:
Dependency-Specific Parameters
|
Parameter |
Scope |
Read-Only / Write |
Description |
Default Value |
Example |
|---|---|---|---|---|---|
|
|
Module-Required Dependency |
Write |
Provide a binding name for the association between an application and a service instance |
|
|
|
|
Module-Required Dependency |
Write |
This parameter defines the target for the content deployment. It is usually a service instance or a service key toward the content backend that processes the content. The parameter is valid only for modules with direct content deployment:
For more information, see Deploying Content with Generic Application Content Deployment. |
false |
|
|
|
Module-Required Dependency |
Write |
If this parameter is set to true, the service keys used during the content deployment are deleted once the deployment is completed. The parameter is valid only for modules with direct content deployment:
|
false |
|
|
|
Module-Required Dependency |
Write |
Used when consuming an existing service key. Specifies the name of the environment variable that will contain the service key's credentials. See Consumption of existing service keys for more information. |
The name of the service key. |
|
|
|
Module-Provided Dependency |
Write |
Specifies the organizations and spaces in which public provided dependencies are visible. See Visibility of cross-MTA configuration for more information. |
In all spaces of the current organization. |
|
|
|
Module-Provided Dependency |
Write |
Valid for blue-green deployment. Specify this parameter if you want to provide the routes specified in the descriptor. |
false |
|
As an alternative, you can also externalize such configurations in a file. See Service Instance Parameters.
MTA properties are Cloud Foundry application environment variables that are used during application runtime. When an MTA property is set, the SAP Cloud Deployment service injects its key as the environment variable key and its value as the variable value in the application, represented by the corresponding MTA module.
MTA properties can be declared in different levels - module level, resource level, and dependency level.
To enable resource properties to resolve values from a property in another resource or module, a resource must declare a dependency. However, these “requires” declarations do not affect the order of the application deployment.
It is not possible to reference list configuration entries either from resources or “subscription” functionalities (deployment features that are available to subscriber applications).
Cross-References between Properties in the MTA Deployment Descriptor in a YAML file
modules: - name: java ... provides: - name: backend properties: url: ${default-url}/foo resources: - name: example type: example-type properties: example-prop: my-example-prop - name: uaa type: uaa-type requires: - name: example - name: backend properties: prop: ~{url} parameters: param: ~{url} properties: pro1: ~{example/example-prop} parameters: config: app-router-url: ~{backend/url} example-prop: ~{example/example-prop}
Note the following about the example above:
- The application name
backendcan depend on the provided content. - The
javamodule provides theurlproperty, which can be referenced by other modules. Its value is generated using the defaulturlprovided to the application during deployment. - The
javamodule propertypropcontains a parameterurl, which results in an environment variable <prop> containing the referenced value. - References to other properties can also be used for parameter values, for example in values contained in the
providessection of a module.
The SAP Cloud Deployment service supports the extension of the standard syntax for references in module properties. This extension enables you to specify the name of the requires section inside the property reference. You can use this syntax extension to declare implicit groups, as illustrated in the following example:
Syntax Extension: Alternative Grouping of MTA Properties
modules: - name: pricing-ui type: javascript.nodejs properties: API: # equivalent to group, but defined in the module properties - key: internal1 protocol: ~{price_opt/protocol} #reference to value of protocol defined in price_opt of module pricing-backend - key: external url: ~{competitor_data/url} # reference to string value of property 'url' in required resource 'competitor_data' api_keys: ~{competitor_data/creds} # reference to list value of property 'creds' in 'competitor_data' requires: - name: competitor_data - name: price_opt - name: pricing-backend type: java.tomcat provides: - name: price_opt properties: protocol: http ... resources: - name: competitor_data properties: url: "https://marketwatch.acme.com/" creds: app_key: 25892e17-80f6 secret_key: cd171f7c-560d
In some cases, it is required to use a value that is unknown before deployment. For example, such entity could be the GUID of another service instance. The GUID of a newly created service instance is not known before the creation of said service but it might be consumed during the MTA deployment.
The feature enables an existing Cloud Foundry entity parameter value to be used inside an MTA descriptor.
Currently, the feature is limited to resolving service GUID for the following resource types:
org.cloudfoundry.managed-serviceorg.cloudfoundry.user-provided-serviceorg.cloudfoundry.existing-service
Resolved parameters can only be referenced from other resources or from a cross-MTA dependency. If a dynamic parameter is referenced from other places, like modules, the reference won’t be resolved.
MTA Deployment Descriptor (
mtad.yaml)_schema-version: 3 ID: sample-dynamic-service-guid version: 1.0.0 modules: - name: sample-app type: staticfile path: content.zip requires: - name: test-service - name: hana-service resources: - name: test-service type: org.cloudfoundry.user-provided-service parameters: config: service-guid-of-db: ~{hana-service/my-db-service-guid} requires: - name: hana-service processed-after: [hana-service] - name: hana-service type: org.cloudfoundry.managed-service parameters: service: hana service-plan: schema properties: my-db-service-guid: ${service-guid}
In order to use this feature, it is necessary to specify
${service-guid}inside thepropertiessection of the resource. Consumer of service GUID value must add respective resource name in therequiressection and specify theprocessed-afterparameter because the order of resource processing must be explicitly described.
Resolved parameters can also be referenced from a cross-MTA dependency, allowing the service instance to be referenced from another MTA.
The following example shows the dependency declaration referencing a dynamic parameter in the deployment descriptor of the “provider” MTA:
_schema-version: 3 ID: dynamic-service-guid-provider version: 1.0.0 modules: - name: app-provider type: staticfile path: appBits.zip provides: - name: db-guid public: true parameters: visibility: - org: ${org} space: ${space} properties: db-instanceid: ~{hana-service/my-db-service-guid} requires: - name: hana-service resources: - name: hana-service type: org.cloudfoundry.managed-service parameters: service: hana service-plan: schema properties: my-db-service-guid: ${service-guid}
The following example shows the dependency declaration in the deployment descriptor of the “consumer” MTA:
_schema-version: 3 ID: dynamic-service-guid-consumer version: 1.0.0 modules: - name: app-consumer type: staticfile path: content.zip requires: - name: db-config properties: reference_instance: ~{db-instanceid} resources: - name: db-config type: configuration parameters: provider-id: "dynamic-service-guid-provider:db-guid" version: ">=1.0.0" target: org: ${org} space: ${space}
For more information about cross-MTA configurations see Cross-MTA Dependencies.