github.com/kardianos/nomad@v0.1.3-0.20151022182107-b13df73ee850/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 "3d823c52-929a-fa8b-c50d-1ac4d00cf6b7" 50 Evaluation triggered by job "example" 51 Allocation "85b839d7-f67a-72a4-5a13-104020ae4807" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 52 Evaluation status changed: "pending" -> "complete" 53 ==> Evaluation "3d823c52-929a-fa8b-c50d-1ac4d00cf6b7" 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 = <none> 71 72 ==> Evaluations 73 ID Priority TriggeredBy Status 74 3d823c52-929a-fa8b-c50d-1ac4d00cf6b7 50 job-register complete 75 76 ==> Allocations 77 ID EvalID NodeID TaskGroup Desired Status 78 85b839d7-f67a-72a4-5a13-104020ae4807 3d823c52-929a-fa8b-c50d-1ac4d00cf6b7 2512929f-5b7c-a959-dfd9-bf8a8eb022a6 cache run running 79 ``` 80 81 Here we can see that our evaluation that was created has completed, and that 82 it resulted in the creation of an allocation that is now running on the local node. 83 84 ## Modifying a Job 85 86 The definition of a job is not static, and is meant to be updated over time. 87 You may update a job to change the docker container, to update the application version, 88 or to change the count of a task group to scale with load. 89 90 For now, edit the `example.nomad` file to uncomment the count and set it to 3: 91 92 ``` 93 # Control the number of instances of this group. 94 # Defaults to 1 95 count = 3 96 ``` 97 98 Once you have finished modifying the job specification, use `nomad run` to 99 push the updated version of the job: 100 101 ``` 102 $ nomad run example.nomad 103 ==> Monitoring evaluation "ec199c63-2022-f5c7-328d-1cf85e61bf66" 104 Evaluation triggered by job "example" 105 Allocation "21551679-5224-cb6b-80a2-d0b091612d2e" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 106 Allocation "b1be1410-a01c-20ad-80ff-96750ec0f1da" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 107 Allocation "ed32a35d-8086-3f04-e299-4432e562cbf2" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 108 Evaluation status changed: "pending" -> "complete" 109 ==> Evaluation "ec199c63-2022-f5c7-328d-1cf85e61bf66" finished with status "complete" 110 ``` 111 112 Because we set the count of the task group to three, Nomad created two 113 additional allocations to get to the desired state. It is idempotent to 114 run the same job specification again and no new allocations will be created. 115 116 Now, let's try to do an application update. In this case, we will simply change 117 the version of redis we want to run. Edit the `example.nomad` file and change 118 the Docker image from "redis:latest" to "redis:2.8": 119 120 ``` 121 # Configure Docker driver with the image 122 config { 123 image = "redis:2.8" 124 } 125 ``` 126 127 This time we have not changed the number of task groups we want running, 128 but we've changed the task itself. This requires stopping the old tasks 129 and starting new tasks. Our example job is configured to do a rolling update via 130 the `stagger` attribute, doing a single update every 10 seconds. Use `run` to push the updated 131 specification now: 132 133 ``` 134 $ nomad run example.nomad 135 ==> Monitoring evaluation "d34d37f4-19b1-f4c0-b2da-c949e6ade82d" 136 Evaluation triggered by job "example" 137 Allocation "5614feb0-212d-21e5-ccfb-56a394fc41d5" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 138 Allocation "bf7e3ad5-b217-14fe-f3f8-2b83af9dbb42" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 139 Allocation "e3978af2-f61e-c601-7aa1-90aea9b23cf6" created: node "2512929f-5b7c-a959-dfd9-bf8a8eb022a6", group "cache" 140 Evaluation status changed: "pending" -> "complete" 141 ==> Evaluation "d34d37f4-19b1-f4c0-b2da-c949e6ade82d" finished with status "complete" 142 ``` 143 144 We can see that Nomad handled the update in three phases, only updating a single task 145 group in each phase. The update strategy can be configured, but rolling updates makes 146 it easy to upgrade an application at large scale. 147 148 ## Stopping a Job 149 150 So far we've created, run and modified a job. The final step in a job lifecycle 151 is stopping the job. This is done with the [`stop` command](/docs/commands/stop.html): 152 153 ``` 154 $ nomad stop example 155 ==> Monitoring evaluation "bb407de4-02cb-f009-d986-646d6c11366d" 156 Evaluation triggered by job "example" 157 Evaluation status changed: "pending" -> "complete" 158 ==> Evaluation "bb407de4-02cb-f009-d986-646d6c11366d" finished with status "complete" 159 ``` 160 161 When we stop a job, it creates an evaluation which is used to stop all 162 the existing allocations. This also deletes the job definition out of Nomad. 163 If we try to query the job status, we can see it is no longer registered: 164 165 ``` 166 $ nomad status example 167 Error querying job: Unexpected response code: 404 (job not found) 168 ``` 169 170 If we wanted to start the job again, we could simply `run` it again. 171 172 ## Next Steps 173 174 Users of Nomad primarily interact with jobs, and we've now seen 175 how to create and scale our job, perform an application update, 176 and do a job tear down. Next we will add another Nomad 177 client to [create our first cluster](cluster.html) 178