github.com/ranjib/nomad@v0.1.1-0.20160225204057-97751b02f70b/website/source/intro/getting-started/jobs.html.md (about) 1 --- 2 layout: "intro" 3 page_title: "Jobs" 4 sidebar_current: "getting-started-jobs" 5 description: |- 6 Learn how to submit, modify and stop jobs in Nomad. 7 --- 8 9 # Jobs 10 11 Jobs are the primary configuration that users interact with when using 12 Nomad. A job is a declarative specification of tasks that Nomad should run. 13 Jobs have a globally unique name, one or many task groups, which are themselves 14 collections of one or many tasks. 15 16 The format of the jobs is [documented here](/docs/jobspec/index.html). They 17 can either be specified in [HCL](https://github.com/hashicorp/hcl) or JSON, 18 however we recommend only using JSON when the configuration is generated by a machine. 19 20 ## Running a Job 21 22 To get started, we will use the [`init` command](/docs/commands/init.html) which 23 generates a skeleton job file: 24 25 ``` 26 $ nomad init 27 Example job file written to example.nomad 28 29 $ cat example.nomad 30 31 # There can only be a single job definition per file. 32 # Create a job with ID and Name 'example' 33 job "example" { 34 # Run the job in the global region, which is the default. 35 # region = "global" 36 ... 37 ``` 38 39 In this example job file, we have declared a single task 'redis' which is using 40 the Docker driver to run the task. The primary way you interact with Nomad 41 is with the [`run` command](/docs/commands/run.html). The `run` command takes 42 a job file and registers it with Nomad. This is used both to register new 43 jobs and to update existing jobs. 44 45 We can register our example job now: 46 47 ``` 48 $ nomad run example.nomad 49 ==> Monitoring evaluation "26cfc69e" 50 Evaluation triggered by job "example" 51 Allocation "8ba85cef" created: node "171a583b", group "cache" 52 Evaluation status changed: "pending" -> "complete" 53 ==> Evaluation "26cfc69e" finished with status "complete" 54 ``` 55 56 Anytime a job is updated, Nomad creates an evaluation to determine what 57 actions need to take place. In this case, because this is a new job, Nomad has 58 determined that an allocation should be created and has scheduled it on our 59 local agent. 60 61 To inspect the status of our job we use the [`status` command](/docs/commands/status.html): 62 63 ``` 64 $ nomad status example 65 ID = example 66 Name = example 67 Type = service 68 Priority = 50 69 Datacenters = dc1 70 Status = running 71 Periodic = false 72 73 ==> Evaluations 74 ID Priority Triggered By Status 75 26cfc69e 50 job-register complete 76 77 ==> Allocations 78 ID Eval ID Node ID Task Group Desired Status 79 8ba85cef 26cfc69e 171a583b cache run running 80 ``` 81 82 Here we can see that our evaluation that was created has completed, and that 83 it resulted in the creation of an allocation that is now running on the local node. 84 85 ## Modifying a Job 86 87 The definition of a job is not static, and is meant to be updated over time. 88 You may update a job to change the docker container, to update the application version, 89 or to change the count of a task group to scale with load. 90 91 For now, edit the `example.nomad` file to uncomment the count and set it to 3: 92 93 ``` 94 # Control the number of instances of this group. 95 # Defaults to 1 96 count = 3 97 ``` 98 99 Once you have finished modifying the job specification, use `nomad run` to 100 push the updated version of the job: 101 102 ``` 103 $ nomad run example.nomad 104 ==> Monitoring evaluation "127a49d0" 105 Evaluation triggered by job "example" 106 Allocation "8ab24eef" created: node "171a583b", group "cache" 107 Allocation "f6c29874" created: node "171a583b", group "cache" 108 Allocation "8ba85cef" modified: node "171a583b", group "cache" 109 Evaluation status changed: "pending" -> "complete" 110 ==> Evaluation "127a49d0" finished with status "complete" 111 ``` 112 113 Because we set the count of the task group to three, Nomad created two 114 additional allocations to get to the desired state. It is idempotent to 115 run the same job specification again and no new allocations will be created. 116 117 Now, let's try to do an application update. In this case, we will simply change 118 the version of redis we want to run. Edit the `example.nomad` file and change 119 the Docker image from "redis:latest" to "redis:2.8": 120 121 ``` 122 # Configure Docker driver with the image 123 config { 124 image = "redis:2.8" 125 } 126 ``` 127 128 This time we have not changed the number of task groups we want running, 129 but we've changed the task itself. This requires stopping the old tasks 130 and starting new tasks. Our example job is configured to do a rolling update via 131 the `stagger` attribute, doing a single update every 10 seconds. Use `run` to push the updated 132 specification now: 133 134 ``` 135 $ nomad run example.nomad 136 ==> Monitoring evaluation "ebcc3e14" 137 Evaluation triggered by job "example" 138 Allocation "9a3743f4" created: node "171a583b", group "cache" 139 Evaluation status changed: "pending" -> "complete" 140 ==> Evaluation "ebcc3e14" finished with status "complete" 141 ==> Monitoring evaluation "b508d8f0" 142 Evaluation triggered by job "example" 143 Allocation "926e5876" created: node "171a583b", group "cache" 144 Evaluation status changed: "pending" -> "complete" 145 ==> Evaluation "b508d8f0" finished with status "complete" 146 ==> Monitoring next evaluation "ea78c05a" in 10s 147 ==> Monitoring evaluation "ea78c05a" 148 Evaluation triggered by job "example" 149 Allocation "3c8589d5" created: node "171a583b", group "cache" 150 Evaluation status changed: "pending" -> "complete" 151 ==> Evaluation "ea78c05a" finished with status "complete" 152 ``` 153 154 We can see that Nomad handled the update in three phases, only updating a single task 155 group in each phase. The update strategy can be configured, but rolling updates makes 156 it easy to upgrade an application at large scale. 157 158 ## Stopping a Job 159 160 So far we've created, run and modified a job. The final step in a job lifecycle 161 is stopping the job. This is done with the [`stop` command](/docs/commands/stop.html): 162 163 ``` 164 $ nomad stop example 165 ==> Monitoring evaluation "fd03c9f8" 166 Evaluation triggered by job "example" 167 Evaluation status changed: "pending" -> "complete" 168 ==> Evaluation "fd03c9f8" finished with status "complete" 169 ``` 170 171 When we stop a job, it creates an evaluation which is used to stop all 172 the existing allocations. This also deletes the job definition out of Nomad. 173 If we try to query the job status, we can see it is no longer registered: 174 175 ``` 176 $ nomad status example 177 No job(s) with prefix or id "example" found 178 ``` 179 180 If we wanted to start the job again, we could simply `run` it again. 181 182 ## Next Steps 183 184 Users of Nomad primarily interact with jobs, and we've now seen 185 how to create and scale our job, perform an application update, 186 and do a job tear down. Next we will add another Nomad 187 client to [create our first cluster](cluster.html) 188