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

​
Top-Level Fields

FieldTypeRequiredDescription
versionstringYesMust be v2
namestringConditionalApp name. Required unless PORTER_APP_NAME env var is set
buildobjectConditionalBuild configuration. Cannot be used with image
imageobjectConditionalPre-built image configuration. Cannot be used with build
servicesarrayYesList of service definitions
envobjectNoEnvironment variables
envGroupsstring[]NoNames of environment groups to attach
predeployobjectNoPre-deploy job configuration
initialDeployobjectNoJob to run only on first deployment
autoRollbackobjectNoAutomatic rollback settings
efsStorageobjectNoAWS 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.
FieldTypeRequiredDescription
methodstringYesBuild method: docker or pack
contextstringYesBuild context directory
dockerfilestringConditionalDockerfile path (required if method is docker)
builderstringConditionalBuilder image (required if method is pack)
buildpacksstring[]NoList of buildpacks (for pack method)
build:
  method: docker
  context: .
  dockerfile: ./Dockerfile
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.
FieldTypeRequiredDescription
repositorystringYesImage repository URL
tagstringNoImage 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 must already exist in the Porter cluster where the app will be deployed. 
envGroups:
  - production-secrets
  - shared-config
  - database-credentials

​
predeploy

object Optional A job that runs before deploying services. Commonly used for database migrations.
FieldTypeRequiredDescription
runstringYesCommand to execute
cpuCoresnumberNoCPU allocation
ramMegabytesnumberNoMemory 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.
FieldTypeRequiredDescription
runstringYesCommand to execute
cpuCoresnumberNoCPU allocation
ramMegabytesnumberNoMemory allocation
initialDeploy:
  run: npm run seed
  cpuCores: 0.25
  ramMegabytes: 256

​
autoRollback

object Optional Configure automatic rollback when deployments fail.
FieldTypeRequiredDescription
enabledbooleanYesEnable 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.
FieldTypeRequiredDescription
enabledbooleanYesEnable 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:
FieldTypeRequiredDescription
namestringYesUnique service identifier (max 31 chars, lowercase alphanumeric and -)
typestringYesService type: web, worker, or job
runstringYesCommand to execute
instancesintegerNoNumber of replicas (not for jobs)
cpuCoresnumberYesCPU allocation (e.g., 0.5, 1, 2)
ramMegabytesintegerYesMemory allocation in MB
gpuCoresNvidiaintegerNoNVIDIA GPU cores to allocate
portintegerConditionalPort the service listens on (required for web)
nodeGroupstringNoUUID of a user node group to run on
connectionsarrayNoExternal cloud service connections
terminationGracePeriodSecondsintegerNoSeconds to wait before force-killing pods
serviceMeshEnabledbooleanNoEnable service mesh for inter-service communication
metricsScrapingobjectNoPrometheus metrics scraping configuration

​
Service Types

TypeDescriptionDocumentation
webHTTP services with public or private endpointsWeb Services
workerBackground processing servicesWorker Services
jobScheduled or on-demand tasksJob 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

​
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.
FieldTypeDescription
gpuCoresNvidiaintegerNumber 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.
FieldTypeDescription
enabledbooleanEnable metrics scraping
pathstringHTTP path to scrape (default: /metrics)
portintegerPort to scrape metrics from
scrapeIntervalSecondsintegerScrape 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 * * *"