github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/commands/job/dispatch.mdx (about)

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