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

# Web services in porter.yaml

> Complete field reference for web services in porter.yaml including ports, custom domains, health checks, autoscaling, and path-based routing

Web services are HTTP-based services that can be exposed publicly or kept private within your cluster. This is a complete reference for all fields that can be set for a web service in `porter.yaml`.

## Field Reference

| Field                           | Type    | Required | Description                                                                    |
| ------------------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `name`                          | string  | Yes      | Service identifier (max 31 chars)                                              |
| `type`                          | string  | Yes      | Must be `web`                                                                  |
| `run`                           | string  | Yes      | Command to execute                                                             |
| `port`                          | integer | Yes      | Port the service listens on                                                    |
| `cpuCores`                      | number  | Yes      | CPU allocation                                                                 |
| `ramMegabytes`                  | integer | Yes      | Memory allocation in MB                                                        |
| `instances`                     | integer | No       | Number of replicas (default: 1)                                                |
| `private`                       | boolean | No       | Route the service through the cluster's private load balancer (default: false) |
| `loadBalancerConfig`            | object  | No       | Load balancer configuration (`public_lb` or `private_lb`)                      |
| `disableTLS`                    | boolean | No       | Disable TLS termination                                                        |
| `autoscaling`                   | object  | No       | Autoscaling configuration                                                      |
| `domains`                       | array   | No       | Custom domain configuration                                                    |
| `healthCheck`                   | object  | No       | Combined health check config                                                   |
| `livenessCheck`                 | object  | No       | Liveness probe config                                                          |
| `readinessCheck`                | object  | No       | Readiness probe config                                                         |
| `startupCheck`                  | object  | No       | Startup probe config                                                           |
| `pathRouting`                   | array   | No       | Path-based routing rules                                                       |
| `pathRoutingConfig`             | object  | No       | Path routing options                                                           |
| `ingressAnnotations`            | object  | No       | Custom ingress annotations                                                     |
| `connections`                   | array   | No       | External cloud connections                                                     |
| `serviceMeshEnabled`            | boolean | No       | Enable service mesh                                                            |
| `metricsScraping`               | object  | No       | Prometheus metrics config                                                      |
| `terminationGracePeriodSeconds` | integer | No       | Graceful shutdown timeout                                                      |
| `gpuCoresNvidia`                | integer | No       | NVIDIA GPU cores                                                               |
| `nodeGroup`                     | string  | No       | Node group UUID                                                                |

***

## Basic Example

```yaml theme={null}
services:
  - name: api
    type: web
    run: node server.js
    port: 8080
    cpuCores: 0.5
    ramMegabytes: 512
    instances: 2
```

***

## `private`

`boolean`

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

When `true`, the service is fronted by the cluster's **private load balancer** instead of the default public one. The service is reachable only from networks peered to your VPC (PrivateLink, VPC peering, transit gateway) — not from the public internet.

