github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/job-specification/lifecycle.mdx (about)

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