Porter Manifest File Format

The manifest is the porter.yaml file used to build a bundle. You can use this json schema to validate a Porter manifest.

We have a Porter Visual Studio Code extension that provides autocomplete when editing a porter.yaml file.

Supported Versions

Below are schema versions for the Porter manifest, and the corresponding Porter version that supports it.

Schema Type Schema Version Porter Version
Bundle (none) v0.38.*
Bundle 1.0.0-alpha.1 v1.0.0-alpha.14+

Sometimes you may want to work with a different version of a resource than what is supported by Porter, especially when migrating from one version of Porter to another. The schema-check configuration setting allows you to change how Porter behaves when the schemaVersion of a resource doesn’t match Porter’s supported version.

schemaType: Bundle
schemaVersion: 1.0.0-alpha.1
name: myapp
version: 1.0.0
description: Install my great application
registry: localhost:5000
reference: localhost:5000/myapp:v1.0.0
dockerfile: template.Dockerfile

maintainers:
  - name: Qi Lu
  - email: sal@example.com
  - name: Frank
    url: https://example.com/frank

custom:
  app:
    version: 1.2.3
    commit: abc123

required:
  - docker:
      privileged: true

mixins:
  - exec
  - helm3:
      clientVersion: 3.1.2

credentials:
  - name: kubeconfig
    description: A kubeconfig with cluster admin role
    path: /root/.kube/config
  - name: token
    env: GITHUB_TOKEN
    applyTo:
      - release

parameters:
  - name: log-level
    description: Log level for MyApp
    type: integer
    env: MYAPP_LOG_LEVEL
    applyTo:
      - install
      - upgrade
  - name: connstr
    description: MyApp database connnection string
    type: string
    env: MYAPP_CONNECTION_STRING
    sensitive: true
    source:
      dependency: mysql
      output: admin-connstr
    applyTo:
      - install
      - status
  - name: release-name
    type: string
    env: RELEASE
    default: myapp

state:
  - name: tfstate
    description: Store terraform state with the bundle instead of a remote backend
    path: terraform/terraform.tfstate

dependencies:
  - name: mysql
    bundle:
      reference: getporter/mysql:v0.1.1
    parameters:
      database: myapp

outputs:
  - name: app-token
    description: Access token for MyApp
    type: file
    path: /cnab/app/myapp_token
    sensitive: true
    applyTo:
      - install
  - name: ip-address
    type: string

images:
  myapp:
    repository: example/myapp
    digest: sha256:568461508c8d220742add8abd226b33534d4269868df4b3178fae1cba3818a6e

install:
  - helm3:
      description: "Install MyApp"
      name: "{{ bundle.parameters.release }}"
      chart: ./charts/myapp
      replace: true
      set:
        image.repository: "{{ bundle.images.myapp.repository }}"
        image.digest: "{{ bundle.images.myapp.digest }}"

upgrade:
  - helm3:
      name: "{{ bundle.parameters.release }}"
      chart: ./charts/myapp
      set:
        image.repository: "{{ bundle.images.myapp.repository }}"
        image.digest: "{{ bundle.images.myapp.digest }}"

uninstall:
  - helm3:
      purge: true
      releases:
        - "{{ bundle.parameters.release }}"  

poke:
  - exec:
      command: ./poke-myapp.sh

customActions:
  status:
    description: See what's up in there
    modifies: false
    stateless: true

status:
  - exec:
      command: ./status.sh
Field Required Description
schemaType false The type of document. This isn’t used by Porter but is included when Porter outputs the file, so that editors can determine the resource type.
schemaVersion true The version of the Bundle schema used in this file.
name true The name of the bundle.
version true The version of the bundle, must adhere to semver v2.
The bundle tag defaults to the version with a v prefix, e.g. mybundle:v1.0.0. Use –tag or the reference field to override.
description false A description of the bundle.
registry true* The OCI registry to use when the bundle is published.
*Either registry or reference must be specified.
reference true* The full reference to use when the bundle is published to an OCI registry.
*Either registry or reference must be specified.
dockerfile false The relative path to a Dockerfile to use as a template during porter build.
maintainers false A list of maintainers for the bundle.
maintainers.name false Name of the maintainer.
maintainers.email false Email of the maintainer.
maintainers.url false Url of the maintainer.
custom false An object of custom bundle metadata.
required false A list of additional features required by the bundle.
required.docker false Indicate that the bundle requires a Docker host/daemon.
required.docker.privileged false Run the bundle in a privileged container.
mixins true A list of mixins used in the bundle. May include additional configuration settings depending on the mixin.
credentials false A list of credentials used by the bundle.
credentials.name true The name of the credential.
credentials.description false A description of the credential, how its used, and how to find it.
credentials.required false Indicates if the credential is required.
credentials.applyTo false A list of actions that apply to this item. When none are specified, all actions apply.
credentials.env true The environment variable name, such as MY_VALUE, into which the credential value is stored. Either env or path must be specified.
credentials.path true The path inside the bundle where the credential value is stored. Either env or path must be specified.
parameters false A list of parameters used by the bundle.
parameters.name true The name of the parameter.
parameters.description false A description of the parameter and how it is used.
parameters.default false The default value of the parameter. When no default is set, the parameter is required.
parameters.applyTo false A list of actions that apply to this item. When none are specified, all actions apply.
parameters.env true The environment variable name, such as MY_VALUE, into which the parameter value is stored. Either env or path must be specified.
parameters.path true The path inside the bundle where the parameter value is stored. Either env or path must be specified.
parameters.type true The parameter type. Allowed values are: string, number, integer, boolean, object, or file.
parameters.sensitive false Indicates whether this parameter’s value is sensitive and should not be logged.
parameters.source false Indicates that the parameter should get its value from an external source.
parameters.source.output true An output name. The parameter’s value is set to output’s last value.
parameters.source.dependency false The name of the dependency that generated the output. If not set, the output must be generated by the current bundle.
state false State variables that are generated by the bundle and injected on subsequent runs.
state.name true The name of this state variable
state.description false Description of how the variable is used by the bundle.
state.mixin false The name of the mixin that generates and manages this state variable.
state.path true The path inside of the bundle where the state variable data is stored.
outputs false A list of output values produced by the bundle.
outputs.name true The name of the output.
outputs.description false A description of the output and what it represents.
outputs.default false The default value of the output. When no default is set, the output is required.
outputs.applyTo false A list of actions that apply to this item. When none are specified, all actions apply.
outputs.path true The path inside the bundle where the output value is stored.
outputs.type true The output type. Allowed values are: string, number, integer, boolean, object, or file.
outputs.sensitive false Indicates whether this output’s value is sensitive and should not be logged.
images false A map of images referenced in the bundle. When the bundle is relocated, the referenced images are copied to the new bundle location.
images.KEY.description false A description of the image and how it is used.
images.KEY.repository true The repository portion of the image reference, i.e. docker.io/library/nginx
images.KEY.digest true The repository digest of the image, e.g. sha256:cafebabe…
dependencies false Other bundles that this bundle relies upon.
dependencies.requires true A list of bundles that should be executed with this bundle.
dependencies.requires.name true A name for the dependency, used to refer to the dependency using the template syntax bundle.dependencies.NAME.
dependencies.requires.reference true The full bundle reference for the dependency in the format REGISTRY/NAME:TAG.
dependencies.requires.parameters false A map of parameter names to their value.
customActions false A map of action names to a custom action definition.
customActions.NAME.description false A description of the action.
customActions.NAME.modifies false Specifies if the action will modify resources in any way.
customActions.NAME.stateless false Specifies that the action could be run before the bundle is installed and does not require credentials.

Next Steps