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
The installation variable contains data related to the execution of the bundle.
Variable | Description |
---|---|
installation.name | The name of the installation. |
installation.namespace | The namespace 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:
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).
Variable | Description |
---|---|
bundle.name | The bundle name |
bundle.description | The bundle description |
bundle.version | The bundle version defined in porter.yaml |
bundle.installerImage | The name of the bundle installer 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:
- 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.
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:
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 }
Dependecies v2 (experimental)
The second version of dependencies, called DependenciesV2, is available under the experimental flag.
You can enable the experimental flag by setting an environment variable as follows:
PORTER_EXPERIMENTAL=dependencies-v2
When DependenciesV2 is enabled, it is possible to use templating inside the dependency output section, like this:
dependencies:
requires:
- name: mysql
bundle:
reference: getporter/mysql:v0.1.3
outputs:
connection-string: "Server=mysql;Database=myDb;Uid=${bundle.parameters.uid};Pwd=${bundles.dependencies.mysql.mysql-password};"
If referencing an output from the same dependency, the format outputs.OUTPUT_NAME
can also be used.
dependencies:
requires:
- name: mysql
bundle:
reference: getporter/mysql:v0.1.3
outputs:
connection-string: "Server=mysql;Database=myDb;Uid=${bundle.parameters.uid};Pwd=${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 }