docs: lifecycle stanza (#7493)

website/data/docs-navigation.js

@@ -136,6 +136,7 @@ export default [
       'ephemeral_disk',
       'group',
       'job',
+      'lifecycle',
       'logs',
       'meta',
       'migrate',

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
+
+<Placement groups={['job', 'group', 'task', 'lifecycle']} />
+
+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.

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` <code>([Lifecycle][]: nil)</code> - Specifies when a task is run
+  within the lifecycle of a task group.
+
 - `logs` <code>([Logs][]: nil)</code> - 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'