Merge pull request #1304 from hashicorp/d-plan-cli

plan cli docs

command/plan.go

@@ -55,10 +55,8 @@ General Options:
 Plan Options:
 
   -diff
-    Defaults to true, but can be toggled off to omit diff output.
+	Determines whether the diff between the remote job and planned job is shown.
-
+	Defaults to true.
-  -no-color
-    Disable colored output.
 
   -verbose
     Increase diff verbosity.

website/source/docs/commands/plan.html.md.erb

@@ -0,0 +1,186 @@
+---
+layout: "docs"
+page_title: "Commands: plan"
+sidebar_current: "docs-commands-plan"
+description: >
+  The plan command is used to dry-run a job update to determine its effects.
+---
+
+# Command: plan
+
+The `plan` command can be used to envoke 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/jobspec/index.html)
+format.
+
+## Usage
+
+```
+nomad plan [options] <file>
+```
+
+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 run
+-check-index`](/docs/commands/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 the job's region is used.
+
+## General Options
+
+<%= general_options_usage %>
+
+## Plan Options
+
+* `-diff`: Determines whether the diff between the remote job and planned job is
+  shown. Defaults to true.
+
+* `-verbose`: Increase diff verbosity.
+
+## Examples
+
+Plan a new job that has not been previously submitted:
+
+```
+$ nomad run job1.nomad
+nomad 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 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 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 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" exhausted on 1 nodes
+
+Job Modify Index: 15
+To submit the job with version verification run:
+
+nomad 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 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 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 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 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 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"
+      + IOPS:     "0"
+      + 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 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 the job modify index returned. If the index has
+changed, another user has modified the job and the plan's results are
+potentially invalid.
+```

website/source/docs/commands/run.html.md.erb

@@ -41,12 +41,12 @@ environment variable are overridden and the the job's region is used.
 
 ## Run Options
 
-* `-check-index`: If set, the job is only registered or updated if the the
+* `-check-index`: If set, the job is only registered or
-  passed job modify index matches the server side version. If a check-index value
+  updated if the the passed job modify index matches the server side version.
-  of zero is passed, the job is only registered if it does not yet exist. If a
+  If a check-index value of zero is passed, the job is only registered if it does
-  non-zero value is passed, it ensures that the job is being updated from a known
+  not yet exist. If a non-zero value is passed, it ensures that the job is being
-  state. The use of this flag is most common in conjunction with [plan
+  updated from a known state. The use of this flag is most common in conjunction
-  command](/docs/commands/plan.html).
+  with [plan command](/docs/commands/plan.html).
 
 * `-detach`: Return immediately instead of monitoring. A new evaluation ID
   will be output, which can be used to examine the evaluation using the
@@ -72,7 +72,8 @@ $ nomad run job1.nomad
 ==> Evaluation "52dee78a" finished with status "complete"
 ```
 
-Update the job using check-index:
+<a id="check-index"></a> Update the job using `check-index`:
+
 ```
 $ nomad run -check-index 5 example.nomad
 Enforcing job modify index 5: job exists with conflicting job modify index: 6

website/source/layouts/docs.erb

@@ -135,6 +135,9 @@
 						<li<%= sidebar_current("docs-commands-node-status") %>>
 							<a href="/docs/commands/node-status.html">node-status</a>
 						</li>
+						<li<%= sidebar_current("docs-commands-plan") %>>
+							<a href="/docs/commands/plan.html">plan</a>
+						</li>
 						<li<%= sidebar_current("docs-commands-run") %>>
 							<a href="/docs/commands/run.html">run</a>
 						</li>