github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/website/source/docs/commands/job-dispatch.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: job dispatch"
     4  sidebar_current: "docs-commands-job-dispatch"
     5  description: >
     6    The dispatch command is used to create an instance of a parameterized job.
     7  ---
     8  
     9  # Command: job dispatch
    10  
    11  ~> The `job dispatch` subcommand described here is available only in version
    12  0.5.3 and later. The release canidate is downloadable on the [releases
    13  page.](https://releases.hashicorp.com/nomad/0.5.3-rc1/)
    14  
    15  The `job dispatch` command is used to create new instances of a [parameterized
    16  job]. The parameterized job captures a job's configuration and runtime
    17  requirements in a generic way and `dispatch` is used to provide the input for
    18  the job to run against. A parameterized job is similar to a function definition,
    19  and dispatch is used to invoke the function.
    20  
    21  Each time a job is dispatched, a unique job ID is generated. This allows a
    22  caller to track the status of the job, much like a future or promise in some
    23  programming languages.
    24  
    25  ## Usage
    26  
    27  ```
    28  nomad job dispatch [options] <parameterized job> [input source]
    29  ```
    30  
    31  Dispatch creates an instance of a parameterized job. A data payload to the
    32  dispatched instance can be provided via stdin by using "-" for the input source
    33  or by specifiying a path to a file. Metadata can be supplied by using the meta
    34  flag one or more times.
    35  
    36  The payload has a **size limit of 16KiB**.
    37  
    38  Upon successful creation, the dispatched job ID will be printed and the
    39  triggered evaluation will be monitored. This can be disabled by supplying the
    40  detach flag.
    41  
    42  On successful job submission and scheduling, exit code 0 will be returned. If
    43  there are job placement issues encountered (unsatisfiable constraints, resource
    44  exhaustion, etc), then the exit code will be 2. Any other errors, including
    45  client connection issues or internal errors, are indicated by exit code 1.
    46  
    47  ## General Options
    48  
    49  <%= partial "docs/commands/_general_options" %>
    50  
    51  ## Run Options
    52  
    53  * `-meta`: Meta takes a key/value pair seperated by "=". The metadata key will
    54    be merged into the job's metadata. The job may define a default value for the
    55    key which is overriden when dispatching. The flag can be provided more than
    56    once to inject multiple metadata key/value pairs. Arbitrary keys are not
    57    allowed. The parameterized job must allow the key to be merged.
    58  
    59  * `-detach`: Return immediately instead of monitoring. A new evaluation ID
    60    will be output, which can be used to examine the evaluation using the
    61    [eval-status](/docs/commands/eval-status.html) command
    62  
    63  * `-verbose`: Show full information.
    64  
    65  ## Examples
    66  
    67  Dispatch against a parameterized job with the ID "video-encode" and
    68  passing in a configuration payload via stdin:
    69  
    70  ```
    71  $ cat << EOF | nomad job dispatch video-encode -
    72  {
    73    "s3-input": "https://s3-us-west-1.amazonaws.com/video-bucket/cb31dabb1",
    74    "s3-output": "https://s3-us-west-1.amazonaws.com/video-bucket/a149adbe3",
    75    "input-codec": "mp4",
    76    "output-codec": "webm",
    77    "quality": "1080p"
    78  }
    79  EOF
    80  Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
    81  Evaluation ID     = 31199841
    82  
    83  ==> Monitoring evaluation "31199841"
    84      Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
    85      Allocation "8254b85f" created: node "82ff9c50", group "cache"
    86      Evaluation status changed: "pending" -> "complete"
    87  ==> Evaluation "31199841" finished with status "complete"
    88  ```
    89  
    90  Dispatch against a parameterized job with the ID "video-encode" and
    91  passing in a configuration payload via a file:
    92  
    93  ```
    94  $ nomad job dispatch video-encode video-config.json
    95  Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
    96  Evaluation ID     = 31199841
    97  
    98  ==> Monitoring evaluation "31199841"
    99      Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
   100      Allocation "8254b85f" created: node "82ff9c50", group "cache"
   101      Evaluation status changed: "pending" -> "complete"
   102  ==> Evaluation "31199841" finished with status "complete"
   103  ```
   104  
   105  Dispatch against a parameterized job with the ID "video-encode" using the detach
   106  flag:
   107  
   108  ```
   109  $ nomad job dispatch -detach video-encode video-config.json
   110  Dispatched Job ID = example/dispatch-1485380684-c37b3dba
   111  Evaluation ID     = d9034c4e
   112  ```
   113  
   114  [parameterized job]: /docs/job-specification/parameterized.html "Nomad parameterized Job Specification"