Hooks

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

Hooks can be used to execute commands before or after any lifecycle operation. This can be useful to do things such as perform a security scan on an image, run database migrations on a deploy, etc.

Hooks enable these custom lifecycle operations to be performed while retaining the standard Waypoint workflow of up or dedicated commands build, deploy, release.

Hooks can be configured for build, registry, deploy, and release operations.

Configuration

Hooks are configured in the stanza of the operation they should run before or after. Hooks are supported in build, registry, deploy, and release stanzas.

Example waypoint.hcl:

project = "hooks-example"

app "hooks-example" {
    build {
        use "pack" {}
        hook {
            when = "before"
            command = ["./audit-log.sh", "build starting"]
            on_failure = "continue"
        }
        hook {
            when = "after"
            command = ["./audit-log.sh", "build finished"]
        }
    }
    deploy {
        use "docker" {}
        hook {
            when = "before"
            command = ["./audit-log.sh", "deploy starting"]
            on_failure = "fail"
        }
        hook {
            when = "after"
            command = ["./audit-log.sh", "deploy finished"]
        }
    }
}

Example audit-log.sh:

#!/bin/bash
echo `date` $1 >> audit-log.txt

Reference the hook configuration stanza documentation for details on all the fields a hook has and which are required.

Execution Environment

Hooks are executed alongside the Waypoint operation, most commonly within an on-demand runner. For this reason, you may may need to add additional binaries and files to the OCI image used to launch the on-demand runner.

Hooks are not executed in the app deployment platform. Therefore, operations such as database migrations or scripts that must be run within the context of a deploy should use some other mechanism for execution.

Note: waypoint exec will not operate on the current deployment within a hook, because the deployment is not successful until the hook itself is successful. waypoint exec from a hook will instead execute in the context of the previous deployment. We will look at ways in the future to enable this sort of behavior.

Execution Order

Hooks are excuted in the order they're defined in the configuration file for the when value they match. For example: all "before" hooks will be executed in order that they are defined.

Hooks are executed when the operation they're defined in is executed. For example, a registry hook will not be executed during a waypoint build -push=false command because -push=false configures Waypoint to not execute the registry push operation.

Failure Behavior

When a hook fails, it will fail its associated operation by default. This behavior can be configured with the on_failure option.

This has the often desired effect of making the result of that operation unusable by other operations. For example, an "after" hook failing for a "build" will make that artifact unavailable for future deployment operations even if the build itself succeeded.

If on_failure is set to "continue," then hook failure is ignored and does not affect the overall success or failure of the associated operation.

Examples of this are shown in the configuration section above.