Amazon CloudFormation Hooks concepts and terminology - Amazon CloudFormation Hooks
TerminologyCharacteristics of HooksHooks quotas
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon CloudFormation Hooks concepts and terminology

This section introduces fundamental terminology and concepts to help you get started with Amazon CloudFormation Hooks.

Hooks terminology

Amazon CloudFormation Hooks uses the following terminology in addition to common Amazon concepts and terminology.

Hook

A Hook contains code that is invoked immediately before CloudFormation creates, updates, or deletes specific resources. Hooks can inspect the resources that CloudFormation is about to provision. If any resources 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.

Hook target

Hook targets are the CloudFormation resources that you want to run a Hook against. They can be general resources that CloudFormation supports, or third-party resources in the registry. You specify targets while authoring a Hook. For example, you can author a Hook targeting the Amazon::S3::Bucket resource. A Hook can support multiple targets, and there is no limit on the number of resource targets.

target invocation point

Target invocation points are the exact point in the provisioning logic where Hooks run. CloudFormation supports a PRE (before) target invocation point. This means that you can write a Hook that runs before the provisioning logic for the target begins. For example, a Hook with a PRE target invocation point for an Amazon S3 target runs before the service starts provisioning an Amazon S3 bucket in your account.

target action

Target action is the type of operation that triggers a Hook. The action can be CREATE, UPDATE, or DELETE.

Valid values: (CREATE | UPDATE | DELETE)

Hook handler

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.

Characteristics of Hooks

Hooks have the following characteristics:

  • Proactive validation – Reduces risk, operational overhead, and cost by identifying noncompliant resources before they're created, updated, or deleted.

  • Automatic enforcement – Provides enforcement in your Amazon Web Services account to prevent noncompliant resources from being provisioned by CloudFormation.

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 resources.

  • WARN – Allows provisioning to continue with a warning message.

You can register your Hooks as private or third-party public extensions in the CloudFormation registry. For more information, see Using the Amazon CloudFormation registry.

Hooks quotas

For more information on Hooks quotas, see Amazon CloudFormation quotas.