1## Job
2
3### Create new job
4
5This endpoint creates (aka "registers") a new job in the system.
6
7https://www.nomadproject.io/api/jobs.html#create-job
8
9Example:
10
11```
12import nomad
13
14job = {'Job': {'AllAtOnce': None,
15  'Constraints': None,
16  'CreateIndex': None,
17  'Datacenters': ['dc1'],
18  'ID': 'example',
19  'JobModifyIndex': None,
20  'Meta': None,
21  'ModifyIndex': None,
22  'Name': 'example',
23  'Namespace': None,
24  'ParameterizedJob': None,
25  'ParentID': None,
26  'Payload': None,
27  'Periodic': None,
28  'Priority': None,
29  'Region': None,
30  'Stable': None,
31  'Status': None,
32  'StatusDescription': None,
33  'Stop': None,
34  'SubmitTime': None,
35  'TaskGroups': [{'Constraints': None,
36    'Count': 1,
37    'EphemeralDisk': {'Migrate': None, 'SizeMB': 300, 'Sticky': None},
38    'Meta': None,
39    'Name': 'cache',
40    'RestartPolicy': {'Attempts': 10,
41     'Delay': 25000000000,
42     'Interval': 300000000000,
43     'Mode': 'delay'},
44    'Tasks': [{'Artifacts': None,
45      'Config': {'image': 'redis:3.2', 'port_map': [{'db': 6379}]},
46      'Constraints': None,
47      'DispatchPayload': None,
48      'Driver': 'docker',
49      'Env': None,
50      'KillTimeout': None,
51      'Leader': False,
52      'LogConfig': None,
53      'Meta': None,
54      'Name': 'redis',
55      'Resources': {'CPU': 500,
56       'DiskMB': None,
57       'IOPS': None,
58       'MemoryMB': 256,
59       'Networks': [{'CIDR': '',
60         'Device': '',
61         'DynamicPorts': [{'Label': 'db', 'Value': 0}],
62         'IP': '',
63         'MBits': 10,
64         'ReservedPorts': None}]},
65      'Services': [{'AddressMode': '',
66        'CheckRestart': None,
67        'Checks': [{'Args': None,
68          'CheckRestart': None,
69          'Command': '',
70          'Header': None,
71          'Id': '',
72          'InitialStatus': '',
73          'Interval': 10000000000,
74          'Method': '',
75          'Name': 'alive',
76          'Path': '',
77          'PortLabel': '',
78          'Protocol': '',
79          'TLSSkipVerify': False,
80          'Timeout': 2000000000,
81          'Type': 'tcp'}],
82        'Id': '',
83        'Name': 'global-redis-check',
84        'PortLabel': 'db',
85        'Tags': ['global', 'cache']}],
86      'ShutdownDelay': 0,
87      'Templates': None,
88      'User': '',
89      'Vault': None}],
90    'Update': None}],
91  'Type': 'service',
92  'Update': {'AutoRevert': False,
93   'Canary': 0,
94   'HealthCheck': None,
95   'HealthyDeadline': 180000000000,
96   'MaxParallel': 1,
97   'MinHealthyTime': 10000000000,
98   'Stagger': None},
99  'VaultToken': None,
100  'Version': None}}
101
102my_nomad = nomad.Nomad(host='192.168.33.10')
103
104response = my_nomad.job.register_job("example", job)
105```
106
107
108### Read job
109
110This endpoint reads information about a single job for its specification and status.
111
112https://www.nomadproject.io/api/jobs.html#read-job
113
114
115Example:
116
117```
118import nomad
119
120my_nomad = nomad.Nomad(host='192.168.33.10')
121
122job = my_nomad.job.get_job("example")
123```
124
125### Job versions
126
127This endpoint reads information about all versions of a job.
128
129https://www.nomadproject.io/api/jobs.html#list-job-versions
130
131Example:
132
133```
134import nomad
135
136my_nomad = nomad.Nomad(host='192.168.33.10')
137
138versions = my_nomad.job.get_versions("example")
139
140for version in versions["Versions"]:
141  print (version)
142```
143
144### List job allocations
145
146This endpoint reads information about a single job's allocations.
147
148https://www.nomadproject.io/api/jobs.html#list-job-allocations
149
150Example:
151
152```
153import nomad
154
155my_nomad = nomad.Nomad(host='192.168.33.10')
156
157allocations = my_nomad.job.get_allocations("example")
158
159for allocation in allocations:
160  print (allocation)
161```
162
163### List job evaluations
164
165This endpoint reads information about a single job's evaluations
166
167https://www.nomadproject.io/api/jobs.html#list-job-evaluations
168
169Example:
170
171```
172import nomad
173
174my_nomad = nomad.Nomad(host='192.168.33.10')
175
176evaluations = my_nomad.job.get_evaluations("example")
177
178for evaluation in evaluations:
179  print (evaluation)
180```
181
182
183### List job deploymetns
184
185This endpoint lists a single job's deployments
186
187https://www.nomadproject.io/api/jobs.html#list-job-deployments
188
189Example:
190
191```
192import nomad
193
194my_nomad = nomad.Nomad(host='192.168.33.10')
195
196deployments = my_nomad.job.get_deployments("example")
197
198for deployment in deployments:
199  print (deployment)
200```
201
202
203### Read job's most recent deployment
204
205This endpoint returns a single job's most recent deployment.
206
207https://www.nomadproject.io/api/jobs.html#read-job-39-s-most-recent-deployment
208
209Example:
210
211```
212import nomad
213
214my_nomad = nomad.Nomad(host='192.168.33.10')
215
216deployment = my_nomad.job.get_deployment("example")
217
218```
219
220### Job summary
221
222This endpoint reads summary information about a job.
223
224https://www.nomadproject.io/api/jobs.html#read-job-summary
225
226Example:
227
228```
229import nomad
230
231my_nomad = nomad.Nomad(host='192.168.33.10')
232
233summary = my_nomad.job.get_summary("example")
234```
235
236
237### Update existing job
238
239This endpoint registers a new job or updates an existing job.
240
241https://www.nomadproject.io/api/jobs.html#update-existing-job
242
243Example:
244
245See create new job
246
247
248### Dispatch job
249
250This endpoint dispatches a new instance of a parameterized job.
251
252https://www.nomadproject.io/api/jobs.html#dispatch-job
253
254Example:
255
256```
257import nomad
258
259my_nomad = nomad.Nomad(host='192.168.33.10')
260
261parametrize_job = {
262    "Job": {
263        "Region": "example-region",
264        "ID": "example-batch",
265        "ParentID": "",
266        "Name": "example-batch",
267        "Type": "batch",
268        "Priority": 100,
269        "AllAtOnce": False,
270        "Datacenters": [
271            "dc1"],
272        "Constraints": [],
273        "ParameterizedJob": {
274            "Payload": "optional",
275            "MetaRequired": [
276                "time"
277            ],
278            "MetaOptional": []
279        },
280        "TaskGroups": [
281            {
282                "Name": "example-task-group",
283                "Count": 0,
284                "Constraints": None,
285                "Tasks": [
286                    {
287                        "Name": "example-task",
288                        "Driver": "docker",
289                        "Config": {
290                            "args": ["${NOMAD_META_TIME"],
291                            "command": "sleep",
292                            "image": "scratch",
293                            "logging": [],
294                            "port_map": []
295                        },
296                        "Constraints": None,
297                        "Env": {},
298                        "Services": [],
299                        "Resources": {
300                            "CPU": 100,
301                            "MemoryMB": 200,
302                            "IOPS": 0,
303                            "Networks": []
304                        },
305                        "Meta": None,
306                        "KillTimeout": 5000000000,
307                        "LogConfig": {
308                            "MaxFiles": 10,
309                            "MaxFileSizeMB": 10
310                        },
311                        "Artifacts": None,
312                        "Vault": None,
313                        "Templates": [],
314                        "DispatchPayload": None
315                    }
316                ],
317                "RestartPolicy": {
318                    "Interval": 600000000000,
319                    "Attempts": 10,
320                    "Delay": 30000000000,
321                    "Mode": "delay"
322                }
323            }
324        ],
325        "Update": {
326            "Stagger": 0,
327            "MaxParallel": 0
328        }
329    }
330}
331
332my_nomad = nomad.Nomad(host='192.168.33.10')
333
334response = my_nomad.job.register_job("example-batch", parametrize_job)
335
336my_nomad.job.dispatch_job("example-batch", meta={"time": "500"})
337```
338
339### Revert to older job version
340
341This endpoint reverts the job to an older version.
342
343https://www.nomadproject.io/api/jobs.html#revert-to-older-job-version
344
345Example:
346
347```
348import nomad
349
350my_nomad = nomad.Nomad(host='192.168.33.10')
351
352current_job_version = my_nomad.job.job.get_deployment("example")["JobVersion"]
353
354prior_job_version = current_job_version - 1
355
356my_nomad.job.revert_job("example", prior_job_version, current_job_version)
357```
358
359
360### Set job stability
361
362This endpoint sets the job's stability.
363
364https://www.nomadproject.io/api/jobs.html#set-job-stability
365
366Example:
367
368```
369import nomad
370
371my_nomad = nomad.Nomad(host='192.168.33.10')
372
373current_job_version = my_nomad.job.get_deployment("example")["JobVersion"]
374
375my_nomad.job.stable_job("example", current_job_version, True)
376```
377
378
379### Create job evaluation
380
381This endpoint creates a new evaluation for the given job. This can be used to force run the scheduling logic if necessary.
382
383https://www.nomadproject.io/api/jobs.html#create-job-evaluation
384
385Example:
386
387```
388import nomad
389
390my_nomad = nomad.Nomad(host='192.168.33.10')
391
392my_nomad.job.evaluate_job("example")
393```
394
395### Create job plan
396
397This endpoint invokes a dry-run of the scheduler for the job.
398
399https://www.nomadproject.io/api/jobs.html#create-job-plan
400
401Example:
402
403```
404import nomad
405
406job = {'Job': {'AllAtOnce': None,
407  'Constraints': None,
408  'CreateIndex': None,
409  'Datacenters': ['dc1'],
410  'ID': 'example',
411  'JobModifyIndex': None,
412  'Meta': None,
413  'ModifyIndex': None,
414  'Name': 'example',
415  'Namespace': None,
416  'ParameterizedJob': None,
417  'ParentID': None,
418  'Payload': None,
419  'Periodic': None,
420  'Priority': None,
421  'Region': None,
422  'Stable': None,
423  'Status': None,
424  'StatusDescription': None,
425  'Stop': None,
426  'SubmitTime': None,
427  'TaskGroups': [{'Constraints': None,
428    'Count': 1,
429    'EphemeralDisk': {'Migrate': None, 'SizeMB': 300, 'Sticky': None},
430    'Meta': None,
431    'Name': 'cache',
432    'RestartPolicy': {'Attempts': 10,
433     'Delay': 25000000000,
434     'Interval': 300000000000,
435     'Mode': 'delay'},
436    'Tasks': [{'Artifacts': None,
437      'Config': {'image': 'redis:3.2', 'port_map': [{'db': 6379}]},
438      'Constraints': None,
439      'DispatchPayload': None,
440      'Driver': 'docker',
441      'Env': None,
442      'KillTimeout': None,
443      'Leader': False,
444      'LogConfig': None,
445      'Meta': None,
446      'Name': 'redis',
447      'Resources': {'CPU': 500,
448       'DiskMB': None,
449       'IOPS': None,
450       'MemoryMB': 256,
451       'Networks': [{'CIDR': '',
452         'Device': '',
453         'DynamicPorts': [{'Label': 'db', 'Value': 0}],
454         'IP': '',
455         'MBits': 10,
456         'ReservedPorts': None}]},
457      'Services': [{'AddressMode': '',
458        'CheckRestart': None,
459        'Checks': [{'Args': None,
460          'CheckRestart': None,
461          'Command': '',
462          'Header': None,
463          'Id': '',
464          'InitialStatus': '',
465          'Interval': 10000000000,
466          'Method': '',
467          'Name': 'alive',
468          'Path': '',
469          'PortLabel': '',
470          'Protocol': '',
471          'TLSSkipVerify': False,
472          'Timeout': 2000000000,
473          'Type': 'tcp'}],
474        'Id': '',
475        'Name': 'global-redis-check',
476        'PortLabel': 'db',
477        'Tags': ['global', 'cache']}],
478      'ShutdownDelay': 0,
479      'Templates': None,
480      'User': '',
481      'Vault': None}],
482    'Update': None}],
483  'Type': 'service',
484  'Update': {'AutoRevert': False,
485   'Canary': 0,
486   'HealthCheck': None,
487   'HealthyDeadline': 180000000000,
488   'MaxParallel': 1,
489   'MinHealthyTime': 10000000000,
490   'Stagger': None},
491  'VaultToken': None,
492  'Version': None}}
493
494my_nomad = nomad.Nomad(host='192.168.33.10')
495
496plan = my_nomad.job.plan_job("example", job)
497```
498
499### Stop a job
500
501This endpoint deregisters a job, and stops all allocations part of it.
502
503https://www.nomadproject.io/api/jobs.html#stop-a-job
504
505Example of deferred removal of job (performed by Nomad garbage collector):
506
507```
508import nomad
509
510my_nomad = nomad.Nomad(host='192.168.33.10')
511
512my_nomad.job.deregister_job("example")
513```
514
515Example of immediate removal of job (job not queryable after this):
516
517```
518import nomad
519
520my_nomad = nomad.Nomad(host='192.168.33.10')
521
522my_nomad.job.deregister_job("example", purge=True)
523```
524