Dispatch command

command/job_dispatch.go

@@ -32,6 +32,12 @@ General Options:
 
 Dispatch Options:
 
+  -meta <key>=<value>
+    Meta takes a key/value pair seperated by "=". The metadata key will be
+    injected into the job's metadata. The flag can be provided more than
+    once to inject multiple metadata key/value pairs. Arbitrary injection is not
+    allowed. The parameterized job must allow the key to be injected.
+    
   -detach
     Return immediately instead of entering monitor mode. After job dispatch,
     the evaluation ID will be printed to the screen, which can be used to

website/source/docs/commands/job-dispatch.html.md.erb

@@ -0,0 +1,106 @@
+---
+layout: "docs"
+page_title: "Commands: job dispatch"
+sidebar_current: "docs-commands-job-dispatch"
+description: >
+  The dispatch command is used to create an instance of a parameterized job.
+---
+
+# Command: job dispatch
+
+~> The [`job dispatch`](/docs/commands/snapshot/agent.html) subcommand described here is
+   available only in version 0.5.3 and later. The release canidate is
+   downloadable on the [releases
+   page.](https://releases.hashicorp.com/nomad/0.5.3-rc1/)
+
+The `job dispatch` command is used to create new instances of a [parameterized
+job](TODO). The parameterized job captures a job's configuration and runtime
+requirements in a generic way and `dispatch` is used to provide the input for
+the job to run against. One can think of the parameterized job as a function
+definition and dispatch is used to invoke the function.
+
+## Usage
+
+```
+nomad job dispatch [options] <parameterized job> [input source]
+```
+
+Dispatch creates an instance of a parameterized job. A data payload to the
+dispatched instance can be provided via stdin by using "-" for the input source
+or by specifiying a path to a file. Metadata can be supplied by using the meta
+flag one or more times.
+
+Upon successfully creation, the dispatched job ID will be printed and the
+triggered evaluation will be monitored. This can be disabled by supplying the
+detach flag.
+
+On successful job submission and scheduling, exit code 0 will be returned. If
+there are job placement issues encountered (unsatisfiable constraints, resource
+exhaustion, etc), then the exit code will be 2. Any other errors, including
+client connection issues or internal errors, are indicated by exit code 1.
+
+## General Options
+
+<%= partial "docs/commands/_general_options" %>
+
+## Run Options
+
+* `-meta`: Meta takes a key/value pair seperated by "=". The metadata key will
+  be injected into the job's metadata. The flag can be provided more than once
+  to inject multiple metadata key/value pairs. Arbitrary injection is not
+  allowed. The parameterized job must allow the key to be injected.
+
+* `-detach`: Return immediately instead of monitoring. A new evaluation ID
+  will be output, which can be used to examine the evaluation using the
+  [eval-status](/docs/commands/eval-status.html) command
+
+* `-verbose`: Show full information.
+
+## Examples
+
+Dispatch against a parameterized job with the ID "video-encode" and
+passing in a configuration payload via stdin:
+
+```
+$ cat << EOF | nomad job dispatch video-encode -
+{
+  "s3-input": "https://s3-us-west-1.amazonaws.com/video-bucket/cb31dabb1",
+  "s3-output": "https://s3-us-west-1.amazonaws.com/video-bucket/a149adbe3",
+  "input-codec": "mp4",
+  "output-codec": "webm",
+  "quality": "1080p"
+}
+EOF
+Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
+Evaluation ID     = 31199841
+
+==> Monitoring evaluation "31199841"
+    Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
+    Allocation "8254b85f" created: node "82ff9c50", group "cache"
+    Evaluation status changed: "pending" -> "complete"
+==> Evaluation "31199841" finished with status "complete"
+```
+
+Dispatch against a parameterized job with the ID "video-encode" and
+passing in a configuration payload via a file:
+
+```
+$ nomad job dispatch video-encode video-config.json
+Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
+Evaluation ID     = 31199841
+
+==> Monitoring evaluation "31199841"
+    Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
+    Allocation "8254b85f" created: node "82ff9c50", group "cache"
+    Evaluation status changed: "pending" -> "complete"
+==> Evaluation "31199841" finished with status "complete"
+```
+
+Dispatch against a parameterized job with the ID "video-encode" using the detach
+flag:
+
+```
+$ nomad job dispatch -detach video-encode video-config.json
+Dispatched Job ID = example/dispatch-1485380684-c37b3dba
+Evaluation ID     = d9034c4e
+```

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

@@ -152,3 +152,5 @@ b82f58b6  8bf94335  8d0331e9  cache       run      running  08/08/16 21:03:19 CD
 ed3665f5  8bf94335  8d0331e9  cache       run      running  08/08/16 21:03:19 CDT
 24cfd201  8bf94335  8d0331e9  cache       run      running  08/08/16 21:03:19 CDT
 ```
+
+TODO: CRON AND DISPATCH

website/source/layouts/docs.erb

@@ -204,6 +204,9 @@
             <li<%= sidebar_current("docs-commands-inspect") %>>
               <a href="/docs/commands/inspect.html">inspect</a>
             </li>
+            <li<%= sidebar_current("docs-commands-job-dispatch") %>>
+              <a href="/docs/commands/job-dispatch.html">job dispatch</a>
+            </li>
             <li<%= sidebar_current("docs-commands-keygen") %>>
               <a href="/docs/commands/keygen.html">keygen</a>
             </li>