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

     1  ---
     2  layout: docs
     3  page_title: 'Commands: job run'
     4  sidebar_title: run
     5  description: |
     6    The job run command is used to run a new job.
     7  ---
     8  
     9  # Command: job run
    10  
    11  **Alias: `nomad run`**
    12  
    13  The `job run` command is used to submit new jobs to Nomad or to update existing
    14  jobs. Job files must conform to the [job specification] format.
    15  
    16  ## Usage
    17  
    18  ```plaintext
    19  nomad job run [options] <job file>
    20  ```
    21  
    22  The `job run` command requires a single argument, specifying the path to a file
    23  containing a valid [job specification]. This file will be read and the job will
    24  be submitted to Nomad for scheduling. If the supplied path is "-", the job file
    25  is read from STDIN. Otherwise it is read from the file at the supplied path or
    26  downloaded and read from URL specified. Nomad downloads the job file using
    27  [`go-getter`] and supports `go-getter` syntax.
    28  
    29  By default, on successful job submission the run command will enter an
    30  interactive monitor and display log information detailing the scheduling
    31  decisions and placement information for the provided job. The monitor will
    32  exit after scheduling has finished or failed.
    33  
    34  On successful job submission and scheduling, exit code 0 will be returned. If
    35  there are job placement issues encountered (unsatisfiable constraints, resource
    36  exhaustion, etc), then the exit code will be 2. Any other errors, including
    37  client connection issues or internal errors, are indicated by exit code 1.
    38  
    39  If the job has specified the region, the `-region` flag and `$NOMAD_REGION`
    40  environment variable are overridden and the job's region is used.
    41  
    42  The run command will set the `consul_token` of the job based on the following
    43  precedence, going from highest to lowest: the `-consul-token` flag, the
    44  `$CONSUL_HTTP_TOKEN` environment variable and finally the value in the job file.
    45  
    46  The run command will set the `vault_token` of the job based on the following
    47  precedence, going from highest to lowest: the `-vault-token` flag, the
    48  `$VAULT_TOKEN` environment variable and finally the value in the job file.
    49  
    50  When ACLs are enabled, this command requires a token with the `submit-job`
    51  capability for the job's namespace. Jobs that mount CSI volumes require a
    52  token with the `csi-mount-volume` capability for the volume's namespace. Jobs
    53  that mount host volumes require a token with the `host_volume` capability for
    54  that volume.
    55  
    56  ## General Options
    57  
    58  @include 'general_options.mdx'
    59  
    60  ## Run Options
    61  
    62  - `-check-index`: If set, the job is only registered or
    63    updated if the passed job modify index matches the server side version.
    64    If a check-index value of zero is passed, the job is only registered if it does
    65    not yet exist. If a non-zero value is passed, it ensures that the job is being
    66    updated from a known state. The use of this flag is most common in conjunction
    67    with [`job plan` command].
    68  
    69  - `-detach`: Return immediately instead of monitoring. A new evaluation ID
    70    will be output, which can be used to examine the evaluation using the
    71    [eval status] command.
    72  
    73  - `-output`: Output the JSON that would be submitted to the HTTP API without
    74    submitting the job.
    75  
    76  - `-policy-override`: Sets the flag to force override any soft mandatory
    77    Sentinel policies.
    78  
    79  - `-preserve-counts`: If set, the existing task group counts will be preserved
    80    when updating a job.
    81  
    82  - `-consul-token`: If set, the passed Consul token is stored in the job before
    83    sending to the Nomad servers. This allows passing the Consul token without
    84    storing it in the job file. This overrides the token found in the
    85    `$CONSUL_HTTP_TOKEN` environment variable and that found in the job.
    86  
    87  - `-vault-token`: If set, the passed Vault token is stored in the job before
    88    sending to the Nomad servers. This allows passing the Vault token without
    89    storing it in the job file. This overrides the token found in the
    90    `$VAULT_TOKEN` environment variable and that found in the job.
    91  
    92  - `-hcl1`: If set, HCL1 parser is used for parsing the job spec.
    93  
    94  - `-verbose`: Show full information.
    95  
    96  ## Examples
    97  
    98  Schedule the job contained in the file `job1.nomad`, monitoring placement:
    99  
   100  ```shell-session
   101  $ nomad job run job1.nomad
   102  ==> Monitoring evaluation "52dee78a"
   103      Evaluation triggered by job "example"
   104      Evaluation within deployment: "62eb607c"
   105      Allocation "5e0b39f0" created: node "3e84d3d2", group "group1"
   106      Allocation "5e0b39f0" status changed: "pending" -> "running"
   107      Evaluation status changed: "pending" -> "complete"
   108  ==> Evaluation "52dee78a" finished with status "complete"
   109  ```
   110  
   111  <a id="check-index"></a> Update the job using `check-index`:
   112  
   113  ```shell-session
   114  $ nomad job run -check-index 5 example.nomad
   115  Enforcing job modify index 5: job exists with conflicting job modify index: 6
   116  Job not updated
   117  
   118  $ nomad job run -check-index 6 example.nomad
   119  ==> Monitoring evaluation "5ef16dff"
   120      Evaluation triggered by job "example"
   121      Evaluation within deployment: "62eb607c"
   122      Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache"
   123      Evaluation status changed: "pending" -> "complete"
   124  ==> Evaluation "5ef16dff" finished with status "complete"
   125  ```
   126  
   127  Schedule the job contained in `job1.nomad` and return immediately:
   128  
   129  ```shell-session
   130  $ nomad job run -detach job1.nomad
   131  Job registration successful
   132  Evaluation ID: e18819c1-b83d-dc17-5e7b-b6f264990283
   133  ```
   134  
   135  Schedule a job which cannot be successfully placed. This results in a scheduling
   136  failure and the specifics of the placement are printed:
   137  
   138  ```shell-session
   139  $ nomad job run failing.nomad
   140  ==> Monitoring evaluation "2ae0e6a5"
   141      Evaluation triggered by job "example"
   142      Evaluation status changed: "pending" -> "complete"
   143  ==> Evaluation "2ae0e6a5" finished with status "complete" but failed to place all allocations:
   144      Task Group "cache" (failed to place 1 allocation):
   145        * Class "foo" filtered 1 nodes
   146        * Constraint "${attr.kernel.name} = linux" filtered 1 nodes
   147      Evaluation "67493a64" waiting for additional capacity to place remainder
   148  ```
   149  
   150  [`go-getter`]: https://github.com/hashicorp/go-getter
   151  [`job plan` command]: /docs/commands/job/plan
   152  [eval status]: /docs/commands/eval-status
   153  [job specification]: /docs/job-specification