Lifecycle hooks
Executing commands before and after updating¶
Note
These are shell commands executed with sh, and therefore require the container to provide the sh
executable.
DO NOTE: If the container is not running then lifecycle hooks can not run and therefore the update is executed without running any lifecycle hooks.
It is possible to execute pre/post-check and pre/post-update commands inside every container updated by watchtower.
- The pre-check command is executed for each container prior to every update cycle.
- The pre-update command is executed before stopping the container when an update is about to start.
- The post-update command is executed after restarting the updated container
- The post-check command is executed for each container post every update cycle.
This feature is disabled by default. To enable it, you need to set the option
--enable-lifecycle-hooks on the command line, or set the environment variable
WATCHTOWER_LIFECYCLE_HOOKS to true.
Specifying update commands¶
The commands are specified using docker container labels, the following are currently available:
| Type | Docker Container Label |
|---|---|
| Pre Check | com.centurylinklabs.watchtower.lifecycle.pre-check |
| Pre Update | com.centurylinklabs.watchtower.lifecycle.pre-update |
| Post Update | com.centurylinklabs.watchtower.lifecycle.post-update |
| Post Check | com.centurylinklabs.watchtower.lifecycle.post-check |
These labels can be declared as instructions in a Dockerfile (with some example .sh files) or be specified as part of
the docker run command line:
LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh"
LABEL com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh"
docker run -d \
--label=com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" \
--label=com.centurylinklabs.watchtower.lifecycle.pre-update="/dump-data.sh" \
--label=com.centurylinklabs.watchtower.lifecycle.post-update="/restore-data.sh" \
someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check="/send-heartbeat.sh" \
Timeouts¶
The timeout for all lifecycle commands is 60 seconds. After that, a timeout will occur, forcing Watchtower to continue the update loop.
Pre- or Post-update timeouts¶
For the pre-update or post-update lifecycle command, it is possible to override this timeout to
allow the script to finish before forcefully killing it. This is done by adding the
label com.centurylinklabs.watchtower.lifecycle.pre-update-timeout or post-update-timeout respectively followed by
the timeout expressed in minutes.
If the label value is explicitly set to 0, the timeout will be disabled.
Execution failure¶
The failure of a command to execute, identified by an exit code different than 0 or 75 (EX_TEMPFAIL), will not prevent watchtower from updating the container. Only an error log statement containing the exit code will be reported.