Job Services

Job services are for scheduled or on-demand tasks that run to completion. They’re ideal for cron jobs, data processing, and one-time tasks. This is a complete reference for all fields that can be set for a job service in porter.yaml.

Field Reference

Field	Type	Required	Description
name	string	Yes	Service identifier (max 31 chars)
type	string	Yes	Must be job
run	string	Yes	Command to execute
cpuCores	number	Yes	CPU allocation
ramMegabytes	integer	Yes	Memory allocation in MB
cron	string	No	Cron schedule expression
suspendCron	boolean	No	Temporarily disable cron schedule
allowConcurrent	boolean	No	Allow concurrent job runs
timeoutSeconds	integer	No	Maximum job duration
connections	array	No	External cloud connections
terminationGracePeriodSeconds	integer	No	Graceful shutdown timeout
gpuCoresNvidia	integer	No	NVIDIA GPU cores
nodeGroup	string	No	Node group UUID

---

Basic Example

services:
  - name: cleanup
    type: job
    run: npm run cleanup
    cpuCores: 0.25
    ramMegabytes: 256
    cron: "0 0 * * *"

---

cron

string

Optional

A cron expression that defines when the job should run. Uses standard 5-field cron syntax.

cron: "0 0 * * *"

If no cron expression is provided, the job will default to run every 5 minutes.

---

suspendCron

boolean

Optional

Disable the cron schedule without removing it. The job won’t run on schedule but can still be triggered manually.

suspendCron: true

Use this to pause scheduled jobs during maintenance windows or while debugging, or to create one-off jobs.

---

allowConcurrent

boolean

Optional

Allow multiple instances of the job to run simultaneously. By default, a new job run won’t start if a previous run is still in progress.

allowConcurrent: true

Be careful enabling this for jobs that modify shared resources. Concurrent runs may cause race conditions or data inconsistency.

---

timeoutSeconds

integer

Optional

Maximum number of seconds the job is allowed to run before being terminated.

timeoutSeconds: 3600

If not specified, jobs may run indefinitely. It’s recommended to set a reasonable timeout for all jobs.

---

connections

array

Optional

Connect to external cloud services. See Connections Configuration for full documentation.

---

terminationGracePeriodSeconds

integer

Optional

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

terminationGracePeriodSeconds: 30

Use this to ensure jobs can clean up resources or checkpoint progress before termination.

---

gpuCoresNvidia

integer

Optional

Allocate NVIDIA GPU cores for ML training, inference, or GPU-accelerated processing.

gpuCoresNvidia: 1
nodeGroup: gpu-node-group-uuid

Requires a node group with GPU-enabled instances.

---

Triggering Jobs Manually

Jobs can be triggered manually using the Porter CLI:

# Trigger a job run
porter app run my-app --job my-job

# Trigger and wait for completion
porter app run my-app --job my-job --wait

# Override concurrent restriction
porter app run my-app --job my-job --allow-concurrent

---

Complete Example

services:
  - name: daily-report
    type: job
    run: python generate_report.py
    cpuCores: 1
    ramMegabytes: 2048

    # Schedule: Daily at 6 AM UTC
    cron: "0 6 * * *"

    # Allow up to 2 hours
    timeoutSeconds: 7200

    # Don't allow concurrent runs
    allowConcurrent: false

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

    # Graceful shutdown
    terminationGracePeriodSeconds: 60

---

Common Use Cases

Database Cleanup

services:
  - name: db-cleanup
    type: job
    run: npm run cleanup-old-records
    cpuCores: 0.25
    ramMegabytes: 256
    cron: "0 3 * * *"  # 3 AM daily
    timeoutSeconds: 1800
    allowConcurrent: false

Data Export

services:
  - name: weekly-export
    type: job
    run: python export_data.py
    cpuCores: 0.5
    ramMegabytes: 1024
    cron: "0 0 * * 0"  # Sunday at midnight
    timeoutSeconds: 14400  # 4 hours
    connections:
      - type: awsRole
        role: s3-export-role

ML Training Job

services:
  - name: model-training
    type: job
    run: python train.py
    cpuCores: 8
    ramMegabytes: 32768
    gpuCoresNvidia: 4
    nodeGroup: gpu-node-group-uuid
    timeoutSeconds: 86400  # 24 hours
    terminationGracePeriodSeconds: 300

Health Check / Monitoring

services:
  - name: healthcheck
    type: job
    run: ./check_dependencies.sh
    cpuCores: 0.1
    ramMegabytes: 128
    cron: "*/5 * * * *"  # Every 5 minutes
    timeoutSeconds: 60
    allowConcurrent: false

Manual Migration Job

services:
  - name: data-migration
    type: job
    run: python migrate.py
    cpuCores: 2
    ramMegabytes: 4096
    suspendCron: true  # otherwise, the job will run every 5 minutes by default
    timeoutSeconds: 28800  # 8 hours
    allowConcurrent: false
    terminationGracePeriodSeconds: 120

Jobs with suspendCron: true must be triggered manually using porter app run --job.

---

Job resource retention

Completed job runs are automatically cleaned up from the cluster after 7 days. During this retention window, you can inspect completed job resources directly in Kubernetes. After the retention period, the underlying Kubernetes job resource is removed, but job run history remains available in the Porter dashboard.