Using deployment hooks

What are Deployment Hooks and how do they work?

The Deploy system supports hooks that are started before or after deployment.
These hooks are executable files of any kind (e.g. shell scripts, Linux executable binaries).

Hooks are not executed when a deployment process is triggered by automatic processes such as scaling out an instance of a autoscaling group because of high load. They are only executed through calling r3 deploy.

General usage instructions

(For your reference: general usage instructions for the cloud managment tool suite r3)

The hook system is disabled by default and can be activated and controlled via options. You can find the details below.

Known Caveats

Git

  • Using git commands in your deployment hooks needs extra steps. Due to CVE-2022-24765 git added a check for file ownership, but the local repositories are owned by a different user in the deployment process. You can work around this by using the following commands inside of your hook, before calling any git commands (adjust the <git path> to your local repository, usually /srv/<company-project-role>:

    1 2 export GIT_CONFIG_GLOBAL="$(mktemp)" git config --global safe.directory "<git path>"

Step 1 - Show help context

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 ~$ r3 deploy -h usage: r3 deploy [-h] [-r ROLE] [--init-hook [INITHOOKDIR]] [--pre-hook [PREHOOKDIR]] [--post-hook [POSTHOOKDIR]] [--rev REV] [-n] [-m] [--sanity-check] [--list-roles | --list-sources] [-d] [-q] optional arguments: -h, --help show this help message and exit -r ROLE, --role ROLE Server role to work on --init-hook [INITHOOKDIR] Run initial hook scripts in default path "init-hook.d/" or given directory (optional) --pre-hook [PREHOOKDIR] Run pre-deploy hook scripts in default path "pre-hook.d/" or given directory (optional) --post-hook [POSTHOOKDIR] Run post-deploy hook scripts in default path "post-hook.d/" or given directory (optional) --rev REV Specify tag/branch to clone (git deployment only!) -n, --skip-update Skip update of source code (optional) -m, --skip-deploy Skip distribution of source code (optional) --sanity-check only check the sanity of all components --list-roles List deployable roles and exit --list-sources List source details and exit -d, --debug Run in debug mode. -q, --quiet Run in quiet mode (only errors are shown).

Step 2 - Use hooks during deployment

1 r3 deploy --pre-hook [directory]

The --init-hook option enables the hooks to be started before updating the sources and sets the directory with init-hooks. If no explicit path is specified, the path init-hook.d is used in the project directory (e.g. git-root).

The --pre-hook option enables the hooks to be started before deploying and sets the directory with pre-hooks. If no explicit path is specified, the path pre-hook.d is used in the project directory (e.g. git-root).

The --post-hook option enables the hooks to be started after deployment and sets the directory with post hooks. If no explicit path is specified, the path post-hook.d is used in the project directory (eg git-root).

Hooks are valid only under the following conditions:

  • The executable flag of the file of the hook is set. The flag must already be set in your deployment before r3 deploy copies it to us.

    • If you are using Windows and git, use "git add --chmod=+x 00_somehook.sh" to set the flag.

  • The filename starts with a two-digit number (00-99) followed by a _ (underscore), e.g. 00_firsthook10_otherhook.sh

The hooks will run in the context of the project user on the natgw/jump server/bastion host. You can use any command in the hook that you can also use manually.

The hooks are called with the following options:

  • -p project: project name

  • -r role: server group name (e.g. web)

  • -e environment: environment name (e.g. test)

Example Hook:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 #!/bin/bash source /usr/local/lib/helper.sh function usage() { echo "${SCRIPT} [-r role] [-p project] [-e environment] [-q|-d] [-h]" echo " -h : print this help" echo " -r role : server role" echo " -p project : project name" echo " -e environment : environment name" exit 1 } # iterate options while getopts ':hr:p:e:' opt; do case "${opt}" in "r") role="${OPTARG}" ;; "p") project="${OPTARG}" ;; "e") environment="${OPTARG}" ;; "h") usage ;; ":") log error "Missing argument for option ${OPTARG}" usage ;; *) log error "Unknown option ${opt}" usage ;; esac done # print given project, environment and role echo "${project}-${environment}-${role}" # iterate all servers with given role in current project and run a command for target in $(get-instances-by-role "${role}" --output text | awk -F ' ' '{print$2}' | grep -v 'ip'); do # connect to server and run cache.php if ssh "${target}" php /var/www/cache.php; then # if command run successfully on one server skip all other break fi done # do some more stuff

Related tutorials

Related components