Aspect infrastructure lifecycle hooks

About

This document provides an overview of Aspect's Infrastructure Lifecycle Hooks.

In general, hooks allow you to modify the behavior of Aspect's systems by executing code you provide (in the form of shell scripts or executable files) at various points.

High level overview

Our hooks are grouped by namespace, then by hook name. Each hook is implemented by placing a shell script or executable file named after the hook into the desired namespace directory. For example, to implement the pre-bootstrap hook for runners, you would create an executable or shell script named pre-bootstrap and place it into the runners directory in the hooks bucket (aw-hooks-HASH).

We can provide an example implementation in that can be copied into the hooks bucket named aw-hooks-HASH set up during your Aspect Workflows installation. The name of this bucket is stable after terraform apply. The examples themselves do nothing except logging a brief message.

How to write a hook

While an in-depth overview of implementing the various methods of creating executables in out of scope of this document, the simplest means of creating a shell script is:

1. Create an empty text file with your editor of choice named after the hook you would like to implement.
2. Add a Shebang statement to the first line (see the first line of the example below). See also: https://en.wikipedia.org/wiki/Shebang_(Unix)
3. Add commands/statements to the file.
4. Set the executable bit on the file:

   $ chmod 755 ./path/to/your/file

A minimal shell script:

#!/usr/bin/env bash
echo "Hello world!"

Best practices while implementing hooks

1. Fail fast by leveraging bash settings:

   set -o errexit -o errtrace -o pipefail -o nounset

2. Use shellcheck to validate your script.

Additional References

There is a wealth of material on bash scripting, but here are some of our favorites:

• Bash Reference Manual
• Advanced Bash Scripting Guide

Runner lifecycle hooks (the runners namespace)

Runner lifecycle hooks are copied from the hooks bucket (aw-hooks-HASH) during the bootstrapping process. Note that everything in the directory will be copied, recursively, prior to execution.

The following hooks are available for runners:

• pre-bootstrap
• post-bootstrap

Hooks can also be targeted to run on a particular runner group. This can be performed by placing executable files or shell scripts named after the hook in the pre-created runner group directory within the hooks bucket. Take for example the following file structure:

$ tree -n hooks
hooks
├── README.md
└── runners
    ├── default
    │   ├── post-bootstrap
    │   ├── pre-bootstrap
    │   └── README.md
    ├── post-bootstrap
    ├── pre-bootstrap
    └── README.md

On a runner in the default runner group, during the pre-bootstrap phase, the global hook will be executed first, followed by the runner-specific one.

pre-bootstrap

Supported Location(s):

• aw-hooks-HASH/runners/pre-bootstrap
• aw-hooks-HASH/runners/RUNNER_GROUP/pre-bootstrap

This hook is executed prior to the execution of Aspect's bootstrapping logic. The current working directory when the hook is executed is the hook's dirname.

Note that no users or other utilities have been configured at this point.

post-bootstrap

Supported Location(s):

• aw-hooks-HASH/runners/post-bootstrap
• aw-hooks-HASH/runners/RUNNER_GROUP/post-bootstrap

This hook is executed following the execution of Aspect's bootstrapping logic but prior to the runner taking any CI jobs. The current working directory when the hook is executed is the hook's dirname.