github.com/smintz/nomad@v0.8.3/website/source/guides/operating-a-job/submitting-jobs.html.md (about)

     1  ---
     2  layout: "guides"
     3  page_title: "Submitting Jobs - Operating a Job"
     4  sidebar_current: "guides-operating-a-job-submitting-jobs"
     5  description: |-
     6    The job file is the unit of work in Nomad. Upon authoring, the job file is
     7    submitted to the server for evaluation and scheduling. This section discusses
     8    some techniques for submitting jobs.
     9  ---
    10  
    11  # Submitting Jobs
    12  
    13  In Nomad, the description of the job and all its requirements are maintained in
    14  a single file called the "job file". This job file resides locally on disk and
    15  it is highly recommended that you check job files into source control.
    16  
    17  The general flow for submitting a job in Nomad is:
    18  
    19  1. Author a job file according to the job specification
    20  1. Plan and review changes with a Nomad server
    21  1. Submit the job file to a Nomad server
    22  1. (Optional) Review job status and logs
    23  
    24  Here is a very basic example to get you started.
    25  
    26  ## Author a Job File
    27  
    28  Authoring a job file is very easy. For more detailed information, please see the
    29  [job specification](/docs/job-specification/index.html). Here is a sample job
    30  file which runs a small docker container web server to get us started.
    31  
    32  ```hcl
    33  job "docs" {
    34    datacenters = ["dc1"]
    35  
    36    group "example" {
    37      task "server" {
    38        driver = "docker"
    39  
    40        config {
    41          image = "hashicorp/http-echo"
    42          args = [
    43            "-listen", ":5678",
    44            "-text", "hello world",
    45          ]
    46        }
    47  
    48        resources {
    49          network {
    50            mbits = 10
    51            port "http" {
    52              static = "5678"
    53            }
    54          }
    55        }
    56      }
    57    }
    58  }
    59  ```
    60  
    61  This job file exists on your local workstation in plain text. When you are
    62  satisfied with this job file, you will plan and review the scheduler decision.
    63  It is generally a best practice to commit job files to source control,
    64  especially if you are working in a team.
    65  
    66  ## Planning the Job
    67  
    68  Once the job file is authored, we need to plan out the changes. The `nomad job plan`
    69  command invokes a dry-run of the scheduler and inform us of which scheduling
    70  decisions would take place.
    71  
    72  ```text
    73  $ nomad job plan docs.nomad
    74  + Job: "docs"
    75  + Task Group: "example" (1 create)
    76    + Task: "server" (forces create)
    77  
    78  Scheduler dry-run:
    79  - All tasks successfully allocated.
    80  
    81  Job Modify Index: 0
    82  To submit the job with version verification run:
    83  
    84  nomad job run -check-index 0 docs.nomad
    85  
    86  When running the job with the check-index flag, the job will only be run if the
    87  server side version matches the job modify index returned. If the index has
    88  changed, another user has modified the job and the plan's results are
    89  potentially invalid.
    90  ```
    91  
    92  Note that no action was taken. This job is not running. This is a complete
    93  dry-run and no allocations have taken place.
    94  
    95  ## Submitting the Job
    96  
    97  Assuming the output of the plan looks acceptable, we can ask Nomad to execute
    98  this job. This is done via the `nomad job run` command. We can optionally supply
    99  the modify index provided to us by the plan command to ensure no changes to this
   100  job have taken place between our plan and now.
   101  
   102  ```text
   103  $ nomad job run docs.nomad
   104  ==> Monitoring evaluation "0d159869"
   105      Evaluation triggered by job "docs"
   106      Allocation "5cbf23a1" created: node "1e1aa1e0", group "example"
   107      Evaluation status changed: "pending" -> "complete"
   108  ==> Evaluation "0d159869" finished with status "complete"
   109  ```
   110  
   111  Now that the job is scheduled, it may or may not be running. We need to inspect
   112  the allocation status and logs to make sure the job started correctly. The next
   113  section on [inspecting state](/guides/operating-a-job/inspecting-state.html)
   114  details ways to examine this job's state.
   115  
   116  ## Updating the Job
   117  
   118  When making updates to the job, it is best to always run the plan command and
   119  then the run command. For example:
   120  
   121  ```diff
   122  @@ -2,6 +2,8 @@ job "docs" {
   123     datacenters = ["dc1"]
   124  
   125     group "example" {
   126  +    count = "3"
   127  +
   128       task "server" {
   129         driver = "docker"
   130  ```
   131  
   132  After we save these changes to disk, run the plan command:
   133  
   134  ```text
   135  $ nomad job plan docs.nomad
   136  +/- Job: "docs"
   137  +/- Task Group: "example" (2 create, 1 in-place update)
   138    +/- Count: "1" => "3" (forces create)
   139        Task: "server"
   140  
   141  Scheduler dry-run:
   142  - All tasks successfully allocated.
   143  
   144  Job Modify Index: 131
   145  To submit the job with version verification run:
   146  
   147  nomad job run -check-index 131 docs.nomad
   148  
   149  When running the job with the check-index flag, the job will only be run if the
   150  server side version matches the job modify index returned. If the index has
   151  changed, another user has modified the job and the plan's results are
   152  potentially invalid.
   153  ```
   154  
   155  And then run the run command, assuming the output looks okay. Note that we are
   156  including the "check-index" parameter. This will ensure that no remote changes
   157  have taken place to the job between our plan and run phases.
   158  
   159  ```text
   160  nomad job run -check-index 131 docs.nomad
   161  ==> Monitoring evaluation "42d788a3"
   162      Evaluation triggered by job "docs"
   163      Allocation "04d9627d" created: node "a1f934c9", group "example"
   164      Allocation "e7b8d4f5" created: node "012ea79b", group "example"
   165      Allocation "5cbf23a1" modified: node "1e1aa1e0", group "example"
   166      Evaluation status changed: "pending" -> "complete"
   167  ==> Evaluation "42d788a3" finished with status "complete"
   168  ```
   169  
   170  For more details on advanced job updating strategies such as canary builds and
   171  build-green deployments, please see the documentation on [job update
   172  strategies](/guides/operating-a-job/update-strategies/index.html).