AWS CloudFormation Hooks concepts
The following terminology and concepts are central to your understanding and use of AWS CloudFormation Hooks:
Hook
A Hook contains code that is invoked immediately before CloudFormation creates, updates, or deletes stacks or specific resources. It can also be invoked during a create change set operation. Hooks can inspect the template, resources, or change set that CloudFormation is about to provision. Additionally, Hooks can be invoked immediately before the Cloud Control API creates, update, or deletes specific resources.
If a Hook identifies any configurations that don't comply with the
organizational guidelines defined in your Hook logic, then you may choose to
either WARN users or FAIL, preventing CloudFormation from
provisioning the resource.
Hooks have the following characteristics:
-
Proactive validation – Reduces risk, operational overhead, and cost by identifying non-compliant resources before they're created, updated, or deleted.
-
Automatic enforcement – Provides enforcement in your AWS account to prevent non-compliant resources from being provisioned by CloudFormation.
Failure mode
Your Hook logic can return success or failure. A success response will allow the operation to continue. A failure for non-compliant resources can result in the following:
-
FAIL– Stops provisioning operation. -
WARN– Allows provisioning to continue with a warning message.
Creating Hooks in WARN mode is an effective way to monitor
Hook behavior without affecting stack operations. First, activate Hooks
in WARN mode to understand which operations will be impacted. After you
have assessed the potential effects, you can switch the Hook to
FAIL mode to start preventing non-compliant operations.
Hook targets
Hook targets specify the operations that a Hook will evaluate. These can be operations on:
-
Resources supported by CloudFormation (
Resources) -
Stack templates (
STACK) -
Change sets (
CHANGE_SET) -
Resources supported by the Cloud Control API (
CLOUD_CONTROL)
You define one or more targets that specify the broadest operations that the
Hook will evaluate. For example, you can author a Hook targeting
RESOURCES to target all AWS resources and STACK to
target all stack templates. You can also apply filters to narrow down the scope of the
Hook to the exact operation you want to evaluate. For more information, see
AWS CloudFormation Hooks stack level filters and AWS CloudFormation Hooks target filters.
Target actions
Target action is the type of operation that triggers a Hook. The action can
be CREATE, UPDATE, or DELETE.
Note
When using RESOURCE, STACK, and
CLOUD_CONTROL Hook targets, all target actions are
applicable. When using CHANGE_SET Hook targets, only the
CREATE action is applicable.
Hook handler
For custom Hooks, this is the code that handles evaluation. It is associated
with a target invocation point and a target action that mark an exact point where a
Hook runs. You write handlers that host logic for these specific points. For
example, a PRE target invocation point with CREATE target
action makes a preCreate Hook handler. Code within the
Hook handler runs when a matching target invocation point and service are
performing an associated target action.
Valid values: (preCreate | preUpdate |
preDelete)
Important
Stack operations that result in the status of UpdateCleanup do not
invoke a Hook. For example, during the following two scenarios, the
Hook's preDelete handler is not invoked:
-
the stack is updated after removing one resource from the template.
-
a resource with the update type of replacement is deleted.
