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

  • version - the version of the preview.yaml file reference to use.
  • resources - a list of resources to create.
    • name - the unique ID of the resource.
    • driver - the name of the driver to use for the resource.
    • depends_on - the resources that the target resources depends on.
    • source - the source configuration, specifying the application/addon to use.
    • target - the target configuration, specifying the specifics of the project, cluster, etc., the application/addon should be deployed to.
    • config - the build and runtime configuration for the addon or application.

​
version

The version of the preview.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>.driver

The name of the driver the resource should use. For more about drivers, see the Drivers section of the documentation.

​
<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>.target

The target specifies the specifics of the project, cluster, etc., the application/addon should be deployed to. More specifically, it contains the following fields:

  • project [Integer, optional] - the Porter project ID to deploy the resource to. This is resolved in the following manner:
    • Checks for the PORTER_PROJECT environment variable and uses it if it is set to a non-zero value.
    • Next, checks for the value of target.project in the preview.yaml file and uses it if it is set to a non-zero value.
    • Lastly, defaults back to the CLI configuration value for the project, set by using the porter config set-project command.
  • cluster [Integer, optional] - the Porter cluster ID in the project to deploy the resource to. This is resolved in the following manner:
    • Checks for the PORTER_CLUSTER environment variable and uses it if it is set to a non-zero value.
    • Next, checks for the value of target.cluster in the preview.yaml file and uses it if it is set to a non-zero value.
    • Lastly, defaults back to the CLI configuration value for the cluster, set by using the porter config set-cluster command.
  • namespace [String, optional] - the namespace in the cluster to deploy the resource to. This is resolved in the following manner:
    • Checks for the PORTER_NAMESPACE environment variable and uses it if it is set to a non-empty string.
    • Next, checks for the value of target.namespace in the preview.yaml file and uses it if it is set to a non-empty string.
    • Lastly, uses the default namespace if the above steps do not resolve to a non-empty string value.

Note: In some cases, the target section can also contain the app_name field to denote the Porter release name.

For example, to deploy a resource to a specific project, cluster, and namespace:

---
resources:
  - name: "web-example"
    target:
      project: 1
      cluster: 1
      namespace: "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
    • 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 }"
Setupdeploy (default)