1aceff7806
Most job subcommands allow for job ID prefix match as a convenience functionality so users don't have to type the full job ID. But this introduces a hard ACL requirement that the token used to run these commands have the `list-jobs` permission, even if the token has enough permission to execute the basic command action and the user passed an exact job ID. This change softens this requirement by not failing the prefix match in case the request results in a permission denied error and instead using the information passed by the user directly.
168 lines
6.2 KiB
Plaintext
168 lines
6.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Commands: job dispatch'
|
|
description: |
|
|
The dispatch command is used to create an instance of a parameterized job.
|
|
---
|
|
|
|
# Command: job dispatch
|
|
|
|
The `job dispatch` command is used to create new instances of a [parameterized
|
|
job]. 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. A parameterized job is similar to a function definition,
|
|
and dispatch is used to invoke the function.
|
|
|
|
Each time a job is dispatched, a unique job ID is generated. This allows a
|
|
caller to track the status of the job, much like a future or promise in some
|
|
programming languages.
|
|
|
|
## Usage
|
|
|
|
```plaintext
|
|
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 specifying a path to a file. Metadata can be supplied by using the meta
|
|
flag one or more times.
|
|
|
|
The payload has a **size limit of 16384 bytes (16KiB)**.
|
|
|
|
An optional idempotency token can be specified to prevent dispatching more than
|
|
one instance of the same job. The token can have any value and will be matched
|
|
with existing jobs. If an instance with the same token already exists, the job
|
|
will not be dispatched.
|
|
|
|
Upon successful 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.
|
|
|
|
When ACLs are enabled, this command requires a token with the `dispatch-job`
|
|
capability for the job's namespace. The `list-jobs` capability is required to
|
|
run the command with a job prefix instead of the exact job ID. The `read-job`
|
|
capability is required to monitor the resulting evaluation when `-detach` is
|
|
not used.
|
|
|
|
See the [multiregion] documentation for additional considerations when
|
|
dispatching parameterized jobs.
|
|
|
|
## General Options
|
|
|
|
@include 'general_options.mdx'
|
|
|
|
## Dispatch Options
|
|
|
|
- `-meta`: Meta takes a key/value pair separated by "=". The metadata key will
|
|
be merged into the job's metadata. The job may define a default value for the
|
|
key which is overridden when dispatching. The flag can be provided more than
|
|
once to inject multiple metadata key/value pairs. Arbitrary keys are not
|
|
allowed. The parameterized job must allow the key to be merged.
|
|
|
|
- `-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] command
|
|
|
|
- `-idempotency-token`: Optional identifier used to prevent more than one
|
|
instance of the job from being dispatched.
|
|
|
|
|
|
- `-id-prefix-template`: Optional prefix template for dispatched job IDs.
|
|
|
|
- `-verbose`: Show full information.
|
|
|
|
## Examples
|
|
|
|
Dispatch against a parameterized job with the ID "video-encode" and
|
|
passing in a configuration payload via stdin:
|
|
|
|
```shell-session
|
|
$ cat << EOF | nomad job dispatch video-encode -
|
|
{
|
|
"s3-input": "https://video-bucket.s3-us-west-1.amazonaws.com/cb31dabb1",
|
|
"s3-output": "https://video-bucket.s3-us-west-1.amazonaws.com/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:
|
|
|
|
```shell-session
|
|
$ 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:
|
|
|
|
```shell-session
|
|
$ nomad job dispatch -detach video-encode video-config.json
|
|
Dispatched Job ID = example/dispatch-1485380684-c37b3dba
|
|
Evaluation ID = d9034c4e
|
|
```
|
|
|
|
Dispatch with an idempotency token for the first time:
|
|
|
|
```shell-session
|
|
$ nomad job dispatch -idempotency-token=prod 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 with the same idempotency token:
|
|
|
|
```shell-session
|
|
$ nomad job dispatch -idempotency-token=prod video-encode video-config.json
|
|
Job "video-encode/dispatch-1485379325-cb38d00d" already dispatched with idempotency token "prod".
|
|
```
|
|
|
|
Dispatch with an id prefix:
|
|
|
|
```shell-session
|
|
$ nomad job dispatch -id-prefix-template=config1 video-encode video-config1.json
|
|
Jb
|
|
Dispatched Job ID = video-encode/dispatch-config1-1485379325-cb38d00d
|
|
Evaluation ID = 31199841
|
|
|
|
==> Monitoring evaluation "31199841"
|
|
Evaluation triggered by job "example/dispatch-config1-1485379325-cb38d00d"
|
|
Allocation "8254b85f" created: node "82ff9c50", group "cache"
|
|
Evaluation status changed: "pending" -> "complete"
|
|
==> Evaluation "31199841" finished with status "complete"
|
|
```
|
|
|
|
[eval status]: /nomad/docs/commands/eval/status
|
|
[parameterized job]: /nomad/docs/job-specification/parameterized 'Nomad parameterized Job Specification'
|
|
[multiregion]: /nomad/docs/job-specification/multiregion#parameterized-dispatch
|