Skip to main content

Porter YAML Reference

This document contains a full reference file for porter.yaml. Each porter.yaml file has the following high-level structure:

  • version - the version of the porter.yaml file reference to use.
  • resources - a list of resources to create.
    • name - the name of the resource.
    • depends_on - the resources that the target resources depends on.
    • source - the source configuration, specifying the application/addon to use.
    • config - the build and runtime configuration for the addon or application.

version

The version of the porter.yaml file reference to use. Currently, only v1 is supported:

version: v1

resources

A list of resources to create. For example:

---
resources:
- name: "resource-1"
source:
name: "web"
- name: "resource-2"
depends_on:
- "resource-1"
source:
name: "web"

<resource>.name

The name of the resource to create.

<resource>.depends_on

A list of resources that the target resource depends on.

---
resources:
- name: "resource-1"
source:
name: "web"
- name: "resource-2"
depends_on:
- "resource-1"

<resource>.source

The source specifies the application/addon to deploy for this resource. More specifically, it uniquely identifies a Helm chart. It contains the following fields:

  • name [String, required] - the name of the template to use. Since the default source repo is https://charts.getporter.dev, the names web, worker, and job work by default.
  • repo [String, optional] - the Helm repository URL to use. Currently supported are https://charts.getporter.dev and https://chart-addons.getporter.dev.
  • version [String, optional] - the semver version of the chart to use. If no version is specified, the latest version is used.

For example, to deploy a worker application:

---
resources:
- name: "web-example"
source:
name: "worker" # this could also be "web" or "job"

To deploy postgresql, a supported addon:

---
resources:
- name: "postgres"
source:
name: "postgresql"
repo: "https://chart-addons.getporter.dev"

<resource>.config

The config block specifies build and runtime configuration for the application or addon.

Application Config

If the resource is a web, worker, or job application, the config block expects the following fields:

  • build [required] - the build configuration to use.
    • method [docker, pack, or registry] - the build/deploy method to use: the Docker daemon, cloud-native buildpacks or deployment from a Docker registry.
    • dockerfile [String, optional] - if the build method is docker, the path to the Dockerfile. Defaults to ./Dockerfile.
    • builder [String, optional] - if the build method is pack, the builder to use. Leaving this blank will default to paketobuildpacks/builder:full. Other well-supported options are heroku/buildpacks:20 and heroku/buildpacks:18.
    • buildpacks [String, optional] - if the build method is pack, the buildpacks to use. Leaving this empty will default to the buildpacks supported by paketo and heroku, depending on the builder.
    • context [String, optional] - if the build method is docker or pack, the path to the application directory. Defaults to the current (root) directory.
    • image [String, required if method=registry] - the image repo URL to deploy from, if the build method is registry.
  • values [required] - the runtime configuration to use.

If the resource is an addon, the config block corresponds directly to the runtime configuration.

Runtime Configuration

The options for the runtime configuration (config.values for applications, config for addons) corresponds to the default Helm values for the application. If you have experience with Kubernetes/Helm, you can also view all possible configuration options in the values.yaml files of the respective applications: web, worker, and job. If you don't have this experience, please see the examples to view common configuration options.

Variable References

It is possible to reference output values from another resource to set configuration for the current resource. The syntax to reference dependent variables is as follows:

"{ .<resource_name>.<jsonpath> }"

The <jsonpath> section follows JSONPath syntax. Most of the time, this will simply be a set of nested fields. For example, the postgresql addon outputs a fields postgresqlPassword and postgresqlUsername, so a resource named postgres can be referenced via:

POSTGRES_USERNAME: "{ .postgres.postgresqlUsername }"
POSTGRES_PASSWORD: "{ .postgres.postgresqlPassword }"