Templates

Porter supports templates in the action steps of porter.yaml, and uses the mustache template language. Templates are surrounded by the double curly brace delimiters, {{ template here }} and must be double-quoted when the entire value is a template. Below is an example demonstrating when double-quotes are necessary:

install:
  - exec:
      description: "Use some templates"
      command: ./helpers/{{ parameters.scriptName }}.sh
      arguments:
        - "{{ installation.name }}"
  - helm:
      description: "Install Java App"
      name: "{{ bundle.parameters.cool-app}}"
      chart: bitnami/wordpress
      version: "9.9.3"
      replace: true
      set:
        jdbc_url: jdbc:mysql://{{ bundle.outputs.mysql_host }}:{{ bundle.outputs.mysql_port }}/{{ bundle.parameters.database_name }}

Variables

Variables are grouped by the source of its data:

installation

The installation variable contains data related to the execution of the bundle.

Variable Description
installation.name The name of the installation.

In the example below, we install a helm chart and set the release name to the installation name of the bundle:

install:
  helm:
    description: Install myapp
    name: "{{ installation.name }}"
    chart: charts/myapp

bundle

The bundle variable contains data that was declared in the bundle definition (porter.yaml).

Variable Description
bundle.name The bundle name
bundle.description The bundle description
bundle.version The bundle version defined in porter.yaml
bundle.invocationImage (DEPRECATED) The name of the invocation image

custom metadata

The bundle.custom variable contains data that was declared in the bundle’s custom metadata section. Nested data can be accessed via bundle.custom.KEY.SUBKEY variable.

Here is an example porter.yaml that defines custom metadata and uses it in an action.

custom:
  chart:
    name: "mychart"
    version: "0.2.0"

install:
  - helm:
      description: "Install my chart"
      name: "{{ installation.name }}"
      chart: "{{ bundle.custom.chart.name }}"
      version: "{{ bundle.custom.chart.version }}"
      namespace: "myNamespace"

parameters

The bundle.parameters variable contains the values of parameters passed into the bundle.

Here is an example porter.yaml that defines a parameter and uses it in an action:

parameters:
  - name: namespace
    type: string
    env: RELEASE_NAMESPACE

install:
  - helm:
      description: "Install my chart"
      name: "myRelease"
      chart: "myChart"
      version: "1.2.3"
      namespace: "{{ bundle.parameters.namespace }}"

credentials

The bundle.credentials variable contains the values of credentials passed into the bundle.

Here is an example porter.yaml that defines a credential and uses it in an action:

parameters:
  - name: database-password
    type: string
    env: MYSQL_PASSWORD

install:
  - helm:
      description: "Install my chart"
      name: "myRelease"
      chart: "myChart"
      version: "1.2.3"
      namespace: "myNamespace"
      set:
        mysql-password: "{{ bundle.credentials.database-password }}"

outputs

The bundle.outputs variable contains the values of outputs generated by the bundle.

Here is an example porter.yaml that generates an output during a step and uses it in the next step:

install:
  - exec:
      description: "Generate username"
      command: ./helpers.sh
      arguments:
        - generateUsername
      outputs:
        - name: username
          regex: "(.*)" # Capture all of stdout
  - helm:
      description: "Install my chart"
      name: "myRelease"
      chart: "myChart"
      version: "1.2.3"
      namespace: "myNamespace"
      set:
        wordpress-username: "{{ bundle.outputs.username }}"

dependencies

The bundle.dependencies variable contains metadata for the bundle’s dependencies.

Variable Description
bundle.dependencies.NAME.name The bundle name of the dependency.
bundle.dependencies.NAME.description The bundle description of the dependency.
bundle.dependencies.NAME.version The bundle version of the dependency. This is a semver v2 value, and will not have a leading v prefix.

Outputs are also available, and the format for the dependency outputs variable is bundle.dependencies.NAME.outputs.OUTPUT.

Here is an example porter.yaml that has a dependency and uses an output generated by that dependency in an action:

dependencies:
  mysql:
    reference: getporter/mysql:v0.1.3

install:
  - helm:
      description: "Install my chart"
      name: "myRelease"
      chart: "myChart"
      version: "1.2.3"
      namespace: "myNamespace"
      set:
        database-password: "{{ bundle.dependencies.mysql.outputs.mysql-password }}"

images

The bundle.images variable contains metadata about referenced images in the bundle.

Here is an example porter.yaml that declares a referenced image. This enables relocating any referenced images when the bundle is published to a different registry. The bundle uses the bundle.images variable to tell Helm where to find the image. In this example, the Helm chart must have already exposed the image as a variable.

images:
  mysql:
      description: "A mysql server"
      imageType: "docker"
      repository: "getporter/mysql"
      digest: "sha256:85b1a9b4b60a4cf73a23517dad677e64edf467107fa7d58fce9c50e6a3e4c914"

install:
  - helm:
      description: "Install my chart"
      name: "mysqlServer"
      chart: "mysql"
      version: "1.2.3"
      namespace: "myNameespace"
      set:
        image: "{{bundle.images.mysql.repository}}@{{bundle.images.mysql.digest}}"

env

The env variable contains environment variables. The environment variable name is case sensitive.

install:
  - exec:
      description: "Access environment variables"
      command: ./helpers/login.sh
      arguments:
        - "{{ env.CNAB_REVISION }}"