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 an 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>:

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

Step 1 - Show help context

~$ 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

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:

Related tutorials

Related components

 

 


root360 Knowledge Base - This portal is hosted by Atlassian (atlassian.com | Privacy Policy)