Developing hooks - CloudFormation Command Line Interface

Developing hooks

Hooks proactively inspect the configuration of your AWS resources before provisioning. If non-compliant resources are found, AWS CloudFormation returns a failure status and either fails the operation or provides a warning and allows the operation to continue based on the hook failure mode. You can use pre-built hooks or build your own hooks using the CloudFormation Command Line Interface (CloudFormation CLI).

You can use hooks to proactively enforce a variety of requirements and guidelines. For example, a security-related hook might verify security groups for the appropriate inbound and outbound traffic rules for your Amazon Virtual Private Cloud (Amazon VPC). A cost-related hook might restrict development environments to only use smaller Amazon Elastic Compute Cloud (Amazon EC2) instance types. A hook designed for data availability could enforce automatic backups for Amazon Relational Database Service (Amazon RDS). All of these hooks can be registered and invoked in your accounts.

Characteristics of hooks

Characteristics of hooks include:

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

  • Automatic enforcement – Provide enforcement in your AWS 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 AWS CloudFormation registry.

Using the CloudFormation CLI to create hooks

Use the CloudFormation CLI to develop your hooks. The CloudFormation CLI is an open-source project that provides a consistent way to model and provision both AWS and third-party extensions using CloudFormation.

There are three major steps in developing a hook:

  1. Initiate

    To initiate a hook's project and its required files, use the init command and specify that you want to create a hook. For more information, see Initiating a hooks project for Java and Initiating a hooks project for Python.

  2. Model

    To model, author, and validate your hook schema, define the hook, its properties, and their attributes.

    The CloudFormation CLI creates empty handler functions which correspond to a specific hook invocation point. Add your own logic to these handlers to control what happens during your hook invocation at each stage of its target lifecycle. For more information, see Modeling hooks for Java and Modeling hooks for Python.

  3. Register

    To register a hook, submit your hook to be registered either as a private or a public third-party extension. Register your hook with the submit operation. For more information, see Registering hooks for Java and Registering hooks for Python.

    The following tasks are associated with registering your hook:

    1. Publish – hooks are published to the registry.

    2. Activate – hooks are activated when they're enabled in your account.

    3. Configure – hooks are configured when the type configuration invokes against stacks.

      There are two required type configuration properties:

      • TargetStacks is used to turn the hook on or off.

        • TargetStacks set to ALL turns the hook on for all stack operations.

        • TargetStacks set to NONE turns the hook off, so it doesn't apply to stack operations.

      • FailureMode determines how CloudFormation responds to a failure response.

        • FailureMode set to FAIL prevents the operation.

        • FailureMode set to WARN allows the operation to continue and sends a warning.

Overview

This section provides an overview for hooks and its terminology.

Hook

A hook is executable custom logic that automatically inspect resources before they're provisioned. Hooks are able to inspect the resources that CloudFormation is about to provision. If a hook finds any resource that doesn't comply with your organizational guidelines, they're able to prevent CloudFormation from continuing the provisioning process. With hooks, you can validate resource properties and invoke a warning, or prevent the provisioning operation, on non-compliant resources to reduce security and compliance risk, lower operational overhead, and optimize cost.

Hook targets

Hook targets are the destination where hooks are invoked. You can specify targets such as, CloudFormation resources, registry resources, or custom resource. For example, customers can author a hook targeting AWS::S3::Bucket resource. Hooks support an unlimited number of resource targets.

Invocation point

Invocation points are points in provisioning logic where hooks are invoked. CloudFormation supports pre-invocation points. Hooks are invoked before the provisioning logic for the target begins but won't invoke for skipped resources.

For example, a hook with an invocation point for AWS::S3::Bucket, will invoke before CloudFormation provisions your Amazon S3 bucket resource.

Target action

Target actions are the type of operation that your hook invokes at runtime. For example, if you specify a target action for CREATE on an AWS::S3::Bucket, your hook only invokes when creating an S3 bucket.

Valid values: CREATE | UPDATE | DELETE

Hook handlers

Invocation points and target actions specify the exact point where the hook is invoked. Hook handlers hosts executable custom logic for these points. For example, an invocation point of the CREATE operation uses a preCreate handler. Your code written in the hook handler will start any time targets and services perform a matching action.

Valid values: preCreate | preUpdate | preDelete

Important

Stacks operations that result in the status of UpdateCleanup will not invoke a hook. For example, during the following two scenarios, the hook's preDelete handler will not be invoked:

  • the stack is updated after removing one resource from the template.

  • a resource with the update type of replacement is deleted.

Hooks quotas

This section provides a list of quotas for hooks.

Category Quotas
Hooks per account 100
Hooks per resource 100
Versions per hook 100
Hook configuration size 300 KB
Note

The maximum amount of data that a hook’s configuration can store is 300 KB. This is in addition to all the constraints imposed on Configuration request parameter of SetTypeConfiguration operation.