nomad job plan: Dry-Run a Nomad Deploy in CI
nomad job plan runs the scheduler in dry-run mode, showing what would change and printing the job modify index for a safe apply.
plan is the terraform-plan of Nomad. It shows the diff, predicts placement, and gives you the index to pass to nomad job run -check-index.
What it does
nomad job plan submits the job for evaluation without persisting it. It prints a diff against the current job, reports whether allocations can be placed, and ends with the recommended nomad job run -check-index command carrying the current modify index.
Common usage
nomad job plan web.nomad.hcl
nomad job plan -diff=false web.nomad.hcl
nomad job plan -var="image=app:1.4.2" web.nomad.hclOptions
| Flag | What it does |
|---|---|
| -diff | Show the diff against the running job (default true) |
| -verbose | Show full IDs and per-allocation detail |
| -var <k>=<v> | Set an HCL2 variable |
| -policy-override | Override soft-mandatory Sentinel policies (Enterprise) |
In CI
plan exit codes are meaningful: 0 means no allocations created or destroyed, 1 means an error, and 255 means allocations would change. Gate a deploy on the diff and pass the printed index into nomad job run -check-index so two pipelines cannot race.
Common errors in CI
"Error during plan: Failed to parse using HCL 2 ..." is a jobspec syntax error. A plan that reports "* WARNING: Failed to place all allocations" means constraints or resources cannot be satisfied. Treating exit 255 as a failure is a common CI bug; it signals a non-empty diff, not an error.