> ## Documentation Index
> Fetch the complete documentation index at: https://docs.porter.run/llms.txt
> Use this file to discover all available pages before exploring further.

# porter.yaml reference

> Complete field reference for porter.yaml including build, image, services, environment variables, predeploy, and autoscaling options

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                              |

<Warning>
  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.
</Warning>

***

## `version`

`string`

<Badge shape="pill" color="green">Required</Badge>

The schema version. Must be `v2`.

```yaml theme={null}
version: v2
```

***

## `name`

`string`

<Badge shape="pill" color="green">Required</Badge> (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.

```yaml theme={null}
name: my-app
```

***

## `build`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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)           |

<CodeGroup>
  ```yaml Docker Build theme={null}
  build:
    method: docker
    context: .
    dockerfile: ./Dockerfile
  ```

  ```yaml Buildpack Build theme={null}
  build:
    method: pack
    context: .
    builder: heroku/buildpacks:20
    buildpacks:
      - heroku/python
      - heroku/nodejs
  ```
</CodeGroup>

<Warning>
  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](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/).
</Warning>

<Info>
  For available `builder` and `buildpacks` values, see the [Cloud Native Buildpacks Registry](https://registry.buildpacks.io/) or [Paketo Builders Reference](https://paketo.io/docs/reference/builders-reference/) documentation. Common builders include `heroku/builder:24` and `paketobuildpacks/builder-jammy-full:latest`.
</Info>

***

## `image`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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) |

```yaml theme={null}
image:
  repository: my-registry/my-app
  tag: latest
```

***

## `env`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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

```yaml theme={null}
env:
  PORT: 8080
```

<Info>
  For sensitive values, use environment groups instead of hardcoding them in `porter.yaml`.
</Info>

***

## `envGroups`

`string[]`

<Badge shape="pill" color="gray">Optional</Badge>

Names of [environment groups](/applications/configure/environment-groups) to attach to the application. Environment groups are project-wide and must already exist before deploying.

```yaml theme={null}
envGroups:
  - production-secrets
  - shared-config
  - database-credentials
```

***

## `predeploy`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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  |

```yaml theme={null}
predeploy:
  run: echo "predeploy"
```

See [Predeploy Configuration](/applications/configuration-as-code/services/predeploy) for more details.

***

## `initialDeploy`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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  |

```yaml theme={null}
initialDeploy:
  run: npm run seed
  cpuCores: 0.25
  ramMegabytes: 256
```

***

## `autoRollback`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

Configure automatic rollback when deployments fail.

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

```yaml theme={null}
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`

<Badge shape="pill" color="gray">Optional</Badge>

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 |

```yaml theme={null}
efsStorage:
  enabled: true
```

***

## `services`

`array`

<Badge shape="pill" color="green">Required</Badge>

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](/applications/configuration-as-code/services/web-service)       |
| `worker` | Background processing services                 | [Worker Services](/applications/configuration-as-code/services/worker-service) |
| `job`    | Scheduled or on-demand tasks                   | [Job Services](/applications/configuration-as-code/services/job-service)       |

### Basic Example

```yaml theme={null}
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`

<Badge shape="pill" color="gray">Optional</Badge>

Configure connections to external cloud services. See [Connections Configuration](/applications/configuration-as-code/services/connections) for full documentation.

### AWS Role Connection

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

```yaml theme={null}
services:
  - name: web
    ...
    connections:
      - type: awsRole
        role: iam-role-name
```

### Cloud SQL Connection (GCP)

Connect to Google Cloud SQL instances.

```yaml theme={null}
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.

```yaml theme={null}
services:
  - name: web
    ...
    connections:
      - type: disk
        config:
          diskName: my-disk
```

***

## `gpu`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

Configure GPU resources for machine learning workloads.

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

```yaml theme={null}
services:
  - name: web
    ...
    gpuCoresNvidia: 1
    nodeGroup: 123e4567-e89b-12d3-a456-426614174000
```

<Info>
  GPU workloads require a node group with GPU-enabled instances.
</Info>

***

## `metricsScraping`

`object`

<Badge shape="pill" color="gray">Optional</Badge>

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)  |

```yaml theme={null}
services:
  - name: web
    ...
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
```

***

## Complete Example

```yaml theme={null}
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 * * *"
```

***

## Related Documentation

* [Web Services](/applications/configuration-as-code/services/web-service) - Web service configuration
* [Worker Services](/applications/configuration-as-code/services/worker-service) - Worker service configuration
* [Job Services](/applications/configuration-as-code/services/job-service) - Job service configuration
* [Predeploy Jobs](/applications/configuration-as-code/services/predeploy) - Pre-deploy job configuration
* [Autoscaling Configuration](/applications/configuration-as-code/services/autoscaling) - Autoscaling configuration reference
* [Connections Configuration](/applications/configuration-as-code/services/connections) - Cloud connections reference
* [porter apply](/standard/cli/command-reference/porter-apply) - CLI reference for deployments