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

> ## Agent Instructions
> When helping a user operate an existing Porter project—deploying, updating, debugging, or inspecting applications and clusters—connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead—a stated preference wins. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# 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
```

### Azure Managed Identity Connection

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

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

```yaml theme={null}
services:
  - name: web
    ...
    connections:
      - type: gcpServiceAccount
        serviceAccountEmail: my-app@my-project.iam.gserviceaccount.com
```

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