github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/commands/job/dispatch.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Commands: job dispatch'
     4  description: |
     5    The dispatch command is used to create an instance of a parameterized job.
     6  ---
     7  
     8  # Command: job dispatch
     9  
    10  The `job dispatch` command is used to create new instances of a [parameterized
    11  job]. The parameterized job captures a job's configuration and runtime
    12  requirements in a generic way and `dispatch` is used to provide the input for
    13  the job to run against. A parameterized job is similar to a function definition,
    14  and dispatch is used to invoke the function.
    15  
    16  Each time a job is dispatched, a unique job ID is generated. This allows a
    17  caller to track the status of the job, much like a future or promise in some
    18  programming languages.
    19  
    20  ## Usage
    21  
    22  ```plaintext
    23  nomad job dispatch [options] <parameterized job> [input source]
    24  ```
    25  
    26  Dispatch creates an instance of a parameterized job. A data payload to the
    27  dispatched instance can be provided via stdin by using "-" for the input source
    28  or by specifying a path to a file. Metadata can be supplied by using the meta
    29  flag one or more times.
    30  
    31  The payload has a **size limit of 16384 bytes (16KiB)**.
    32  
    33  An optional idempotency token can be specified to prevent dispatching more than
    34  one instance of the same job. The token can have any value and will be matched
    35  with existing jobs. If an instance with the same token already exists, the job
    36  will not be dispatched.
    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  When ACLs are enabled, this command requires a token with the `dispatch-job`
    48  capability for the job's namespace.
    49  
    50  See the [multiregion] documentation for additional considerations when
    51  dispatching parameterized jobs.
    52  
    53  ## General Options
    54  
    55  @include 'general_options.mdx'
    56  
    57  ## Dispatch Options
    58  
    59  - `-meta`: Meta takes a key/value pair separated by "=". The metadata key will
    60    be merged into the job's metadata. The job may define a default value for the
    61    key which is overridden when dispatching. The flag can be provided more than
    62    once to inject multiple metadata key/value pairs. Arbitrary keys are not
    63    allowed. The parameterized job must allow the key to be merged.
    64  
    65  - `-detach`: Return immediately instead of monitoring. A new evaluation ID
    66    will be output, which can be used to examine the evaluation using the
    67    [eval status] command
    68  
    69  - `-idempotency-token`: Optional identifier used to prevent more than one
    70    instance of the job from being dispatched.
    71  
    72  
    73  - `-id-prefix-template`: Optional prefix template for dispatched job IDs.
    74  
    75  - `-verbose`: Show full information.
    76  
    77  ## Examples
    78  
    79  Dispatch against a parameterized job with the ID "video-encode" and
    80  passing in a configuration payload via stdin:
    81  
    82  ```shell-session
    83  $ cat << EOF | nomad job dispatch video-encode -
    84  {
    85    "s3-input": "https://video-bucket.s3-us-west-1.amazonaws.com/cb31dabb1",
    86    "s3-output": "https://video-bucket.s3-us-west-1.amazonaws.com/a149adbe3",
    87    "input-codec": "mp4",
    88    "output-codec": "webm",
    89    "quality": "1080p"
    90  }
    91  EOF
    92  Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
    93  Evaluation ID     = 31199841
    94  
    95  ==> Monitoring evaluation "31199841"
    96      Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
    97      Allocation "8254b85f" created: node "82ff9c50", group "cache"
    98      Evaluation status changed: "pending" -> "complete"
    99  ==> Evaluation "31199841" finished with status "complete"
   100  ```
   101  
   102  Dispatch against a parameterized job with the ID "video-encode" and
   103  passing in a configuration payload via a file:
   104  
   105  ```shell-session
   106  $ nomad job dispatch video-encode video-config.json
   107  Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
   108  Evaluation ID     = 31199841
   109  
   110  ==> Monitoring evaluation "31199841"
   111      Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
   112      Allocation "8254b85f" created: node "82ff9c50", group "cache"
   113      Evaluation status changed: "pending" -> "complete"
   114  ==> Evaluation "31199841" finished with status "complete"
   115  ```
   116  
   117  Dispatch against a parameterized job with the ID "video-encode" using the detach
   118  flag:
   119  
   120  ```shell-session
   121  $ nomad job dispatch -detach video-encode video-config.json
   122  Dispatched Job ID = example/dispatch-1485380684-c37b3dba
   123  Evaluation ID     = d9034c4e
   124  ```
   125  
   126  Dispatch with an idempotency token for the first time:
   127  
   128  ```shell-session
   129  $ nomad job dispatch -idempotency-token=prod video-encode video-config.json
   130  Dispatched Job ID = video-encode/dispatch-1485379325-cb38d00d
   131  Evaluation ID     = 31199841
   132  
   133  ==> Monitoring evaluation "31199841"
   134      Evaluation triggered by job "example/dispatch-1485379325-cb38d00d"
   135      Allocation "8254b85f" created: node "82ff9c50", group "cache"
   136      Evaluation status changed: "pending" -> "complete"
   137  ==> Evaluation "31199841" finished with status "complete"
   138  ```
   139  
   140  Dispatch with the same idempotency token:
   141  
   142  ```shell-session
   143  $ nomad job dispatch -idempotency-token=prod video-encode video-config.json
   144  Job "video-encode/dispatch-1485379325-cb38d00d" already dispatched with idempotency token "prod".
   145  ```
   146  
   147  Dispatch with an id prefix:
   148  
   149  ```shell-session
   150  $ nomad job dispatch -id-prefix-template=config1 video-encode video-config1.json
   151  Jb
   152  Dispatched Job ID = video-encode/dispatch-config1-1485379325-cb38d00d
   153  Evaluation ID     = 31199841
   154  
   155  ==> Monitoring evaluation "31199841"
   156      Evaluation triggered by job "example/dispatch-config1-1485379325-cb38d00d"
   157      Allocation "8254b85f" created: node "82ff9c50", group "cache"
   158      Evaluation status changed: "pending" -> "complete"
   159  ==> Evaluation "31199841" finished with status "complete"
   160  ```
   161  
   162  [eval status]: /docs/commands/eval/status
   163  [parameterized job]: /docs/job-specification/parameterized 'Nomad parameterized Job Specification'
   164  [multiregion]: /docs/job-specification/multiregion#parameterized-dispatch