This requires the cluster to have a private load balancer provisioned. See [advanced cluster settings](/cloud-accounts/advanced-cluster-settings#private-load-balancer) to enable one.

```yaml theme={null}
private: true
```

<Info>
  `private` is shorthand for `loadBalancerConfig.mode: private_lb`. Prefer `loadBalancerConfig` for new services — setting both on the same service is not supported.
</Info>

***

## `loadBalancerConfig`

`object`

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

Configures the load balancer that fronts the web service. Use this to explicitly route the service through the cluster's public or private load balancer.

| Field  | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `mode` | string | Yes      | `public_lb` (default) or `private_lb` |

When `mode` is `private_lb`, the service is fronted by the cluster's private load balancer and is reachable only from peered networks. The cluster must have a private load balancer provisioned (see [advanced cluster settings](/cloud-accounts/advanced-cluster-settings#private-load-balancer)). Custom domains attached to a private service must have DNS provider credentials configured on the cluster so Porter can provision certificates for custom domains.

When `mode` is `public_lb` or `loadBalancerConfig` is omitted, the service is fronted by the cluster's default public load balancer.

```yaml theme={null}
services:
  - name: internal-admin
    type: web
    run: node server.js
    port: 8080
    cpuCores: 0.5
    ramMegabytes: 512
    loadBalancerConfig:
      mode: private_lb
    domains:
      - name: admin.internal.example.com
```

***

## `disableTLS`

`boolean`

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

Disable TLS termination at the load balancer. Only use this for services that handle their own TLS or for internal testing.

```yaml theme={null}
disableTLS: true
```

<Warning>
  Disabling TLS exposes your service over HTTP. Only use this when you have a specific requirement.
</Warning>

***

## `autoscaling`

`object`

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

Configure horizontal pod autoscaling based on CPU and memory utilization. See [Autoscaling Configuration](/applications/configuration-as-code/services/autoscaling) for full documentation.

***

## `domains`

`array`

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

Configure custom domains for your web service.

| Field  | Type   | Description |
| ------ | ------ | ----------- |
| `name` | string | Domain name |

```yaml theme={null}
domains:
  - name: example.com
```

***

## `healthCheck`

`object`

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

Configure a combined health check that applies to liveness, readiness, and startup probes.

| Field                 | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| `enabled`             | boolean | Enable health checks                   |
| `httpPath`            | string  | HTTP endpoint to check                 |
| `timeoutSeconds`      | integer | Request timeout (min: 1)               |
| `initialDelaySeconds` | integer | Initial delay before checking (min: 0) |

```yaml theme={null}
healthCheck:
  enabled: true
  httpPath: /healthz
  timeoutSeconds: 1
  initialDelaySeconds: 15
```

<Warning>
  Cannot be used together with `livenessCheck`, `readinessCheck`, or `startupCheck`. Use either the combined `healthCheck` or the individual checks.
</Warning>

<Tip>
  For best practices on combining health checks with graceful shutdown for zero-downtime deployments, see [Zero-Downtime Deployments](/applications/configure/zero-downtime-deployments).
</Tip>

***

## Advanced Health Checks

For fine-grained control, configure liveness, readiness, and startup probes separately.

### `livenessCheck`

`object`

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

Determines if the container should be restarted.

```yaml theme={null}
livenessCheck:
  enabled: true
  httpPath: /livez
  timeoutSeconds: 1
  initialDelaySeconds: 15
```

### `readinessCheck`

`object`

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

Determines if the container is ready to receive traffic.

```yaml theme={null}
readinessCheck:
  enabled: true
  httpPath: /readyz
  timeoutSeconds: 1
  initialDelaySeconds: 15
```

### `startupCheck`

`object`

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

Used for slow-starting containers. Other probes are disabled until this passes.

```yaml theme={null}
startupCheck:
  enabled: true
  httpPath: /startupz
  timeoutSeconds: 1
  initialDelaySeconds: 15
```

***

## `pathRouting`

`array`

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

Configure path-based routing to direct requests to different ports or services.

| Field         | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `path`        | string  | Yes      | URL path prefix                                  |
| `port`        | integer | Yes      | Port to route to                                 |
| `serviceName` | string  | No       | Service to route to (defaults to current)        |
| `appName`     | string  | No       | Application to route to (requires `serviceName`) |

```yaml theme={null}
pathRouting:
  - path: /api/v1/
    port: 8080
  - path: /api/v2/
    port: 8081
  - path: /admin/
    port: 9000
    serviceName: admin-service
  - path: /auth/
    port: 8080
    appName: auth-app
    serviceName: auth-service
```

<Info>
  A path must be specified for the default port set in `services.port`.
</Info>

***

## `pathRoutingConfig`

`object`

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

Configure path rewriting behavior for path-based routing.

| Field         | Type   | Description       |
| ------------- | ------ | ----------------- |
| `rewriteMode` | string | Path rewrite mode |

**Rewrite Modes:**

| Mode             | Description                           | Example: `/api/v1/users` |
| ---------------- | ------------------------------------- | ------------------------ |
| `rewrite-all`    | Rewrite entire path to root (default) | `/`                      |
| `rewrite-prefix` | Remove the matched prefix only        | `/users`                 |
| `rewrite-off`    | No rewriting, keep original path      | `/api/v1/users`          |

```yaml theme={null}
pathRouting:
  - path: /api/v1/
    port: 8080
  - path: /api/v2/
    port: 8081
pathRoutingConfig:
  rewriteMode: rewrite-prefix
```

***

## `ingressAnnotations`

`object`

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

Add custom NGINX ingress annotations for advanced configuration.

```yaml theme={null}
ingressAnnotations:
  nginx.ingress.kubernetes.io/proxy-connect-timeout: "18000"
```

<Tip>
  Common use cases include increasing upload limits, configuring timeouts, and enabling WebSocket support.
</Tip>

***

## `connections`

`array`

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

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

***

## `serviceMeshEnabled`

`boolean`

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

Enable service mesh for enhanced inter-service communication with improved performance, reliability, and monitoring.

```yaml theme={null}
serviceMeshEnabled: true
```

<Info>
  Recommended for applications with multiple services that communicate with each other, especially those using gRPC or WebSockets.
</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}
metricsScraping:
  enabled: true
  path: /metrics
  port: 9090
  scrapeIntervalSeconds: 60
```

***

## `terminationGracePeriodSeconds`

`integer`

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

Seconds to wait for graceful shutdown before forcefully terminating the container.

```yaml theme={null}
terminationGracePeriodSeconds: 60
```

<Tip>
  Increase this value for services that need time to complete in-flight requests or cleanup tasks.
</Tip>

***

## `gpuCoresNvidia`

`integer`

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

Allocate NVIDIA GPU cores for ML inference or GPU-accelerated workloads.

```yaml theme={null}
gpuCoresNvidia: 1
nodeGroup: gpu-node-group-uuid
```

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

***

## Complete Example

```yaml theme={null}
services:
  - name: api
    type: web
    run: npm start
    port: 8080
    cpuCores: 1
    ramMegabytes: 1024

    # Autoscaling
    autoscaling:
      enabled: true
      minInstances: 1
      maxInstances: 10
      cpuThresholdPercent: 80
      memoryThresholdPercent: 80

    # Custom domains
    domains:
      - name: example.com

    # Health checks
    livenessCheck:
      enabled: true
      httpPath: /livez
      timeoutSeconds: 1
      initialDelaySeconds: 15
    readinessCheck:
      enabled: true
      httpPath: /readyz
      timeoutSeconds: 1
      initialDelaySeconds: 15

    # Path routing
    pathRouting:
      - path: /api/v1/
        port: 8080
      - path: /api/v2/
        port: 8081
    pathRoutingConfig:
      rewriteMode: rewrite-prefix

    # Ingress configuration
    ingressAnnotations:
      nginx.ingress.kubernetes.io/proxy-connect-timeout: "18000"

    # Service mesh and metrics
    serviceMeshEnabled: true
    metricsScraping:
      enabled: true
      path: /metrics
      port: 9090
      scrapeIntervalSeconds: 60

    # Cloud connections
    connections:
      - type: awsRole
        role: api-s3-access

    # Graceful shutdown
    terminationGracePeriodSeconds: 30
```