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