Skip to content

Deployment Descriptor

Jump to bottom
Vasko Bozhurski edited this page Aug 14, 2019 · 6 revisions

The MultiApps deployment descriptor is a YAML file that defines the relations between the different applications (modules), services (resources) and contains information needed for their deployment and configuration to the Cloud Foundry platform.

Editor Schema Support

Writing YAML descriptors in plain text is often hard so we have contributed a schema to the public Schema Store. This would provide you an almost out of the box support when writing MultiApps deployment descriptors in some of the more popular IDEs. The schema would provide you with auto-completion as well as suggestions and syntax checking.

What it offers?

  • Auto-completion for all MTA spec entities as well as the Supported Parameters by the MultiApps Controller.

  • Structure checks for mandatory elements as well overall structure of the descriptors.

  • Tooltips with description of each entity or parameter on all levels of the descriptor.

  • Default values as well as value validation for certain elements of the descriptor.

IntelliJ

The latest version of IntelliJ provides an out of the box support for Schema Store. This means that you won't have to do anything. Keep in mind that if you want support for extension descriptors you would need to set the *.mtaext in the IDE as YAML when first asked. If you set it to Plain Text you won't receive the IDE won't provide you the schema's functionality.

Visual Studio Code

For VSCode the functionality requires a bit more work to have. You would need to install the following extension from the marketplace: YAML which will provide you schema support. Make sure that inside the extension's configuration settings the option for downloading schemas from the schema store is enabled. Sadly it only works with files ending in .yml or .yaml so it won't work for extension descriptors.

MTA Information

  • ID - The ID of the MultiApps application. The MTA ID has to be unique in the space it is being deployed to, otherwise it would override the already deployed MultiApps application.

  • _schema-version - The MTA schema version that the MultiApps Controller should use to process the archive. Currently the highest supported version is '3.3'.

  • version - The version of your MultiApps application. For instance 1.0.0.

Modules

Modules represent the applications that are deployed and managed by the MultiApps Controller. Modules have the following fields:

  • name - The name or id of the module that is unique within the MTA. This name would also match the application name if not otherwise overriden by the app-name parameter.

  • type - The module-type of the module. Module-types are defined in the manifest.yml and provide predefined parameters and properties that are merged with the ones explicitly stated in the module.

  • hooks - Hooks allow execution of descriptor defined commands at specific moments of the module's lifecycle.

  • parameters - The parameters are used to detail deployment semantics to the MultiApps Controller such as memory, instances, host name and others. For more details check the Parameters.

  • properties - Module properties represent the user-defined ENV values that the application should have once deployed.

  • requires - This field holds a list of the required modules and resources that the module depends upon.

  • provides - This field holds a list of the provided dependencies that the module exposes.

Resources

Resources are external from the MTAR itself and can represent the services, service keys or configurations that are used by the applications (modules) within the MTA. They can be defined via the following fields:

  • name - The name or id of the resource that is unique within the MTA. This name would also match the service instance name if not overriden by a parameter of the resource.

  • type - The resource-type of the resource. Resource-types are defined in the manifest.yml and provide predefined parameters and properties that are merged with the ones explicitly stated in the resource. The type also defines the type and lifecycle of the service as such:

    • org.cloudfoundry.user-provided-service - This type describes the Cloud Foundry user provided services that map to external services that your application needs to consume.

    • org.cloudfoundry.managed-service - This type describes a Cloud Foundry service that will have it's lifecycle managed by the MultiApps Controller. If the service is not existing, it will be created. These types of services need to have their service name service and service plan service-plan defined.

    • org.cloudfoundry.existing-service - The existing service type differs from the managed service maps to a service that is already existing in the space. For this type, only the service instance name service-name needs to be provided.

    • org.cloudfoundry.existing-service-key - The consumption of existing service keys from applications is an alternative of service bindings. The application can use the service key credentials and consume the service.

    • configuration - Provides a way to have cross-MTA dependency to modules from another MTA that have their provided dependency with a field public: true.

  • parameters - The parameters are used to detail deployment semantics to the MultiApps Controller such as service name, service plan and service instance name. For more details check the Parameters.

  • properties - The properties of resources are mainly used to pass values to the modules that depend on them via references.

  • requires - This field holds a list of the required modules or resources that the resource depends upon.

  • provides - This field holds a list of the provided dependencies that the resource exposes.

  • optional - By default this field is set to false. If set to true, if a service is unavailable the deployment would continue rather than fail.

  • active - By default this field is set to false. If set to true, the resource will be skipped.

Example

This is a mtad.yml taken from the spring-music example application. It represents two applications, one java tomcat and one nodejs, that consume 2 services, one as managed and one as user provided external service.

_schema-version: 3.1
ID: cf.samples.spring.music
version: 1.0.0

modules:
  - name: spring-music-web
    type: java.tomcat
    requires:
      - name: news-provider
        properties:
          NEWS_URL: ~{url} # a reference to a property value, defined within the descriptor 
      - name: spring-music-db
      - name: spring-music-news-external
    parameters:
      buildpack: java_buildpack
    properties:
      POPULATE_ALBUM_REPOSITORY: true

  - name: spring-music-news
    type: javascript.nodejs
    provides:
      - name: news-provider
        properties:
          url: ${default-url}/news # a placeholder which must be resolved by the ALM service

resources:
  - name: spring-music-db
    type: org.cloudfoundry.managed-service
    parameters:
      service: postgresql # this is an example service name
      service-plan: v9.6 # this is an example service plan
  - name: spring-music-news-external
    type: org.cloudfoundry.user-provided-service
    parameters:
      config:
        url: http://some.domain.com/example/ # example value
Clone this wiki locally