porter.yaml reference

This is the complete reference for all fields that can be set in a porter.yaml file.

Top-Level Fields

Field	Type	Required	Description
`version`	string	Yes	Must be `v2`
`name`	string	Conditional	App name. Required unless `PORTER_APP_NAME` env var is set
`build`	object	Conditional	Build configuration. Cannot be used with `image`
`image`	object	Conditional	Pre-built image configuration. Cannot be used with `build`
`services`	array	Yes	List of service definitions
`env`	object	No	Environment variables
`envGroups`	string[]	No	Names of environment groups to attach
`predeploy`	object	No	Pre-deploy job configuration
`initialDeploy`	object	No	Job to run only on first deployment
`autoRollback`	object	No	Automatic rollback settings
`efsStorage`	object	No	AWS EFS storage configuration

You must specify either build or image, but not both. Use build when Porter should build your container image, or image when using a pre-built image from a registry.

`version`

string Required The schema version. Must be v2.

version: v2

`name`

string Required (unless PORTER_APP_NAME is set) The application name. Must be 31 characters or less, consist of lowercase alphanumeric characters or -, and start and end with an alphanumeric character.

name: my-app

`build`

object Optional Configuration for building container images. Cannot be used together with image.

Field	Type	Required	Description
`method`	string	Yes	Build method: `docker` or `pack`
`context`	string	Yes	Build context directory
`dockerfile`	string	Conditional	Dockerfile path (required if method is `docker`)
`builder`	string	Conditional	Builder image (required if method is `pack`)
`buildpacks`	string[]	No	List of buildpacks (for `pack` method)

build:
  method: docker
  context: .
  dockerfile: ./Dockerfile

build:
  method: pack
  context: .
  builder: heroku/buildpacks:20
  buildpacks:
    - heroku/python
    - heroku/nodejs

We recommend defining a Dockerfile over using buildpacks - if you’re not sure which to use, default to creating a Dockerfile for your application. For more information about creating a Dockerfile, you can look here.

For available builder and buildpacks values, see the Cloud Native Buildpacks Registry or Paketo Builders Reference documentation. Common builders include heroku/builder:24 and paketobuildpacks/builder-jammy-full:latest.

`image`

object Optional Configuration for using a pre-built container image. Cannot be used together with build.

Field	Type	Required	Description
`repository`	string	Yes	Image repository URL
`tag`	string	No	Image tag (can be overridden with `--tag` flag)

image:
  repository: my-registry/my-app
  tag: latest

`env`

object Optional Environment variables to set for all services. Values must be strings.

env:
  PORT: 8080

For sensitive values, use environment groups instead of hardcoding them in porter.yaml.

`envGroups`

string[] Optional Names of environment groups to attach to the application. Environment groups are project-wide and must already exist before deploying.

envGroups:
  - production-secrets
  - shared-config
  - database-credentials

`predeploy`

object Optional A job that runs before deploying services. Commonly used for database migrations.

Field	Type	Required	Description
`run`	string	Yes	Command to execute
`cpuCores`	number	No	CPU allocation
`ramMegabytes`	number	No	Memory allocation

predeploy:
  run: echo "predeploy"

See Predeploy Configuration for more details.

`initialDeploy`

object Optional A job that runs only on the first deployment of a preview environment. Useful for one-time setup tasks like database seeding.

Field	Type	Required	Description
`run`	string	Yes	Command to execute
`cpuCores`	number	No	CPU allocation
`ramMegabytes`	number	No	Memory allocation

initialDeploy:
  run: npm run seed
  cpuCores: 0.25
  ramMegabytes: 256

`autoRollback`

object Optional Configure automatic rollback when deployments fail.

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable or disable auto-rollback

autoRollback:
  enabled: true

When enabled, Porter automatically rolls back all services to the last successfully deployed version if any service fails to deploy.

`efsStorage`

object Optional Enable AWS EFS (Elastic File System) storage for persistent data. Only available on AWS clusters.

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable EFS storage

efsStorage:
  enabled: true

`services`

array Required List of service definitions. Each service represents a deployable unit of your application.

Common Service Fields

These fields apply to all service types:

Field	Type	Required	Description
`name`	string	Yes	Unique service identifier (max 31 chars, lowercase alphanumeric and `-`)
`type`	string	Yes	Service type: `web`, `worker`, or `job`
`run`	string	Yes	Command to execute
`instances`	integer	No	Number of replicas (not for jobs)
`cpuCores`	number	Yes	CPU allocation (e.g., `0.5`, `1`, `2`)
`ramMegabytes`	integer	Yes	Memory allocation in MB
`gpuCoresNvidia`	integer	No	NVIDIA GPU cores to allocate
`port`	integer	Conditional	Port the service listens on (required for `web`)
`nodeGroup`	string	No	UUID of a user node group to run on
`connections`	array	No	External cloud service connections
`terminationGracePeriodSeconds`	integer	No	Seconds to wait before force-killing pods
`serviceMeshEnabled`	boolean	No	Enable service mesh for inter-service communication
`metricsScraping`	object	No	Prometheus metrics scraping configuration

Service Types

