Products
»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
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.
See the multiregion documentation for additional considerations when dispatching parameterized jobs.
General Options
-address=<addr>: The address of the Nomad server. Overrides theNOMAD_ADDRenvironment variable if set. Defaults tohttp://127.0.0.1:4646.-region=<region>: The region of the Nomad server to forward commands to. Overrides theNOMAD_REGIONenvironment variable if set. Defaults to the Agent's local region.-namespace=<namespace>: The target namespace for queries and actions bound to a namespace. Overrides theNOMAD_NAMESPACEenvironment variable if set. If set to'*', job and alloc subcommands query all namespaces authorized to user. Defaults to the "default" namespace.-no-color: Disables colored command output. Alternatively,NOMAD_CLI_NO_COLORmay be set. This option takes precedence over-force-color.-force-color: Forces colored command output. This can be used in cases where the usual terminal detection fails. Alternatively,NOMAD_CLI_FORCE_COLORmay be set. This option has no effect if-no-coloris also used.-ca-cert=<path>: Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. Overrides theNOMAD_CACERTenvironment variable if set.-ca-path=<path>: Path to a directory of PEM encoded CA cert files to verify the Nomad server SSL certificate. If both-ca-certand-ca-pathare specified,-ca-certis used. Overrides theNOMAD_CAPATHenvironment variable if set.-client-cert=<path>: Path to a PEM encoded client certificate for TLS authentication to the Nomad server. Must also specify-client-key. Overrides theNOMAD_CLIENT_CERTenvironment variable if set.-client-key=<path>: Path to an unencrypted PEM encoded private key matching the client certificate from-client-cert. Overrides theNOMAD_CLIENT_KEYenvironment variable if set.-tls-server-name=<value>: The server name to use as the SNI host when connecting via TLS. Overrides theNOMAD_TLS_SERVER_NAMEenvironment variable if set.-tls-skip-verify: Do not verify TLS certificate. This is highly not recommended. Verification will also be skipped ifNOMAD_SKIP_VERIFYis set.-token: The SecretID of an ACL token to use to authenticate API requests with. Overrides theNOMAD_TOKENenvironment variable if set.
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:
Dispatch against a parameterized job with the ID "video-encode" and passing in a configuration payload via a file:
Dispatch against a parameterized job with the ID "video-encode" using the detach flag:
Dispatch with an idempotency token for the first time:
Dispatch with the same idempotency token:
Dispatch with an id prefix: