github.com/smintz/nomad@v0.8.3/website/source/docs/commands/job/plan.html.md.erb (about) 1 --- 2 layout: "docs" 3 page_title: "Commands: job plan" 4 sidebar_current: "docs-commands-job-plan" 5 description: > 6 The job plan command is used to dry-run a job update to determine its effects. 7 --- 8 9 # Command: job plan 10 **Alias: `nomad plan`** 11 12 The `job plan` command can be used to invoke the scheduler in a dry-run mode with 13 new jobs or when updating existing jobs to determine what would happen if the 14 job is submitted. Job files must conform to the [job 15 specification](/docs/job-specification/index.html) format. 16 17 ## Usage 18 19 ``` 20 nomad job plan [options] <path> 21 ``` 22 23 The `job plan` command requires a single argument, specifying the path to a file 24 containing a [HCL job specification](/docs/job-specification/index.html). This 25 file will be read and the resulting parsed job will be validated. If the 26 supplied path is "-", the job file is read from STDIN. Otherwise it is read 27 from the file at the supplied path or downloaded and read from URL specified. 28 Nomad downloads the job file using 29 [`go-getter`](https://github.com/hashicorp/go-getter) 30 and supports `go-getter` syntax. 31 32 Plan invokes a dry-run of the scheduler to determine the effects of submitting 33 either a new or updated version of a job. The plan will not result in any 34 changes to the cluster but gives insight into whether the job could be run 35 successfully and how it would affect existing allocations. 36 37 A job modify index is returned with the plan. This value can be used when 38 submitting the job using [`nomad job run 39 -check-index`](/docs/commands/job/run.html#check-index), which will check that the 40 job was not modified between the plan and run command before invoking the 41 scheduler. This ensures the job has not been modified since the plan. 42 43 A structured diff between the local and remote job is displayed to 44 give insight into what the scheduler will attempt to do and why. 45 46 If the job has specified the region, the `-region` flag and `NOMAD_REGION` 47 environment variable are overridden and the job's region is used. 48 49 Plan will return one of the following exit codes: 50 51 * 0: No allocations created or destroyed. 52 * 1: Allocations created or destroyed. 53 * 255: Error determining plan results. 54 55 ## General Options 56 57 <%= partial "docs/commands/_general_options" %> 58 59 ## Plan Options 60 61 * `-diff`: Determines whether the diff between the remote job and planned job is 62 shown. Defaults to true. 63 64 * `-policy-override`: Sets the flag to force override any soft mandatory Sentinel policies. 65 66 * `-verbose`: Increase diff verbosity. 67 68 ## Examples 69 70 Plan a new job that has not been previously submitted: 71 72 ``` 73 $ nomad job plan job1.nomad 74 nomad job plan example.nomad 75 + Job: "example" 76 + Task Group: "cache" (1 create) 77 + Task: "redis" (forces create) 78 79 Scheduler dry-run: 80 - All tasks successfully allocated. 81 82 Job Modify Index: 0 83 To submit the job with version verification run: 84 85 nomad job run -check-index 0 example.nomad 86 87 When running the job with the check-index flag, the job will only be run if the 88 server side version matches the job modify index returned. If the index has 89 changed, another user has modified the job and the plan's results are 90 potentially invalid. 91 ``` 92 93 94 Increase the count of an existing without sufficient cluster capacity: 95 96 ``` 97 $ nomad job plan example.nomad 98 +/- Job: "example" 99 +/- Task Group: "cache" (7 create, 1 in-place update) 100 +/- Count: "1" => "8" (forces create) 101 Task: "redis" 102 103 Scheduler dry-run: 104 - WARNING: Failed to place all allocations. 105 Task Group "cache" (failed to place 3 allocations): 106 * Resources exhausted on 1 nodes 107 * Dimension "cpu" exhausted on 1 nodes 108 109 Job Modify Index: 15 110 To submit the job with version verification run: 111 112 nomad job run -check-index 15 example.nomad 113 114 When running the job with the check-index flag, the job will only be run if the 115 server side version matches the job modify index returned. If the index has 116 changed, another user has modified the job and the plan's results are 117 potentially invalid. 118 ``` 119 120 Update an existing job such that it would cause a rolling update: 121 122 ``` 123 $ nomad job plan example.nomad 124 +/- Job: "example" 125 +/- Task Group: "cache" (3 create/destroy update) 126 +/- Task: "redis" (forces create/destroy update) 127 +/- Config { 128 +/- image: "redis:2.8" => "redis:3.2" 129 port_map[0][db]: "6379" 130 } 131 132 Scheduler dry-run: 133 - All tasks successfully allocated. 134 - Rolling update, next evaluation will be in 10s. 135 136 Job Modify Index: 7 137 To submit the job with version verification run: 138 139 nomad job run -check-index 7 example.nomad 140 141 When running the job with the check-index flag, the job will only be run if the 142 server side version matches the job modify index returned. If the index has 143 changed, another user has modified the job and the plan's results are 144 potentially invalid. 145 ``` 146 147 Add a task to the task group using verbose mode: 148 149 ``` 150 $ nomad job plan -verbose example.nomad 151 +/- Job: "example" 152 +/- Task Group: "cache" (3 create/destroy update) 153 + Task: "my-website" (forces create/destroy update) 154 + Driver: "docker" 155 + KillTimeout: "5000000000" 156 + Config { 157 + image: "node:6.2" 158 + port_map[0][web]: "80" 159 } 160 + Resources { 161 + CPU: "500" 162 + DiskMB: "300" 163 + IOPS: "0" 164 + MemoryMB: "256" 165 + Network { 166 + MBits: "10" 167 + Dynamic Port { 168 + Label: "web" 169 } 170 } 171 } 172 + LogConfig { 173 + MaxFileSizeMB: "10" 174 + MaxFiles: "10" 175 } 176 + Service { 177 + Name: "website" 178 + PortLabel: "web" 179 + Check { 180 Command: "" 181 + Interval: "10000000000" 182 + Name: "alive" 183 Path: "" 184 Protocol: "" 185 + Timeout: "2000000000" 186 + Type: "tcp" 187 } 188 } 189 Task: "redis" 190 191 Scheduler dry-run: 192 - All tasks successfully allocated. 193 - Rolling update, next evaluation will be in 10s. 194 195 Job Modify Index: 7 196 To submit the job with version verification run: 197 198 nomad job run -check-index 7 example.nomad 199 200 When running the job with the check-index flag, the job will only be run if the 201 server side version matches the job modify index returned. If the index has 202 changed, another user has modified the job and the plan's results are 203 potentially invalid. 204 ```