mirror of
https://github.com/kemko/nomad.git
synced 2026-01-03 08:55:43 +03:00
4eb78f1348
We have a description of the order of shutdown in the `task.leader` docs, but the `lifecycle` block is an intuitive place to look for this same information, and the behavior is largely governed by that feature anyways.
150 lines
4.7 KiB
Plaintext
150 lines
4.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: lifecycle block in the job specification
|
|
description: |-
|
|
Configure when Nomad runs a task in the `lifecycle` block of the Nomad job configuration. Specify a lifecycle hook of prestart, poststart, or poststop. Define a task as ephemeral or as a long-lived sidecar. Review examples of initialization, cleanup, and auxiliary tasks.
|
|
---
|
|
|
|
# `lifecycle` block in the job specification
|
|
|
|
<Placement groups={['job', 'group', 'task', 'lifecycle']} />
|
|
|
|
The `lifecycle` block is used to express task dependencies in Nomad by
|
|
configuring when a task is run within the lifecycle of a task group.
|
|
|
|
Main tasks are tasks that do not have a `lifecycle` block. Lifecycle task hooks
|
|
specify when other tasks are run in relation to the main tasks.
|
|
There are three different lifecycle hooks, indicating when a task is started:
|
|
|
|
- prestart tasks are started immediately
|
|
- poststart tasks are started after the main tasks are running
|
|
- poststop tasks are started after the main tasks are dead
|
|
|
|
Tasks can be run with an additional parameter indicating whether they are ephemeral
|
|
tasks or "sidecar" tasks that are expected to run for the duration of the main tasks.
|
|
The absence of the sidecar flag indicates that the task is ephemeral
|
|
and should not be restarted if it completes successfully.
|
|
|
|
The `lifecycle` block also controls the order Nomad stops tasks in an
|
|
allocation. Nomad first waits for the group's [shutdown_delay][]. It then stops
|
|
the [leader][] task, if present. Then Nomad stops any non-sidecar and
|
|
non-poststop tasks, and finally any sidecar tasks.
|
|
|
|
Learn more about [Nomad's task dependencies][learn-taskdeps].
|
|
|
|
## Parameters
|
|
|
|
- `hook` `(string: <required>)` - Specifies when a task should be run within
|
|
the lifecycle of a group. The following hooks are available:
|
|
|
|
- `prestart` - Will be started immediately. The main tasks will not start until
|
|
all `prestart` tasks with `sidecar = false` have completed successfully.
|
|
- `poststart` - Will be started once all main tasks are running.
|
|
- `poststop` - Will be started once all main tasks have stopped successfully
|
|
or exhausted their failure [retries](/nomad/docs/job-specification/restart).
|
|
|
|
- `sidecar` `(bool: false)` - Controls whether a task is ephemeral or
|
|
long-lived within the task group. If a lifecycle task is ephemeral
|
|
(`sidecar = false`), the task will not be restarted after it completes successfully. If a
|
|
lifecycle task is long-lived (`sidecar = true`) and terminates, it will be
|
|
restarted as long as the allocation is running.
|
|
|
|
[learn-taskdeps]: /nomad/tutorials/task-deps
|
|
[shutdown_delay]: /nomad/docs/job-specification/group#shutdown_delay
|
|
[leader]: /nomad/docs/job-specification/task#leader
|
|
|
|
## Examples
|
|
|
|
The following include examples of archetypal lifecycle patterns.
|
|
|
|
### Init task pattern
|
|
|
|
Init tasks are useful for performing initialization steps that can't be more easily
|
|
accomplished using [`template`](/nomad/docs/job-specification/template) or
|
|
[`artifact`](/nomad/docs/job-specification/artifact), like waiting on other services
|
|
or performing complex initialization.
|
|
|
|
In the following example, the init task will block the main task from starting
|
|
until the upstream database service is listening on the expected port:
|
|
|
|
```hcl
|
|
task "wait-for-db" {
|
|
lifecycle {
|
|
hook = "prestart"
|
|
sidecar = false
|
|
}
|
|
|
|
driver = "exec"
|
|
config {
|
|
command = "sh"
|
|
args = ["-c", "while ! nc -z db.service.local.consul 8080; do sleep 1; done"]
|
|
}
|
|
}
|
|
|
|
task "main-app" {
|
|
...
|
|
}
|
|
```
|
|
|
|
### Companion sidecar pattern
|
|
|
|
Companion or sidecar tasks run alongside the main task to perform an auxiliary
|
|
task. Common examples include proxies and log shippers. These tasks benefit from
|
|
running in the same task group because of tighter filesystem and networking
|
|
coupling.
|
|
|
|
```hcl
|
|
task "fluentd" {
|
|
lifecycle {
|
|
hook = "poststart"
|
|
sidecar = true
|
|
}
|
|
|
|
driver = "docker"
|
|
config {
|
|
image = "fluentd/fluentd"
|
|
}
|
|
|
|
template {
|
|
destination = "local/fluentd.conf"
|
|
data = ...
|
|
}
|
|
}
|
|
|
|
task "main-app" {
|
|
...
|
|
}
|
|
```
|
|
|
|
### Cleanup task pattern
|
|
|
|
Poststop tasks run after the main tasks have stopped. They are useful for performing
|
|
post-processing that isn't available in the main tasks or for recovering from
|
|
failures in the main tasks.
|
|
|
|
The example below shows a chatbot which posts a notification when the main tasks
|
|
have stopped:
|
|
|
|
```hcl
|
|
task "main-app" {
|
|
...
|
|
}
|
|
|
|
task "announce" {
|
|
lifecycle {
|
|
hook = "poststop"
|
|
}
|
|
|
|
driver = "docker"
|
|
config {
|
|
image = "alpine/httpie"
|
|
command = "http"
|
|
args = [
|
|
"POST",
|
|
"https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
|
|
"text='All done!'"
|
|
]
|
|
}
|
|
}
|
|
```
|