211 lines
6.3 KiB
Plaintext
211 lines
6.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Commands: job plan'
|
|
sidebar_title: plan
|
|
description: |
|
|
The job plan command is used to dry-run a job update to determine its effects.
|
|
---
|
|
|
|
# Command: job plan
|
|
|
|
**Alias: `nomad plan`**
|
|
|
|
The `job plan` command can be used to invoke the scheduler in a dry-run mode
|
|
with new jobs or when updating existing jobs to determine what would happen if
|
|
the job is submitted. Job files must conform to the [job specification] format.
|
|
|
|
## Usage
|
|
|
|
```plaintext
|
|
nomad job plan [options] <path>
|
|
```
|
|
|
|
The `job plan` command requires a single argument, specifying the path to a file
|
|
containing an HCL [job specification]. This file will be read and the resulting
|
|
parsed job will be validated. If the supplied path is "-", the job file is read
|
|
from STDIN. Otherwise it is read from the file at the supplied path or
|
|
downloaded and read from URL specified. Nomad downloads the job file using
|
|
[`go-getter`] and supports `go-getter` syntax.
|
|
|
|
Plan invokes a dry-run of the scheduler to determine the effects of submitting
|
|
either a new or updated version of a job. The plan will not result in any
|
|
changes to the cluster but gives insight into whether the job could be run
|
|
successfully and how it would affect existing allocations.
|
|
|
|
A job modify index is returned with the plan. This value can be used when
|
|
submitting the job using [`nomad job run -check-index`], which will check that
|
|
the job was not modified between the plan and run command before invoking the
|
|
scheduler. This ensures the job has not been modified since the plan.
|
|
|
|
A structured diff between the local and remote job is displayed to
|
|
give insight into what the scheduler will attempt to do and why.
|
|
|
|
If the job has specified the region, the `-region` flag and `NOMAD_REGION`
|
|
environment variable are overridden and the job's region is used.
|
|
|
|
Plan will return one of the following exit codes:
|
|
|
|
- 0: No allocations created or destroyed.
|
|
- 1: Allocations created or destroyed.
|
|
- 255: Error determining plan results.
|
|
|
|
When ACLs are enabled, this command requires a token with the `submit-job`
|
|
capability for the job's namespace.
|
|
|
|
## General Options
|
|
|
|
@include 'general_options.mdx'
|
|
|
|
## Plan Options
|
|
|
|
- `-diff`: Determines whether the diff between the remote job and planned job is
|
|
shown. Defaults to true.
|
|
|
|
- `-policy-override`: Sets the flag to force override any soft mandatory
|
|
Sentinel policies.
|
|
|
|
- `-hcl1`: If set, HCL1 parser is used for parsing the job spec.
|
|
|
|
- `-verbose`: Increase diff verbosity.
|
|
|
|
## Examples
|
|
|
|
Plan a new job that has not been previously submitted:
|
|
|
|
```shell-session
|
|
$ nomad job plan job1.nomad
|
|
nomad job plan example.nomad
|
|
+ Job: "example"
|
|
+ Task Group: "cache" (1 create)
|
|
+ Task: "redis" (forces create)
|
|
|
|
Scheduler dry-run:
|
|
- All tasks successfully allocated.
|
|
|
|
Job Modify Index: 0
|
|
To submit the job with version verification run:
|
|
|
|
nomad job run -check-index 0 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
job modify index given matches the server-side version. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
Increase the count of an existing without sufficient cluster capacity:
|
|
|
|
```shell-session
|
|
$ nomad job plan example.nomad
|
|
+/- Job: "example"
|
|
+/- Task Group: "cache" (7 create, 1 in-place update)
|
|
+/- Count: "1" => "8" (forces create)
|
|
Task: "redis"
|
|
|
|
Scheduler dry-run:
|
|
- WARNING: Failed to place all allocations.
|
|
Task Group "cache" (failed to place 3 allocations):
|
|
* Resources exhausted on 1 nodes
|
|
* Dimension "cpu" exhausted on 1 nodes
|
|
|
|
Job Modify Index: 15
|
|
To submit the job with version verification run:
|
|
|
|
nomad job run -check-index 15 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
job modify index given matches the server-side version. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
Update an existing job such that it would cause a rolling update:
|
|
|
|
```shell-session
|
|
$ nomad job plan example.nomad
|
|
+/- Job: "example"
|
|
+/- Task Group: "cache" (3 create/destroy update)
|
|
+/- Task: "redis" (forces create/destroy update)
|
|
+/- Config {
|
|
+/- image: "redis:2.8" => "redis:3.2"
|
|
port_map[0][db]: "6379"
|
|
}
|
|
|
|
Scheduler dry-run:
|
|
- All tasks successfully allocated.
|
|
- Rolling update, next evaluation will be in 10s.
|
|
|
|
Job Modify Index: 7
|
|
To submit the job with version verification run:
|
|
|
|
nomad job run -check-index 7 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
job modify index given matches the server-side version. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
Add a task to the task group using verbose mode:
|
|
|
|
```shell-session
|
|
$ nomad job plan -verbose example.nomad
|
|
+/- Job: "example"
|
|
+/- Task Group: "cache" (3 create/destroy update)
|
|
+ Task: "my-website" (forces create/destroy update)
|
|
+ Driver: "docker"
|
|
+ KillTimeout: "5000000000"
|
|
+ Config {
|
|
+ image: "node:6.2"
|
|
+ port_map[0][web]: "80"
|
|
}
|
|
+ Resources {
|
|
+ CPU: "500"
|
|
+ DiskMB: "300"
|
|
+ MemoryMB: "256"
|
|
+ Network {
|
|
+ MBits: "10"
|
|
+ Dynamic Port {
|
|
+ Label: "web"
|
|
}
|
|
}
|
|
}
|
|
+ LogConfig {
|
|
+ MaxFileSizeMB: "10"
|
|
+ MaxFiles: "10"
|
|
}
|
|
+ Service {
|
|
+ Name: "website"
|
|
+ PortLabel: "web"
|
|
+ Check {
|
|
Command: ""
|
|
+ Interval: "10000000000"
|
|
+ Name: "alive"
|
|
Path: ""
|
|
Protocol: ""
|
|
+ Timeout: "2000000000"
|
|
+ Type: "tcp"
|
|
}
|
|
}
|
|
Task: "redis"
|
|
|
|
Scheduler dry-run:
|
|
- All tasks successfully allocated.
|
|
- Rolling update, next evaluation will be in 10s.
|
|
|
|
Job Modify Index: 7
|
|
To submit the job with version verification run:
|
|
|
|
nomad job run -check-index 7 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
job modify index given matches the server-side version. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
[job specification]: /docs/job-specification
|
|
[hcl job specification]: /docs/job-specification
|
|
[`go-getter`]: https://github.com/hashicorp/go-getter
|
|
[`nomad job run -check-index`]: /docs/commands/job/run#check-index
|