Custom hooks

You can provide custom hooks by placing plain JavaScript files, with .js file extension, into the hooks directory. Each file must export a hook provider object. Takomo uses the provider to initialize the actual hook.

You can use all language features available in Node 14.4.0.

Hook provider

Hook provider has the following properties:

Key

Required

Type

Description

type

yes

string

Type of the hook

init

yes

function

A function that initializes the hook with properties given in a stack group or stack configuration file. The function can be either synchronous or asynchronous, and must return an instantiated hook object.

Hook

Hook has the following properties:

Key

Required

Type

Description

execute

yes

function

A function that is invoked with an hook input object when the hook is executed. The function can be synchronous or asynchronous and must return a hook output.

Hook Input

A hook input is an object that is passed to hook's execute function. It has the following properties:

Key

Required

Type

Description

stage

yes

string

Current stack operation stage. Possible values are: before, after

operation

yes

string

Current stack operation. Possible values are: create, update, delete

status

yes

string

Current stack operation status. Possible values are: success, failed, cancelled This is defined only when the stage is after.

variables

yes

object

Mutable variables object containing command line and environment variables. The hook can modify existing variables and add new ones. After the hook is completed, the same variables object is passed to the subsequent hooks which can then access its contents. The variables are available also in the stack's template file.

ctx

yes

object

Command context object

Hook Output

A hook output is a value returned from hook's execute function. It is used to determine if the hook execution was successful and to share data between hooks. It can be either a boolean, an Error which is always considered as failure, or a detailed object with the following properties:

Key

Required

Type

Description

success

yes

boolean

A boolean determining if the hook execution was successful.

message

no

string

An informative message about the hook execution outcome.

value

no

any

A value to be exposed to other hooks.

Sharing data between hooks

Hooks can expose values to other hooks by returning a hook output object. Takomo stores the returned value with a hook's name in a mutable variables object that it then passes to the subsequent hooks. Takomo discards the mutable variables object after the stack operation completes, which means the exposed data is not visible to hooks executed in other stacks.

Examples

Here are a few examples of custom hooks.

Simple custom hook

This example hook prints some debug information to the console.

Our file structure looks like this:

.
├─ stacks
│ └─ my-stack.yml
├─ hooks
│ └─ debug.js
└─ templates
└─ my-stack.yml

The hook provider defined in hooks/debug.js looks like this:

hooks/debug.js
module.exports = {
type: "debug",
init: (props) => {
console.log("Initialize debug hook")
return {
execute: (input) => {
console.log("Execute debug hook!")
console.log(`Stage: ${input.stage}`)
console.log(`Operation: ${input.operation}`)
console.log(`Status: ${input.status}`)
console.log(JSON.stringify(props, null, 2))
return {
message: "OK",
success: true,
value: "Did some debugging"
}
}
}
}
}

Our custom hook is used in the stack configuration like so:

stacks/my-stack.yml
hooks:
- name: my-hook
type: debug

When executed, the hook exposes string "Did some debugging" in the mutable variables object.

Sharing data between hooks

This example shows how you can share data between hooks.

Our file structure looks like this:

.
├─ stacks
│ └─ my-stack.yml
├─ hooks
│ ├─ first.js
│ └─ second.js
└─ templates
└─ my-stack.yml

There are two custom hooks located in the hooks dir.

hooks/first.js
module.exports = {
type: "first",
init: (props) => {
return {
execute: (input) => {
return {
message: "OK",
success: true,
value: "My greeting to the next hook"
}
}
}
}
}

The first hook returns a hook output object that contains a greeting to other hooks in the value property.

hooks/second.js
module.exports = {
type: "second",
init: (props) => {
return {
execute: (input) => {
const greeting = input.variables.hooks.firstHook
// Do something with the greeting here...
return true
}
}
}
}

The second hook reads the greeting from the input argument.

And this is how you glue everything together in a stack configuration file:

template: my-stack.yml
regions: eu-west-1
hooks:
- name: firstHook
type: first
- name: secondHook
type: second

The hooks property defines two hooks, one of each type. Takomo executes the hooks in order they are defined.