Running Ad‑Hoc Work with Nomad’s Parameterized Batch Jobs

Why Parameterized Batch Jobs?

In many teams, you need to run finite, on‑demand workloads: a nightly report, a monthly data backfill, or a one‑off schema migration. You could register a new Nomad job for each run, but that quickly becomes a maintenance nightmare. Nomad’s parameterized batch jobs let you register a single job template once and dispatch it multiple times with different payloads. Each dispatch becomes an independent child job, so logs, failures, and scheduling are isolated.

Key Concepts

• Batch job type – Runs to completion and is not rescheduled on success.
• Parameterized block – Declares required and optional metadata keys that each dispatch must supply.
• NOMAD_META_ – Environment variables automatically populated from the dispatched metadata.
• Child job – The runtime instance created by a dispatch; it inherits the parent’s constraints, resources, and placement rules.

Concrete Example: Nightly Report Generator

Below is a minimal job file that runs a Python script to generate a report for a given date and upload it to an S3 bucket. The job is parameterized by REPORT_DATE and OUTPUT_BUCKET so you can dispatch it nightly with the desired date and destination.

job "report-generator" {
  type = "batch"

  parameterized {
    required = ["REPORT_DATE", "OUTPUT_BUCKET"]
    optional = ["DEBUG"]
  }

  group "default" {
    task "generate" {
      driver = "docker"
      config {
        image = "python:3.12-slim"
        command = ["python", "/app/report.py"]
      }

      env {
        REPORT_DATE   = "${NOMAD_META_REPORT_DATE}"
        OUTPUT_BUCKET = "${NOMAD_META_OUTPUT_BUCKET}"
        DEBUG         = "${NOMAD_META_DEBUG:-false}"
      }
    }
  }
}

Save this as report-generator.nomad and register it once:

nomad job register report-generator.nomad

Now dispatch it from a CI pipeline or a cron job:

nomad job dispatch report-generator \
  -meta REPORT_DATE=2026-10-15 \
  -meta OUTPUT_BUCKET=my-analytics-reports \
  -meta DEBUG=true

Each dispatch creates a child job named report-generator-uuid. Inside the task you can read the values via environment variables or the NOMAD_META_ prefix. For example, a simple report.py could start with:

import os
print("Report date:", os.getenv("REPORT_DATE"))
print("Output bucket:", os.getenv("OUTPUT_BUCKET"))
print("Debug mode:", os.getenv("DEBUG"))

After the job completes, its allocation logs are available in Nomad’s UI or via nomad alloc logs. If the allocation fails, Nomad will reschedule it like any other job, respecting the constraints defined in the parent specification.

Dispatch vs. Periodic Jobs

Nomad also offers periodic jobs for recurring schedules. Why choose parameterized dispatch instead? When the trigger for a run is external—e.g., a CI pipeline that decides the date to process, or a user‑initiated backfill—you don’t want to hard‑code the schedule into the job file. Dispatch gives you that flexibility while keeping a single, centrally maintained job definition.

Trade‑offs & Limitations

• No built‑in queue semantics – Dispatching is instant; there’s no retry‑with‑backoff or dead‑letter queue. Your application must be idempotent or handle duplicates.
• Metadata size limits – Metadata is stored in Raft state. Large payloads (e.g., hundreds of megabytes) should be avoided; instead, pass a reference to object storage.
• Version drift – The parameterized block syntax and CLI flags have changed across Nomad releases. Verify the syntax against your deployed version’s documentation.

How to Verify the Setup

1. Run nomad job dispatch --help to confirm the -meta flag syntax on your version.
2. After dispatch, list allocations with nomad alloc list and note the child job name.
3. Inspect the allocation’s environment by running nomad alloc exec <alloc-id> -- env | grep NOMAD_META.
4. Simulate a node failure by stopping a Nomad agent and observe the allocation’s reschedule behavior.

Actionable Next Steps

1. Register your batch template once and keep it under source control.
2. Integrate nomad job dispatch into your CI/CD pipeline or cron system.
3. Implement idempotent logic in your task to guard against duplicate runs.
4. Set up alerts on allocation failures so you can react quickly.

Parameterized batch jobs give you a lightweight, version‑controlled way to run ad‑hoc workloads in Nomad without the overhead of managing multiple job files or building a custom queue system. Start with the example above, adapt the parameters to your use case, and observe how each dispatch remains isolated and fully schedulable within your Nomad cluster.