github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/lifecycle.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: lifecycle Stanza - Job Specification
     4  description: |-
     5    The "lifecycle" stanza configures when a task is run within the lifecycle of a
     6    task group
     7  ---
     8  
     9  # `lifecycle` Stanza
    10  
    11  <Placement groups={['job', 'group', 'task', 'lifecycle']} />
    12  
    13  The `lifecycle` stanza is used to express task dependencies in Nomad by
    14  configuring when a task is run within the lifecycle of a task group.
    15  
    16  Main tasks are tasks that do not have a `lifecycle` stanza. Lifecycle task hooks
    17  specify when other tasks are run in relation to the main tasks.
    18  There are three different lifecycle hooks, indicating when a task is started:
    19  
    20  - prestart tasks are started immediately
    21  - poststart tasks are started after the main tasks are running
    22  - poststop tasks are started after the main tasks are dead
    23  
    24  Tasks can be run with an additional parameter indicating whether they are ephemeral
    25  tasks or "sidecar" tasks that are expected to run for the duration of the main tasks.
    26  The absence of the sidecar flag indicates that the task is ephemeral
    27  and should not be restarted if it completes successfully.
    28  
    29  Learn more about [Nomad's task dependencies][learn-taskdeps].
    30  
    31  ## `lifecycle` Parameters
    32  
    33  - `hook` `(string: <required>)` - Specifies when a task should be run within
    34    the lifecycle of a group. The following hooks are available:
    35  
    36    - `prestart` - Will be started immediately. The main tasks will not start until
    37      all `prestart` tasks with `sidecar = false` have completed successfully.
    38    - `poststart` - Will be started once all main tasks are running.
    39    - `poststop` - Will be started once all main tasks have stopped successfully
    40      or exhausted their failure [retries](/docs/job-specification/restart).
    41  
    42  - `sidecar` `(bool: false)` - Controls whether a task is ephemeral or
    43    long-lived within the task group. If a lifecycle task is ephemeral
    44    (`sidecar = false`), the task will not be restarted after it completes successfully. If a
    45    lifecycle task is long-lived (`sidecar = true`) and terminates, it will be
    46    restarted as long as the allocation is running.
    47  
    48  [learn-taskdeps]: https://learn.hashicorp.com/collections/nomad/task-deps
    49  
    50  ## Lifecycle Examples
    51  
    52  The following include examples of archetypal lifecycle patterns.
    53  
    54  ### Init Task Pattern
    55  
    56  Init tasks are useful for performing initialization steps that can't be more easily
    57  accomplished using [`template`](/docs/job-specification/template) or
    58  [`artifact`](/docs/job-specification/artifact), like waiting on other services
    59  or performing complex initialization.
    60  
    61  In the following example, the init task will block the main task from starting
    62  until the upstream database service is listening on the expected port:
    63  
    64  ```hcl
    65    task "wait-for-db" {
    66      lifecycle {
    67        hook = "prestart"
    68        sidecar = false
    69      }
    70  
    71      driver = "exec"
    72      config {
    73        command = "sh"
    74        args = ["-c", "while ! nc -z db.service.local.consul 8080; do sleep 1; done"]
    75      }
    76    }
    77  
    78    task "main-app" {
    79      ...
    80    }
    81  ```
    82  
    83  ### Companion Sidecar Pattern
    84  
    85  Companion or sidecar tasks run alongside the main task to perform an auxiliary
    86  task. Common examples include proxies and log shippers. These tasks benefit from
    87  running in the same task group because of tighter filesystem and networking
    88  coupling.
    89  
    90  ```hcl
    91    task "fluentd" {
    92      lifecycle {
    93        hook = "poststart"
    94        sidecar = true
    95      }
    96  
    97      driver = "docker"
    98      config {
    99        image = "fluentd/fluentd"
   100      }
   101  
   102      template {
   103        destination = "local/fluentd.conf"
   104        data = ...
   105      }
   106    }
   107  
   108    task "main-app" {
   109      ...
   110    }
   111  ```
   112  
   113  ### Cleanup Task Pattern
   114  
   115  Poststop tasks run after the main tasks have stopped. They are useful for performing
   116  post-processing that isn't available in the main tasks or for recovering from
   117  failures in the main tasks.
   118  
   119  The example below shows a chatbot which posts a notification when the main tasks
   120  have stopped:
   121  
   122  ```hcl
   123    task "main-app" {
   124      ...
   125    }
   126  
   127    task "announce" {
   128      lifecycle {
   129        hook = "poststop"
   130      }
   131  
   132      driver = "docker"
   133      config {
   134        image = "alpine/httpie"
   135        command = "http"
   136        args = [
   137          "POST",
   138          "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
   139          "text='All done!'"
   140        ]
   141      }
   142    }
   143  ```