Type	Description	Documentation
`web`	HTTP services with public or private endpoints	Web Services
`worker`	Background processing services	Worker Services
`job`	Scheduled or on-demand tasks	Job Services

Basic Example

services:
  - name: web
    type: web
    run: python app.py
    instances: 1
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
  - name: web-on-user-node-group
    type: web
    run: python app.py
    instances: 1
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000

`connections`

array Optional Configure connections to external cloud services. See Connections Configuration for full documentation.

AWS Role Connection

Attach an IAM role to your service for AWS API access.

services:
  - name: web
    ...
    connections:
      - type: awsRole
        role: iam-role-name

Azure Managed Identity Connection

Bind a User Assigned Managed Identity to your service for Azure API access via Azure Workload Identity.

services:
  - name: web
    ...
    connections:
      - type: azureManagedIdentity
        identityName: my-managed-identity
        resourceGroup: my-resource-group

GCP Service Account Connection

Bind a GCP IAM service account to your service for GCP API access without service account key files.

services:
  - name: web
    ...
    connections:
      - type: gcpServiceAccount
        serviceAccountEmail: my-app@my-project.iam.gserviceaccount.com

Cloud SQL Connection (GCP)

Connect to Google Cloud SQL instances.

services:
  - name: web
    ...
    connections:
      - type: cloudSql
        config:
          cloudSqlConnectionName: project-123456:us-east1:instance-name
          cloudSqlDatabasePort: 5432
          cloudSqlServiceAccount: service-account-name

Persistent Disk Connection

Attach persistent storage to your service.

services:
  - name: web
    ...
    connections:
      - type: disk
        config:
          diskName: my-disk

`gpu`

object Optional Configure GPU resources for machine learning workloads.

Field	Type	Description
`gpuCoresNvidia`	integer	Number of NVIDIA GPU cores

services:
  - name: web
    ...
    gpuCoresNvidia: 1
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000

GPU workloads require a node group with GPU-enabled instances.

`metricsScraping`

object Optional Configure Prometheus metrics scraping for custom application metrics.

Field	Type	Description
`enabled`	boolean	Enable metrics scraping
`path`	string	HTTP path to scrape (default: `/metrics`)
`port`	integer	Port to scrape metrics from
`scrapeIntervalSeconds`	integer	Scrape interval in seconds (default: 60)

services:
  - name: web
    ...
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090

Complete Example

version: v2
name: my-app

build:
  method: docker
  context: .
  dockerfile: ./Dockerfile

env:
  PORT: "8080"
  LOG_LEVEL: "info"

envGroups:
  - production-secrets
  - shared-config

predeploy:
  run: python manage.py migrate
  cpuCores: 0.5
  ramMegabytes: 512

initialDeploy:
  run: python manage.py seed
  cpuCores: 0.25
  ramMegabytes: 256

autoRollback:
  enabled: true

efsStorage:
  enabled: true

services:
  # Web service with all options
  - name: web
    type: web
    run: python app.py
    instances: 2
    cpuCores: 1
    ramMegabytes: 1024
    port: 8080
    terminationGracePeriodSeconds: 30
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 10
      cpuThresholdPercent: 80
      memoryThresholdPercent: 80
    healthCheck:
      enabled: true
      httpPath: /healthz
    domains:
      - name: app.example.com
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
      scrapeIntervalSeconds: 30
    connections:
      - type: awsRole
        role: my-app-role

  # GPU-enabled worker on a custom node group
  - name: ml-worker
    type: worker
    run: python ml_worker.py
    instances: 1
    cpuCores: 4
    ramMegabytes: 16384
    gpuCoresNvidia: 1
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000
    terminationGracePeriodSeconds: 60
    serviceMeshEnabled: true

  # Background worker
  - name: worker
    type: worker
    run: python worker.py
    instances: 1
    cpuCores: 0.5
    ramMegabytes: 512

  # Scheduled job
  - name: cleanup
    type: job
    run: python cleanup.py
    cpuCores: 0.5
    ramMegabytes: 256
    cron: "0 0 * * *"

Web Services - Web service configuration
Worker Services - Worker service configuration
Job Services - Job service configuration
Predeploy Jobs - Pre-deploy job configuration
Autoscaling Configuration - Autoscaling configuration reference
Connections Configuration - Cloud connections reference
porter apply - CLI reference for deployments

​Top-Level Fields

​version

​name

​build

​image

​env

​envGroups

​predeploy

​initialDeploy

​autoRollback

​efsStorage

​services

​Common Service Fields

​Service Types

​Basic Example

​connections

​AWS Role Connection

​Azure Managed Identity Connection

​GCP Service Account Connection

​Cloud SQL Connection (GCP)

​Persistent Disk Connection

​gpu

​metricsScraping

​Complete Example

​Related Documentation

Top-Level Fields

`version`

`name`

`build`

`image`

`env`

`envGroups`

`predeploy`

`initialDeploy`

`autoRollback`

`efsStorage`

`services`

Common Service Fields

Service Types

Basic Example

`connections`

AWS Role Connection

Azure Managed Identity Connection

GCP Service Account Connection

Cloud SQL Connection (GCP)

Persistent Disk Connection

`gpu`

`metricsScraping`

Complete Example

Related Documentation