diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index e90971a12..95ae65bef 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -136,6 +136,7 @@ export default [ 'ephemeral_disk', 'group', 'job', + 'lifecycle', 'logs', 'meta', 'migrate', diff --git a/website/pages/docs/job-specification/lifecycle.mdx b/website/pages/docs/job-specification/lifecycle.mdx new file mode 100644 index 000000000..cc94fca6e --- /dev/null +++ b/website/pages/docs/job-specification/lifecycle.mdx @@ -0,0 +1,61 @@ +--- +layout: docs +page_title: lifecycle Stanza - Job Specification +sidebar_title: lifecycle +description: The "lifecycle" stanza configures when a task is run within the lifecycle of a task group +--- + +# `lifecycle` Stanza + + + +The `lifecycle` stanza configures when a task is run within the lifecycle of a task group. + +Main tasks are tasks that do not have a `lifecycle` stanza. +Lifecycle task hooks are run in relation to the main tasks. +Tasks can be run as Prestart Hooks, which ensures the prestart task is run before the main tasks are run. + +Tasks can be run with an additional parameter to indicate that they are sidecars, which ensures +that they are running over the duration of the whole task group. This will allow you to run +a long-lived task in a task group for a batch job. The absence of the sidecar flag +indicates that the task is ephemeral and the task will not be restarted if it completes successfully. +This allows you to run an ephemeral prestart task in a task group for a service job, +which can serve as initialization that occurs before the main services are started. + +```hcl +job "docs" { + group "example" { + + task "init" { + lifecycle { + hook = "prestart" + } + ... + } + + task "logging" { + lifecycle { + hook = "prestart" + sidecar = true + } + ... + } + + task "main" { + ... + } + + } +} +``` + +## `lifecycle` Parameters + +- `hook` `(string: "prestart")` - Specifies when a task should be run within + the lifecycle of a group. Currently only Prestart Hooks are supported. + +- `sidecar` `(bool: false)` - Controls whether or not 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 it terminates, it will be + restarted as long as the task group is running in its allocation. diff --git a/website/pages/docs/job-specification/task.mdx b/website/pages/docs/job-specification/task.mdx index 9d846d737..3990e68fe 100644 --- a/website/pages/docs/job-specification/task.mdx +++ b/website/pages/docs/job-specification/task.mdx @@ -67,6 +67,9 @@ job "docs" { the task group. If set to true, when the leader task completes, all other tasks within the task group will be gracefully shutdown. +- `lifecycle` ([Lifecycle][]: nil) - Specifies when a task is run + within the lifecycle of a task group. + - `logs` ([Logs][]: nil) - Specifies logging configuration for the `stdout` and `stderr` of the task. @@ -197,6 +200,7 @@ task "server" { [env]: /docs/job-specification/env 'Nomad env Job Specification' [meta]: /docs/job-specification/meta 'Nomad meta Job Specification' [resources]: /docs/job-specification/resources 'Nomad resources Job Specification' +[lifecycle]: /docs/job-specification/lifecycle 'Nomad lifecycle Job Specification' [logs]: /docs/job-specification/logs 'Nomad logs Job Specification' [service]: /docs/job-specification/service 'Nomad service Job Specification' [vault]: /docs/job-specification/vault 'Nomad vault Job Specification'