Dependencies

In the Porter manifest you can define a dependency on another bundle. The dependent bundle is executed before the bundle is installed, updated, or a custom action is invoked. The dependent bundle is uninstalled after the root bundle is uninstalled.

Dependencies are an extension of the CNAB Spec. The Dependency specification is still evolving and we are using Porter to act as an initial implementation. So other CNAB tools may not support dependencies initially.

Here is a full example of a Porter manifest that uses dependencies.

Define a dependency

In the manifest, add entries for each dependency of your bundle. The name field takes a short name for the dependent bundle that you will use to reference the dependent bundle elsewhere in the bundle. For example you can reference the dependent bundle’s outputs via {{ bundle.dependencies.NAME.outputs }}. The tag field takes the bundle tag of the dependency. Both name and tag are required fields.

dependencies:
  - name: mysql
    tag: getporter/mysql:v0.1.3

Ordering of dependencies

If more than one dependency is declared, they will be installed in the order they are listed. For example, if both the mysql and nginx bundles are required, but the mysql bundle should be installed first, you would list them as such:

dependencies:
  - name: mysql
    tag: getporter/mysql:v0.1.3
  - name: nginx
    tag: my/nginx-bundle:v0.1.0

Defaulting Parameters

Parameters defined in a dependent bundle can be defaulted from the root bundle. In the example below, the mysql bundle defines database_name and mysql_user parameters, and the root bundle (Wordpress) has chosen to default those parameters to specific values, so that the user isn’t required to provide values for those parameter.

dependencies:
  - name: mysql
    tag: getporter/mysql:v0.1.3
    parameters:
      database_name: wordpress
      mysql_user: wordpress

Specifying parameters

Command-line

You can specify parameters for a dependent bundle on the command-line using the following syntax

--param DEPENDENCY#PARAMETER=VALUE

For example, to override the default parameter database_name when installing the wordpress bundle the comand would be

$ porter install --tag getporter/mysql:v0.1.3 --param mysql#database_name=mywordpress

• DEPENDENCY: The dependency name used in the dependencies section of the porter manifest. From the example above, the name is “mysql”.
• PARAMETER: The name of the parameter.
• VALUE: The parameter value.

Parameter Set

The same syntax shown above can be used to specify dependency parameters in a Parameter Set file.

Here, the name field should be set to the DEPENDENCY#PARAMETER value, or mysql#database-name from above.

{
  "name": "wordpress",
  "parameters": [
    {
      "name": "mysql#database-name",
      "source": {
        "value": "mywordpress"
      }
    }
  ]
}

Parameter Precedence

A parameter for a dependency can be set in a few places, here is the order of precedence:

1. Parameters set directly on the command-line via --param
2. Parameters set in a Parameter Set file via --parameter-set
3. Parameters set using a dependency default, for example ```yaml dependencies:
   • name: mysql tag: getporter/mysql:v0.1.3 parameters: database_name: wordpress ```
4. Parameter defaults defined in a bundle, for example ```yaml parameters:
   • name: database_name type: string default: mydb ```

Dependency Graph

At this time Porter only supports direct dependencies. Dependencies of dependencies, a.k.a. transitive dependencies, are ignored. See Design: Dependency Graph Resolution for our backlog item tracking this feature. We do plan to support it!