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

# Worker services in porter.yaml

> Complete field reference for worker services in porter.yaml including health checks, autoscaling, GPU allocation, and resource limits

Worker services are background processing services that don't expose HTTP endpoints. They're ideal for queue consumers, background jobs, and long-running processes. This is a complete reference for all fields that can be set for a worker service in `porter.yaml`.

## Field Reference

| Field                           | Type    | Required | Description                       |
| ------------------------------- | ------- | -------- | --------------------------------- |
| `name`                          | string  | Yes      | Service identifier (max 31 chars) |
| `type`                          | string  | Yes      | Must be `worker`                  |
| `run`                           | string  | Yes      | Command to execute                |
| `cpuCores`                      | number  | Yes      | CPU allocation                    |
| `ramMegabytes`                  | integer | Yes      | Memory allocation in MB           |
| `instances`                     | integer | No       | Number of replicas (default: 1)   |
| `autoscaling`                   | object  | No       | Autoscaling 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              |
| `connections`                   | array   | No       | External cloud connections        |
| `serviceMeshEnabled`            | boolean | No       | Enable service mesh               |
| `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: queue-worker
    type: worker
    run: npm run worker
    cpuCores: 0.5
    ramMegabytes: 512
    instances: 3
```

***

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

***

## `healthCheck`

`object`

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

Configure a combined health check that applies to liveness, readiness, and startup probes. Worker services use command-based health checks since they don't expose HTTP endpoints.

| Field                 | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| `enabled`             | boolean | Enable health checks                   |
| `command`             | string  | Command to run for health check        |
| `timeoutSeconds`      | integer | Command timeout (min: 1)               |
| `initialDelaySeconds` | integer | Initial delay before checking (min: 0) |

```yaml theme={null}
healthCheck:
  enabled: true
  command: ./healthcheck.sh
  timeoutSeconds: 5
  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 command-based health checks with graceful shutdown (SIGTERM handling, shutdown markers), see [Zero-Downtime Deployments: Workers](/applications/configure/zero-downtime-deployments#workers).
</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
  command: ./livez.sh
  timeoutSeconds: 5
  initialDelaySeconds: 15
```

### `readinessCheck`

`object`

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

Determines if the container is ready to receive work.

```yaml theme={null}
readinessCheck:
  enabled: true
  command: ./readyz.sh
  timeoutSeconds: 5
  initialDelaySeconds: 5
```

### `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
  command: ./startupz.sh
  timeoutSeconds: 10
  initialDelaySeconds: 0
```

***

## `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>
  Useful for workers that need to communicate with other services in your cluster.
</Info>

***

## `terminationGracePeriodSeconds`

`integer`

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

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

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

<Tip>
  Set this to a value higher than your longest expected job. This gives workers time to complete in-progress work before shutdown.
</Tip>

***

## `gpuCoresNvidia`

`integer`

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

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

```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: queue-processor
    type: worker
    run: npm run worker
    cpuCores: 1
    ramMegabytes: 2048

    # Autoscaling
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 20
      cpuThresholdPercent: 70
      memoryThresholdPercent: 80

    # Health checks
    livenessCheck:
      enabled: true
      command: ./healthcheck.sh
      timeoutSeconds: 5
    readinessCheck:
      enabled: true
      command: ./ready.sh
      timeoutSeconds: 3

    # Cloud connections
    connections:
      - type: awsRole
        role: worker-sqs-access

    # Service mesh
    serviceMeshEnabled: true

    # Graceful shutdown (allow 2 minutes for jobs to complete)
    terminationGracePeriodSeconds: 120
```

***

## Common Use Cases

### Queue Consumer

```yaml theme={null}
services:
  - name: sqs-consumer
    type: worker
    run: node src/workers/sqs-consumer.js
    cpuCores: 0.5
    ramMegabytes: 512
    instances: 5
    terminationGracePeriodSeconds: 60
    connections:
      - type: awsRole
        role: sqs-consumer-role
```

### Background Job Processor

```yaml theme={null}
services:
  - name: job-processor
    type: worker
    run: bundle exec sidekiq
    cpuCores: 1
    ramMegabytes: 1024
    autoscaling:
      enabled: true
      minInstances: 2
      maxInstances: 10
      cpuThresholdPercent: 70
    terminationGracePeriodSeconds: 300
```

### ML Inference Worker

```yaml theme={null}
services:
  - name: ml-worker
    type: worker
    run: python worker.py
    cpuCores: 4
    ramMegabytes: 8192
    gpuCoresNvidia: 1
    nodeGroup: gpu-node-group-uuid
    instances: 2
```