Templates

Porter supports templates in the action steps of porter.yaml and can perform variable substitution. Templates are surrounded by a dollar sign curly brace delimiter, ${ template here }.

Starting in Porter v1.0.0-beta.2, templating does not require surrounding quotes and can now substitute in non-string variables, such as booleans and numbers.

Variables

Variables are grouped by the source of its data:

• installation
• bundle
  • bundle.custom
  • bundle.parameters
  • bundle.credentials
  • bundle.outputs
  • bundle.dependencies
  • bundle.images
• env

installation

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

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

install:
  helm3:
    description: Install myapp
    name: ${ installation.name }
    chart: charts/myapp

In the next example, we install some kubernetes resources using the namespace of the bundle:

install:
  kubernetes:
    description: Install myapp
    namespace: ${ installation.namespace }
    manifests:
      - manifests

bundle

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

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:
  - helm3:
      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:
  - helm3:
      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:
  - helm3:
      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
  - helm3:
      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.

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:
  requires:
    - name: mysql
      bundle:
        reference: getporter/mysql:v0.1.3

install:
  - helm3:
      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:
  - helm3:
      description: "Install my chart"
      name: "mysqlServer"
      chart: "mysql"
      version: "1.2.3"
      namespace: "myNameespace"
      set:
        image: ${bundle.images.mysql.repository}@${bundle.images.mysql.digest}

When an image tag is provided instead of a digest, Porter gets the latest image digest for the specified tag and then update the bundle to reference the image by digest instead of the provided tag. This helps to ensure deterministic and repeatable bundle execution.

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 }