Parameters and Properties

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.

Note:

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.

Tip:

You can declare metadata for parameters and properties defined in the MTA deployment description; 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 modified overwritable: true.

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

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.

Parameters can be “Read-Only” (also known as “System”) or “Read-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:

Module-Specific Parameters
Resource-Specific Parameters
Module Hooks - Specific Parameters
Generic parameters (table below) that can have the following scopes:
- Top-level - can be defined on top level.
- All - can be consumed everywhere throughout the document.

Note:

Generic Parameters table contains parameters that might be used on top-level or on all levels. Other supported parameters are distributed in the dedicated pages, for example, module-specific parameters.

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.

Sample Code:

modules:
  - name: node-hello-world
    type: javascript.nodejs
    path: web/
    parameters:
       memory: 128M

Generic Parameters

Parameter	Scope	Read-Only (System)	Description	Default Value	Example
`authorization-url`	All	Yes	The authorization URL as specified in the cloud controller's `/v2/info` endpoint.	Generated as described in the description.	`https://login.cf.sap.hana.ondemand.com`
`controller-url`	All	Yes	The URL of the cloud controller	Generated as described in the description.	`https://api.cf.sap.hana.ondemand.com`
`default-domain`	All	Yes	The default domain (configured in the Cloud Foundry environment)	Generated as described in the description.	`accra6024` `cfapps.acme.com`
`deploy-url`	All	Yes	The deploy service URL for the Cloud Foundry environment	Generated as described in the description.	``
`generated-password`	All	Yes	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.	`IG@zGg#2g-cvMvsW`
`generated-user`	All	Yes	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.	`uYi$d41TzM1-Dm6f`
`keep-existing-routes`	Global	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 global level, under the `parameters` section of the descriptor, it indicates if the existing routes of all applications within that MTA should be kept. Note: The module-level variant of the parameter has priority over the global parameter. This parameter is typically used when users want to keep the routes they have mapped manually by using the `cf map-route` command. We discourage this approach, as manual operations could lead to inconsistent deployment results and difficult troubleshooting. We recommend you to define all routes in the deployment and/or extension descriptors, which allows for their automatic management.	`false`	`parameters: keep-existing-routes: true modules: - name: foo type: nodejs parameters: keep-existing-routes: false - name: bar type: nodejs - name: baz type: nodejs`
`org`	All	Yes	Name of the target organization	The current name of the target organization	`initial, trial`
`protocol`	All	Yes	The protocol used by the Cloud Foundry environment.	`http` or `https`	`http, https`
`space`	All	Yes	Name of the target organizational space	Generated as described in the description.	`initial, a007007`
`user`	All	Yes	Name of the current user	Generated as described in the description.
`xs-type`	All	Yes	The XS type, Cloud Foundry or XS advanced	CF	`CF, XSA`
`org-guid`	All	Yes	GUID (Globally Unique Identifier) of the target organization	N/A	`06564ad5-1b38-458d-8c85-a2e0bcd990a9`
`space-guid`	All	Yes	GUID (Globally Unique Identifier) of the target space	N/A	`06564ad5-1b38-458d-8c85-a2e0bcd990a9`
`mta-version`	All	Write	The version of the MTA	N/A	`1.0.0`
`mta-id`	All	Write	The ID of the MTA	N/A	`1.0.0`

These parameters can be used with the provides or requires dependencies:

Dependency-Specific Parameters

Parameter	Scope	Read-Only (System)	Description	Default Value	Example
`env-var-name`	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.	`env-var-name: SERVICE_KEY_CREDENTIALS`
`visibility`	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. `visibility: - org: ${org} space: "*"`	`visibility: - org: foo space: "" - org: bar space: "" - org: baz space: qux`

As an alternative, you can also externalize such configurations in a file. See Service Creation Parameters.

Properties

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.

Cross-References to Properties

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.

Restriction:

It is not possible to reference list configuration entries either from resources or “subscription” functionalities (deployment features that are available to subscriber applications).

Code Syntax:

Cross-References between Properties in the MTA Deployment Descriptor


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 backend can depend on the provided content.
The java module provides the url property, which can be referenced by other modules. Its value is generated using the default url provided to the application during deployment.
The java module property prop contains a parameter url, 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 provides section of a module.

Fully qualified references to properties

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:

Sample Code:

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

Dynamic parameters

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.

Note:

Currently, the feature is limited to resolving service GUID for the following resource types:

org.cloudfoundry.managed-service

org.cloudfoundry.user-provided-service

org.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.

Sample Code:

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}

Note:

In order to use this feature, it is necessary to specify ${service-guid} inside the properties section of the resource. Consumer of service GUID value must add respective resource name in the requires section and specify the processed-after parameter because the order of resource processing must be explicitly described.

Dynamic parameter as a cross-MTA dependency

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:

Sample Code:

_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}

The following example shows the dependency declaration in the deployment descriptor of the “consumer” MTA:

Sample Code:

_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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

parameters-and-properties-490c8f7.md

parameters-and-properties-490c8f7.md

Parameters and Properties

Note:

Tip:

Parameters

Note:

Sample Code:

Note:

Properties

Cross-References to Properties

Restriction:

Code Syntax:

Fully qualified references to properties

Sample Code:

Dynamic parameters

Note:

Sample Code:

Note:

Dynamic parameter as a cross-MTA dependency

Sample Code:

Sample Code:

Files

parameters-and-properties-490c8f7.md

Latest commit

History

parameters-and-properties-490c8f7.md

File metadata and controls

Parameters and Properties

Note:

Tip:

Parameters

Note:

Sample Code:

Note:

Properties

Cross-References to Properties

Restriction:

Code Syntax:

Fully qualified references to properties

Sample Code:

Dynamic parameters

Note:

Sample Code:

Note:

Dynamic parameter as a cross-MTA dependency

Sample Code:

Sample Code: