Hooks are used to perform actions in different stages of stack operations. You can use them, for example, to compile and package lambda functions or notify whenever a deployment completes.
There can be different types of hooks. When configuring a hook, you give it a name and specify which hook type it is.
Hooks are executed in the order they are defined. If one hook fails, the whole stack operation with any remaining hooks is aborted and deemed as a failure. Hook configuration is used to determine when the hook should be executed. For example, you can configure the hook to be executed before an existing stack is updated.
You configure hooks in stack configuration using following properties.
|name||yes||string||Name of the hook.|
|type||yes||string||Type of the hook.|
|operation||no||string or string||Stack operations during which the hook is executed. Supported values are:|
|stage||no||string or string||Stack operation stages during which the hook is executed.|
|status||no||string or string||Stack operation results during which the hook is executed.|
In addition to the properties mentioned above, different hook types can have properties of their own.
Sharing Data Between Hooks
Hooks can expose values to other hooks by returning a detailed hook output object. The returned value is stored with a hook's name in a mutable variables object that is then passed to the subsequent hooks. The mutable variables object is discarded after the current stack operation is completed. The exposed data is not visible to hooks executed in other stacks.
There is one built-in hook:
Executes a shell command given in command property. Exposes the following environment variables to the shell command:
|TKM_COMMAND_STAGE||The current stack operation stage.|
|TKM_COMMAND_OPERATION||The current stack operation.|
|TKM_COMMAND_STATUS||The current stack operation status, not present in before stage|
Any output the hook prints to the stdout is captured and exposed for other hooks.
Here are the properties available for Command hook:
|type||yes||string||Type of the hook, this must be cmd.|
|name||yes||string||Name of the hook.|
|command||yes||string||Shell command to execute.|
|cwd||yes||string||The working directory from where the shell command is executed.|
Implementing Custom Hooks
Hook provider has the following properties:
|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 has the following properties:
|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 has the following properties:
|stage||yes||string||Current stack operation stage. Possible values are:|
|operation||yes||string||Current stack operation. Possible values are:|
|status||yes||string||Current stack operation status. Possible values are:|
|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. If the stack's template is .hbs file, the same variables are also usable there.|
|ctx||yes||string||Command context object|
Hook output 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:
|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.|
This example hook prints some debug information to the console.
Our file structure looks like this:
The hook provider defined in hooks/debug.js looks like this:
Our custom hook is used in the stack configuration like so:
When executed, the hook exposes string "Did some debugging" in the mutable variables object.