1e3c3cb287
IOPS have been modelled as a resource since Nomad 0.1 but has never actually been detected and there is no plan in the short term to add detection. This is because IOPS is a bit simplistic of a unit to define the performance requirements from the underlying storage system. In its current state it adds unnecessary confusion and can be removed without impacting any users. This PR leaves IOPS defined at the jobspec parsing level and in the api/ resources since these are the two public uses of the field. These should be considered deprecated and only exist to allow users to stop using them during the Nomad 0.9.x release. In the future, there should be no expectation that the field will exist.
204 lines
6 KiB
Plaintext
204 lines
6 KiB
Plaintext
---
|
|
layout: "docs"
|
|
page_title: "Commands: job plan"
|
|
sidebar_current: "docs-commands-job-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](/docs/job-specification/index.html) format.
|
|
|
|
## Usage
|
|
|
|
```
|
|
nomad job plan [options] <path>
|
|
```
|
|
|
|
The `job plan` command requires a single argument, specifying the path to a file
|
|
containing a [HCL job specification](/docs/job-specification/index.html). 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`](https://github.com/hashicorp/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`](/docs/commands/job/run.html#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.
|
|
|
|
## General Options
|
|
|
|
<%= partial "docs/commands/_general_options" %>
|
|
|
|
## 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.
|
|
|
|
* `-verbose`: Increase diff verbosity.
|
|
|
|
## Examples
|
|
|
|
Plan a new job that has not been previously submitted:
|
|
|
|
```
|
|
$ 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
|
|
server side version matches the job modify index returned. 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:
|
|
|
|
```
|
|
$ 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
|
|
server side version matches the job modify index returned. 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:
|
|
|
|
```
|
|
$ 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
|
|
server side version matches the job modify index returned. 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:
|
|
|
|
```
|
|
$ 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
|
|
server side version matches the job modify index returned. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|