github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/job.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "job Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-job" 5 description: |- 6 The "job" stanza is the top-most configuration option in the job 7 specification. A job is a declarative specification of tasks that Nomad 8 should run. 9 --- 10 11 # `job` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>**job**</code> 18 </td> 19 </tr> 20 </table> 21 22 The `job` stanza is the top-most configuration option in the job specification. 23 A job is a declarative specification of tasks that Nomad should run. Jobs have a 24 globally unique name, one or many task groups, which are themselves collections 25 of one or many tasks. 26 27 ```hcl 28 job "docs" { 29 constraint { 30 # ... 31 } 32 33 datacenters = ["us-east-1"] 34 35 group "example" { 36 # ... 37 } 38 39 meta { 40 "my-key" = "my-value" 41 } 42 43 parameterized { 44 # ... 45 } 46 47 periodic { 48 # ... 49 } 50 51 priority = 100 52 53 region = "north-america" 54 55 task "docs" { 56 # ... 57 } 58 59 update { 60 # ... 61 } 62 } 63 ``` 64 65 ## `job` Parameters 66 67 - `all_at_once` `(bool: false)` - Controls whether the scheduler can make 68 partial placements if optimistic scheduling resulted in an oversubscribed 69 node. This does not control whether all allocations for the job, where all 70 would be the desired count for each task group, must be placed atomically. 71 This should only be used for special circumstances. 72 73 - `constraint` <code>([Constraint][constraint]: nil)</code> - 74 This can be provided multiple times to define additional constraints. See the 75 [Nomad constraint reference](/docs/job-specification/constraint.html) for more 76 details. 77 78 - `datacenters` `(array<string>: <required>)` - A list of datacenters in the region which are eligible 79 for task placement. This must be provided, and does not have a default. 80 81 - `group` <code>([Group][group]: \<required\>)</code> - Specifies the start of a 82 group of tasks. This can be provided multiple times to define additional 83 groups. Group names must be unique within the job file. 84 85 - `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates 86 with user-defined metadata. 87 88 - `namespace` `(string: "default")` - The namespace in which to execute the job. 89 Values other than default are not allowed in non-Enterprise versions of Nomad. 90 91 - `parameterized` <code>([Parameterized][parameterized]: nil)</code> - Specifies 92 the job as a parameterized job such that it can be dispatched against. 93 94 - `periodic` <code>([Periodic][]: nil)</code> - Allows the job to be scheduled 95 at fixed times, dates or intervals. 96 97 - `priority` `(int: 50)` - Specifies the job priority which is used to 98 prioritize scheduling and access to resources. Must be between 1 and 100 99 inclusively, with a larger value corresponding to a higher priority. 100 101 - `region` `(string: "global")` - The region in which to execute the job. 102 103 - `type` `(string: "service")` - Specifies the [Nomad scheduler][scheduler] to 104 use. Nomad provides the `service`, `system` and `batch` schedulers. 105 106 - `update` <code>([Update][update]: nil)</code> - Specifies the task's update 107 strategy. When omitted, rolling updates are disabled. 108 109 - `vault` <code>([Vault][]: nil)</code> - Specifies the set of Vault policies 110 required by all tasks in this job. 111 112 - `vault_token` `(string: "")` - Specifies the Vault token that proves the 113 submitter of the job has access to the specified policies in the 114 [`vault`][vault] stanza. This field is only used to transfer the token and is 115 not stored after job submission. 116 117 !> It is **strongly discouraged** to place the token as a configuration 118 parameter like this, since the token could be checked into source control 119 accidentally. Users should set the `VAULT_TOKEN` environment variable when 120 running the job instead. 121 122 ## `job` Examples 123 124 The following examples only show the `job` stanzas. Remember that the 125 `job` stanza is only valid in the placements listed above. 126 127 ### Docker Container 128 129 This example job starts a Docker container which runs as a service. Even though 130 the type is not specified as "service", that is the default job type. 131 132 ```hcl 133 job "docs" { 134 datacenters = ["default"] 135 136 group "example" { 137 task "server" { 138 driver = "docker" 139 config { 140 image = "hashicorp/http-echo" 141 args = ["-text", "hello"] 142 } 143 144 resources { 145 memory = 128 146 } 147 } 148 } 149 } 150 ``` 151 152 ### Batch Job 153 154 This example job executes the `uptime` command on 10 Nomad clients in the fleet, 155 restricting the eligible nodes to Linux machines. 156 157 ```hcl 158 job "docs" { 159 datacenters = ["default"] 160 161 type = "batch" 162 163 constraint { 164 attribute = "${attr.kernel.name}" 165 value = "linux" 166 } 167 168 group "example" { 169 count = 10 170 task "uptime" { 171 driver = "exec" 172 config { 173 command = "uptime" 174 } 175 } 176 } 177 } 178 ``` 179 180 ### Consuming Secrets 181 182 This example shows a job which retrieves secrets from Vault and writes those 183 secrets to a file on disk, which the application then consumes. Nomad handles 184 all interactions with Vault. 185 186 ```hcl 187 job "docs" { 188 datacenters = ["default"] 189 190 group "example" { 191 task "cat" { 192 driver = "exec" 193 194 config { 195 command = "cat" 196 args = ["local/secrets.txt"] 197 } 198 199 template { 200 data = "{{ secret \"secret/data\" }}" 201 destination = "local/secrets.txt" 202 } 203 204 vault { 205 policies = ["secret-readonly"] 206 } 207 } 208 } 209 } 210 ``` 211 212 When submitting this job, you would run: 213 214 ``` 215 $ VAULT_TOKEN="..." nomad job run example.nomad 216 ``` 217 218 [constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification" 219 [group]: /docs/job-specification/group.html "Nomad group Job Specification" 220 [meta]: /docs/job-specification/meta.html "Nomad meta Job Specification" 221 [parameterized]: /docs/job-specification/parameterized.html "Nomad parameterized Job Specification" 222 [periodic]: /docs/job-specification/periodic.html "Nomad periodic Job Specification" 223 [task]: /docs/job-specification/task.html "Nomad task Job Specification" 224 [update]: /docs/job-specification/update.html "Nomad update Job Specification" 225 [vault]: /docs/job-specification/vault.html "Nomad vault Job Specification" 226 [scheduler]: /docs/runtime/schedulers.html "Nomad Scheduler Types"