0f92cf9058
* Add new commands for 0.6 * update version in documnetation for 0.6 * more information in example.nomad * 0.6 additional information for viewing status of a job * 0.6 status for alloc-status * changes with 0.6 in modifying a job * status is healthy when consul is running * make new date consistent in * add Latest Deployment and Deployed sections to output * small changes in status values so that things the user should see as thesame, are the same in the example (e.g. Node ID should be the same in all places we list it in the example) * further information in job status added in 0.6 * update output when changing redis version * make new date consistent in * add Latest Deployment and Deployed sections to output * small changes in status values so that things the user should see as thesame, are the same in the example (e.g. Node ID should be the same in all places we list it in the example) * Add new commands for 0.6 * update version in documnetation for 0.6 * more information in example.nomad * 0.6 additional information for viewing status of a job * 0.6 status for alloc-status * changes with 0.6 in modifying a job * status is healthy when consul is running * further information in job status added in 0.6 * evaluation status for deployment in 0.6 * updating client demo config to match website * update output of status for cluster * update output when changing redis version * update terminal output of adding more redis instances. * small update so id numbers are consistent in example * update ouput for , also stitch up ids from previous lines to match * add to output when starting server and clients * add to output * remove text showing large parts of example.nomad file * Small fixes to stopping and updating a job
344 lines
12 KiB
Markdown
344 lines
12 KiB
Markdown
---
|
|
layout: "intro"
|
|
page_title: "Jobs"
|
|
sidebar_current: "getting-started-jobs"
|
|
description: |-
|
|
Learn how to submit, modify and stop jobs in Nomad.
|
|
---
|
|
|
|
# Jobs
|
|
|
|
Jobs are the primary configuration that users interact with when using
|
|
Nomad. A job is a declarative specification of tasks that Nomad should run.
|
|
Jobs have a globally unique name, one or many task groups, which are themselves
|
|
collections of one or many tasks.
|
|
|
|
The format of the jobs is documented in the [job specification][jobspec]. They
|
|
can either be specified in [HashiCorp Configuration Language][hcl] or JSON,
|
|
however we recommend only using JSON when the configuration is generated by a machine.
|
|
|
|
## Running a Job
|
|
|
|
To get started, we will use the [`init` command](/docs/commands/init.html) which
|
|
generates a skeleton job file:
|
|
|
|
```
|
|
$ nomad init
|
|
Example job file written to example.nomad
|
|
```
|
|
|
|
You can view the contents of this file by running `cat example.nomad`. In this
|
|
example job file, we have declared a single task 'redis' which is using
|
|
the Docker driver to run the task. The primary way you interact with Nomad
|
|
is with the [`run` command](/docs/commands/run.html). The `run` command takes
|
|
a job file and registers it with Nomad. This is used both to register new
|
|
jobs and to update existing jobs.
|
|
|
|
We can register our example job now:
|
|
|
|
```
|
|
$ nomad run example.nomad
|
|
==> Monitoring evaluation "26cfc69e"
|
|
Evaluation triggered by job "example"
|
|
Allocation "8ba85cef" created: node "171a583b", group "cache"
|
|
Evaluation status changed: "pending" -> "complete"
|
|
==> Evaluation "26cfc69e" finished with status "complete"
|
|
```
|
|
|
|
Anytime a job is updated, Nomad creates an evaluation to determine what
|
|
actions need to take place. In this case, because this is a new job, Nomad has
|
|
determined that an allocation should be created and has scheduled it on our
|
|
local agent.
|
|
|
|
To inspect the status of our job we use the [`status` command](/docs/commands/status.html):
|
|
|
|
```
|
|
$ nomad status example
|
|
ID = example
|
|
Name = example
|
|
Submit Date = 07/25/17 23:14:43 UTC
|
|
Type = service
|
|
Priority = 50
|
|
Datacenters = dc1
|
|
Status = running
|
|
Periodic = false
|
|
Parameterized = false
|
|
|
|
Summary
|
|
Task Group Queued Starting Running Failed Complete Lost
|
|
cache 0 0 1 0 0 0
|
|
|
|
Latest Deployment
|
|
ID = 11c5cdc8
|
|
Status = successful
|
|
Description = Deployment completed successfully
|
|
|
|
Deployed
|
|
Task Group Desired Placed Healthy Unhealthy
|
|
cache 1 1 1 0
|
|
|
|
Allocations
|
|
ID Node ID Task Group Version Desired Status Created At
|
|
8ba85cef 171a583b cache 0 run running 07/25/17 23:14:43 UTC
|
|
```
|
|
|
|
Here we can see that the result of our evaluation was the creation of an
|
|
allocation that is now running on the local node.
|
|
|
|
An allocation represents an instance of Task Group placed on a node. To inspect
|
|
an allocation we use the [`alloc-status` command](/docs/commands/alloc-status.html):
|
|
|
|
```
|
|
$ nomad alloc-status 8ba85cef
|
|
ID = 8ba85cef
|
|
Eval ID = 61b0b423
|
|
Name = example.cache[0]
|
|
Node ID = 171a583b
|
|
Job ID = example
|
|
Job Version = 0
|
|
Client Status = running
|
|
Client Description = <none>
|
|
Desired Status = run
|
|
Desired Description = <none>
|
|
Created At = 07/25/17 23:14:43 UTC
|
|
Deployment ID = fa882a5b
|
|
Deployment Health = healthy
|
|
|
|
Task "redis" is "running"
|
|
Task Resources
|
|
CPU Memory Disk IOPS Addresses
|
|
2/500 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:30329
|
|
|
|
Recent Events:
|
|
Time Type Description
|
|
07/25/17 23:14:53 UTC Started Task started by client
|
|
07/25/17 23:14:43 UTC Driver Downloading image redis:3.2
|
|
07/25/17 23:14:43 UTC Task Setup Building Task Directory
|
|
07/25/17 23:14:43 UTC Received Task received by client
|
|
```
|
|
|
|
We can see that Nomad reports the state of the allocation as well as its
|
|
current resource usage. By supplying the `-stats` flag, more detailed resource
|
|
usage statistics will be reported.
|
|
|
|
To see the logs of a task, we can use the [logs command](/docs/commands/logs.html):
|
|
|
|
```
|
|
$ nomad logs 8ba85cef redis
|
|
_._
|
|
_.-``__ ''-._
|
|
_.-`` `. `_. ''-._ Redis 3.2.1 (00000000/0) 64 bit
|
|
.-`` .-```. ```\/ _.,_ ''-._
|
|
( ' , .-` | `, ) Running in standalone mode
|
|
|`-._`-...-` __...-.``-._|'` _.-'| Port: 6379
|
|
| `-._ `._ / _.-' | PID: 1
|
|
`-._ `-._ `-./ _.-' _.-'
|
|
|`-._`-._ `-.__.-' _.-'_.-'|
|
|
| `-._`-._ _.-'_.-' | http://redis.io
|
|
`-._ `-._`-.__.-'_.-' _.-'
|
|
|`-._`-._ `-.__.-' _.-'_.-'|
|
|
| `-._`-._ _.-'_.-' |
|
|
`-._ `-._`-.__.-'_.-' _.-'
|
|
`-._ `-.__.-' _.-'
|
|
`-._ _.-'
|
|
`-.__.-'
|
|
...
|
|
```
|
|
|
|
## Modifying a Job
|
|
|
|
The definition of a job is not static, and is meant to be updated over time.
|
|
You may update a job to change the docker container, to update the application version,
|
|
or to change the count of a task group to scale with load.
|
|
|
|
For now, edit the `example.nomad` file to update the count and set it to 3:
|
|
|
|
```
|
|
# The "count" parameter specifies the number of the task groups that should
|
|
# be running under this group. This value must be non-negative and defaults
|
|
# to 1.
|
|
count = 3
|
|
```
|
|
|
|
Once you have finished modifying the job specification, use the [`plan`
|
|
command](/docs/commands/plan.html) to invoke a dry-run of the scheduler to see
|
|
what would happen if you ran the updated job:
|
|
|
|
```
|
|
$ nomad plan example.nomad
|
|
+/- Job: "example"
|
|
+/- Task Group: "cache" (2 create, 1 in-place update)
|
|
+/- Count: "1" => "3" (forces create)
|
|
Task: "redis"
|
|
|
|
Scheduler dry-run:
|
|
- All tasks successfully allocated.
|
|
|
|
Job Modify Index: 6
|
|
To submit the job with version verification run:
|
|
|
|
nomad run -check-index 6 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
server side version matches the job modify index returned. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
We can see that the scheduler detected the change in count and informs us that
|
|
it will cause 2 new instances to be created. The in-place update that will
|
|
occur is to push the update job specification to the existing allocation and
|
|
will not cause any service interruption. We can then run the job with the
|
|
run command the `plan` emitted.
|
|
|
|
By running with the `-check-index` flag, Nomad checks that the job has not
|
|
been modified since the plan was run. This is useful if multiple people are
|
|
interacting with the job at the same time to ensure the job hasn't changed
|
|
before you apply your modifications.
|
|
|
|
```
|
|
$ nomad run -check-index 6 example.nomad
|
|
==> Monitoring evaluation "127a49d0"
|
|
Evaluation triggered by job "example"
|
|
Evaluation within deployment: "2e2c818f"
|
|
Allocation "8ab24eef" created: node "171a583b", group "cache"
|
|
Allocation "f6c29874" created: node "171a583b", group "cache"
|
|
Allocation "8ba85cef" modified: node "171a583b", group "cache"
|
|
Evaluation status changed: "pending" -> "complete"
|
|
==> Evaluation "127a49d0" finished with status "complete"
|
|
```
|
|
|
|
Because we set the count of the task group to three, Nomad created two
|
|
additional allocations to get to the desired state. It is idempotent to
|
|
run the same job specification again and no new allocations will be created.
|
|
|
|
Now, let's try to do an application update. In this case, we will simply change
|
|
the version of redis we want to run. Edit the `example.nomad` file and change
|
|
the Docker image from "redis:3.2" to "redis:4.0":
|
|
|
|
```
|
|
# Configure Docker driver with the image
|
|
config {
|
|
image = "redis:4.0"
|
|
}
|
|
```
|
|
|
|
We can run `plan` again to see what will happen if we submit this change:
|
|
|
|
```
|
|
$ nomad plan example.nomad
|
|
+/- Job: "example"
|
|
+/- Task Group: "cache" (1 create/destroy update, 2 ignore)
|
|
+/- Task: "redis" (forces create/destroy update)
|
|
+/- Config {
|
|
+/- image: "redis:3.2" => "redis:4.0"
|
|
port_map[0][db]: "6379"
|
|
}
|
|
|
|
Scheduler dry-run:
|
|
- All tasks successfully allocated.
|
|
- Rolling update, next evaluation will be in 10s.
|
|
|
|
Job Modify Index: 42
|
|
To submit the job with version verification run:
|
|
|
|
nomad run -check-index 42 example.nomad
|
|
|
|
When running the job with the check-index flag, the job will only be run if the
|
|
server side version matches the job modify index returned. If the index has
|
|
changed, another user has modified the job and the plan's results are
|
|
potentially invalid.
|
|
```
|
|
|
|
Here we can see the `plan` reports it will ignore two allocations and do one
|
|
create/destroy update which stops the old allocation and starts the new
|
|
allocation because we have changed the version of redis to run.
|
|
|
|
The reason the plan only reports a single change to occur is because the job
|
|
file has an `update` stanza that tells Nomad to perform rolling updates when the
|
|
job changes at a rate of `max_parallel`, which is set to 1 in the example file.
|
|
|
|
Once ready, use `run` to push the updated specification:
|
|
|
|
```
|
|
$ nomad run example.nomad
|
|
==> Monitoring evaluation "02161762"
|
|
Evaluation triggered by job "example"
|
|
Evaluation within deployment: "429f8160"
|
|
Allocation "de4e3f7a" created: node "6c027e58", group "cache"
|
|
Evaluation status changed: "pending" -> "complete"
|
|
==> Evaluation "02161762" finished with status "complete"
|
|
```
|
|
|
|
After running, the rolling upgrade can be followed by running `nomad status` and
|
|
watching the deployed count.
|
|
|
|
We can see that Nomad handled the update in three phases, only updating a single
|
|
allocation in each phase and waiting for it to be healthy for `min_healthy_time`
|
|
of 10 seconds before moving on to the next. The update strategy can be
|
|
configured, but rolling updates makes it easy to upgrade an application at large
|
|
scale.
|
|
|
|
## Stopping a Job
|
|
|
|
So far we've created, run and modified a job. The final step in a job lifecycle
|
|
is stopping the job. This is done with the [`stop` command](/docs/commands/stop.html):
|
|
|
|
```
|
|
$ nomad stop example
|
|
==> Monitoring evaluation "ddc4eb7d"
|
|
Evaluation triggered by job "example"
|
|
Evaluation within deployment: "ec46fb3b"
|
|
Evaluation status changed: "pending" -> "complete"
|
|
==> Evaluation "ddc4eb7d" finished with status "complete"
|
|
```
|
|
|
|
When we stop a job, it creates an evaluation which is used to stop all
|
|
the existing allocations. If we now query the job status, we can see it is
|
|
now marked as `dead (stopped)`, indicating that the job has been stopped and
|
|
Nomad is no longer running it:
|
|
|
|
```
|
|
$ nomad status example
|
|
ID = example
|
|
Name = example
|
|
Submit Date = 07/26/17 17:51:01 UTC
|
|
Type = service
|
|
Priority = 50
|
|
Datacenters = dc1
|
|
Status = dead (stopped)
|
|
Periodic = false
|
|
Parameterized = false
|
|
|
|
Summary
|
|
Task Group Queued Starting Running Failed Complete Lost
|
|
cache 0 0 0 0 3 0
|
|
|
|
Latest Deployment
|
|
ID = ec46fb3b
|
|
Status = successful
|
|
Description = Deployment completed successfully
|
|
|
|
Deployed
|
|
Task Group Desired Placed Healthy Unhealthy
|
|
cache 3 3 3 0
|
|
|
|
Allocations
|
|
ID Node ID Task Group Version Desired Status Created At
|
|
8ace140d 2cfe061e cache 2 stop complete 07/26/17 17:51:01 UTC
|
|
8af5330a 2cfe061e cache 2 stop complete 07/26/17 17:51:01 UTC
|
|
df50c3ae 2cfe061e cache 2 stop complete 07/26/17 17:51:01 UTC
|
|
```
|
|
|
|
If we wanted to start the job again, we could simply `run` it again.
|
|
|
|
## Next Steps
|
|
|
|
Users of Nomad primarily interact with jobs, and we've now seen
|
|
how to create and scale our job, perform an application update,
|
|
and do a job tear down. Next we will add another Nomad
|
|
client to [create our first cluster](cluster.html)
|
|
|
|
[jobspec]: /docs/job-specification/index.html "Nomad Job Specification"
|
|
[hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language"
|