github.com/diptanu/nomad@v0.5.7-0.20170516172507-d72e86cbe3d9/website/source/docs/commands/run.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: run"
     4  sidebar_current: "docs-commands-run"
     5  description: >
     6    The run command is used to run a new job.
     7  ---
     8  
     9  # Command: run
    10  
    11  The `run` command is used to submit new jobs to Nomad or to update existing
    12  jobs. Job files must conform to the [job specification](/docs/job-specification/index.html)
    13  format.
    14  
    15  ## Usage
    16  
    17  ```
    18  nomad run [options] <job file>
    19  ```
    20  
    21  The run command requires a single argument, specifying the path to a file
    22  containing a valid [job specification](/docs/job-specification/index.html). This file
    23  will be read and the job will be submitted to Nomad for scheduling. If the
    24  supplied path is "-", the job file is read from STDIN. Otherwise it is read
    25  from the file at the supplied path or downloaded and read from URL specified.
    26  Nomad downloads the job file using [`go-getter`](https://github.com/hashicorp/go-getter)
    27  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 `vault_token` of the job based on the following
    43  precedence, going from highest to lowest: the `-vault-token` flag, the
    44  `$VAULT_TOKEN` environment variable and finally the value in the job file.
    45  
    46  ## General Options
    47  
    48  <%= partial "docs/commands/_general_options" %>
    49  
    50  ## Run Options
    51  
    52  * `-check-index`: If set, the job is only registered or
    53    updated if the passed job modify index matches the server side version.
    54    If a check-index value of zero is passed, the job is only registered if it does
    55    not yet exist. If a non-zero value is passed, it ensures that the job is being
    56    updated from a known state. The use of this flag is most common in conjunction
    57    with [plan command](/docs/commands/plan.html).
    58  
    59  * `-detach`: Return immediately instead of monitoring. A new evaluation ID
    60    will be output, which can be used to examine the evaluation using the
    61    [eval-status](/docs/commands/eval-status.html) command
    62  
    63  * `-vault-token`: If set, the passed Vault token is stored in the job before
    64    sending to the Nomad servers. This allows passing the Vault token without
    65    storing it in the job file. This overrides the token found in $VAULT_TOKEN
    66    environment variable and that found in the job.
    67  
    68  * `-output`: Output the JSON that would be submitted to the HTTP API without
    69    submitting the job.
    70  
    71  ## Status Options
    72  
    73  * `-verbose`: Show full information.
    74  
    75  ## Examples
    76  
    77  Schedule the job contained in the file `job1.nomad`, monitoring placement:
    78  
    79  ```
    80  $ nomad run job1.nomad
    81  ==> Monitoring evaluation "52dee78a"
    82      Allocation "5e0b39f0" created: node "3e84d3d2", group "group1"
    83      Allocation "5e0b39f0" status changed: "pending" -> "running"
    84      Evaluation status changed: "pending" -> "complete"
    85  ==> Evaluation "52dee78a" finished with status "complete"
    86  ```
    87  
    88  <a id="check-index"></a> Update the job using `check-index`:
    89  
    90  ```
    91  $ nomad run -check-index 5 example.nomad
    92  Enforcing job modify index 5: job exists with conflicting job modify index: 6
    93  Job not updated
    94  
    95  $ nomad run -check-index 6 example.nomad
    96  ==> Monitoring evaluation "5ef16dff"
    97      Evaluation triggered by job "example"
    98      Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache"
    99      Evaluation status changed: "pending" -> "complete"
   100  ==> Evaluation "5ef16dff" finished with status "complete"
   101  ```
   102  
   103  Schedule the job contained in `job1.nomad` and return immediately:
   104  
   105  ```
   106  $ nomad run -detach job1.nomad
   107  4947e728
   108  ```
   109  
   110  Schedule a job which cannot be successfully placed. This results in a scheduling
   111  failure and the specifics of the placement are printed:
   112  
   113  ```
   114  $ nomad run failing.nomad
   115  ==> Monitoring evaluation "2ae0e6a5"
   116      Evaluation triggered by job "example"
   117      Evaluation status changed: "pending" -> "complete"
   118  ==> Evaluation "2ae0e6a5" finished with status "complete" but failed to place all allocations:
   119      Task Group "cache" (failed to place 1 allocation):
   120        * Class "foo" filtered 1 nodes
   121        * Constraint "${attr.kernel.name} = linux" filtered 1 nodes
   122      Evaluation "67493a64" waiting for additional capacity to place remainder
   123  ```