mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
35e1ea4328
* Basic implementation for server members and node status * Commands for alloc status and job status * -ui flag for most commands * url hints for variables * url hints for job dispatch, evals, and deployments * agent config ui.cli_url_links to disable * Fix an issue where path prefix was presumed for variables * driver uncomment and general cleanup * -ui flag on the generic status endpoint * Job run command gets namespaces, and no longer gets ui hints for --output flag * Dispatch command hints get a namespace, and bunch o tests * Lots of tests depend on specific output, so let's not mess with them * figured out what flagAddress is all about for testServer, oof * Parallel outside of test instances * Browser-opening test, sorta * Env var for disabling/enabling CLI hints * Addressing a few PR comments * CLI docs available flags now all have -ui * PR comments addressed; switched the env var to be consistent and scrunched monitor-adjacent hints a bit more * ui.Output -> ui.Warn; moves hints from stdout to stderr * isTerminal check and parseBool on command option * terminal.IsTerminal check removed for test-runner-not-being-terminal reasons
169 lines
6.2 KiB
Plaintext
169 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 added to dispatched job IDs.
|
|
|
|
- `-verbose`: Show full information.
|
|
|
|
- `-ui`: Open the dispatched job in the browser.
|
|
|
|
## 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
|