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).