Lifecycle Hooks

Stackery provides lifecycle hooks to enable custom functionality. For example, the postTemplateGeneration event is sent to a hook function near the end of the deployment preparation phase, and the function receiving the event can modify the Stackery generated resource template to add resources Stackery does not natively support.

Hooks are AWS Lambda functions that are run in response to events that occur while using Stackery. Some lifecycle events require a response while others do not. For events that require a response, the hooks function must return within 30 seconds.

Each stack may have one hook function, and this function must be maintained separately from the stack. The hook function can be deployed and maintained using any strategy or tooling, including as part of an independent Stackery stack. The Lambda function must also have a permission granting Stackery the ability to invoke the function.

Once a function has been provisioned and the proper permissions have been granted, the function’s AWS identifier (ARN) must be added as a property of the stack.

The following is a list of the Stackery lifecycle events:

postTemplateGeneration

Creating A Function

You may use any tools and frameworks to create the hook function. The function will be passed an object with an event property. The event property informs the hook function which type of event it is. Events may have additional properties, please see each event’s documentation for details.

Granting Stackery Permission To Invoke The Hook Function

Stackery must have permission to invoke the hook function. This permission is provided by adding a resource-based policy to the function granting a specific role within Stackery’s AWS account the ability to invoke the function.

Granting Permission Using Stackery

If the hook function is deployed via Stackery there is a simple mechanism for adding the permission to the function. Using your editor, open the Stackery/stack.json file of the stack with the function. Locate the function by its name or ID. Add the following permissions property:

{
  "id": "abcd1234",
  "type": "function",
  "name": "My Hook",
  ...
  "permissions": [
    {
      "awsAccountId": "905809316366",
      "role": "stackery/invoke-user-hooks"
    }
  ]
}

When the stack is next deployed, the function will be invokable by the special “invoke-user-hooks” Stackery IAM role from Stackery’s AWS account (905809316366).

Granting Permission Without Stackery

Granting permission without Stackery requires a few more pieces of information and capabilities. You must have:

The full AWS identifier (ARN) of the provisioned hook function
AWS API access credentials with permission to invoke the Lambda AddPermission action on the hook function
AWS CLI tool

To add the required permission run the following command:

$ AWS_ACCESS_KEY_ID=<access key id> AWS_SECRET_ACCESS_KEY=<secret access key> aws --region <region of function> lambda add-permission --function-name <hook function ARN> --action lambda:InvokeFunction --statement-id stackeryInvokeUserHook --principal "arn:aws:iam::905809316366:role/stackery/invoke-user-hooks"

Add Hook To Stack

Now that the function is ready to be used as a Stackery hook the last step is to inform Stackery to send events to the hook function for a stack. Open Stackery/stack.json for the stack that will send lifecycle events. The stack structure will be an object, usually with one key: “nodes”. Add a second key, “hook”, with the AWS identifier (ARN) of the hook function. For example:

{
  "nodes": [
    ...
  ],
  "hook": "arn:aws:lambda:us-west-2:59457274562:function:my-custom-hook"
}

Commit the changes and push them to the git repository for the stack.

Test

To test the hook function try preparing a deployment of the stack. Your function should receive events as the stack is prepared. Stackery will report an error through the dashboard or command line if it fails to invoke the hook function or the function takes too long to respond.

API Reference