Hook schema Hook configuration schema Using wildcards with Hook target names

Amazon CloudFormation Hooks structure overview

The properties and attributes of a Hook are defined in a Hook schema, which is a JSON-formatted text file. The following sections provide details of Hook schemas, including configuration schemas and using wildcards in Hook target names.

Hook schema

A Hook includes a Hook specification represented by a JSON schema and Hook handlers.

The first step in creating a Hook is modeling a schema that defines the Hook, its properties, and their attributes. When you initialize a Hook project using the CloudFormation CLI init command, a Hook schema file is created for you. Use this schema file as a starting point for defining the shape and semantics of your Hook.

Hook schema properties

The following schema is the structure for a Hook.


{
"typeName": "string",
    "description": "string",
    "sourceUrl": "string",
    "documentationUrl": "string",
    "definitions": {
        "definitionName": {
          . . .
        }
    },
    "typeConfiguration": {
        "properties": {
             "propertyName": {
                "description": "string",
                "type": "string",
                 . . .
            },
        },
    "required": [
        "propertyName"
         . . .
            ],
    "additionalProperties": false
    },
    "handlers": {
        "preCreate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preUpdate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preDelete": {
            "targetNames": [
            ],
            "permissions": [
            ]
        }
   },
   "additionalProperties": false
}

typeName

The unique name for your Hook. Specifies a three-part namespace for your Hook, with a recommended pattern of Organization::Service::Hook.

Note

The following organization namespaces are reserved and can't be used in your Hook type names:

Alexa
AMZN
Amazon
ASK
AWS
Custom
Dev

Required: Yes

Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

Minimum: 10

Maximum: 196

description

A short description of the Hook that's displayed in the CloudFormation console.

Required: Yes

sourceUrl

The URL of the source code for the Hook, if public.

Required: No

Maximum: 4096

documentationUrl

The URL of a page providing detailed documentation for the Hook.

Required: Yes

Pattern: ^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$

Maximum: 4096

Note

Although the Hook schema should include complete and accurate property descriptions, you can use the documentationURL property to provide users with more details, including examples, use cases, and other detailed information.

definitions

Use the definitions block to provide shared Hook property schemas.

It's considered a best practice to use the definitions section to define schema elements that can be used at multiple points in your Hook type schema. You can then use a JSON pointer to reference that element at the appropriate places in your Hook type schema.

Required: No

typeConfiguration

The definition of a Hook’s configuration data.

Required: Yes

properties

The properties of the Hook. All properties of a Hook must be expressed in the schema. Align the Hook schema properties with the Hook type configuration properties.

Note

Nested properties aren't allowed. Instead, define any nested properties in the definitions element, and use a $ref pointer to reference them in the desired property.

additionalProperties

additionalProperties must be set to false. All properties of a Hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

handlers

Handlers specify the operations which can initiate the Hook defined in the schema, such as Hook invocation points. For example, a preUpdate handler is invoked before the update operations for all specified targets in the handler.

Valid values: preCreate | preUpdate | preDelete

Note

At least one value must be specified for the handler.

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.

targetNames

A string array of type names that Hook targets. For example, if a preCreate handler has an AWS::S3::Bucket target, the Hook runs for Amazon S3 buckets during the preprovisioning phase.

TargetName

Specify at least one target name for each implemented handler.

Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

Minimum: 1

Required: Yes

Warning
SSM SecureString and Secrets Manager dynamic references are not resolved before they are passed to Hooks.

permissions

A string array that specifies the Amazon permissions needed to invoke the handler.

Required: Yes

additionalProperties

additionalProperties must be set to false. All properties of a Hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

Example Hooks schema

The Java and the Python walkthroughs use the following code example. The following is an example structure for a Hook called mycompany-testing-mytesthook.json.


{
    "typeName":"MyCompany::Testing::MyTestHook",
    "description":"Verifies S3 bucket and SQS queues properties before create and update",
    "sourceUrl":"https://mycorp.com/my-repo.git",
    "documentationUrl":"https://mycorp.com/documentation",
    "typeConfiguration":{
        "properties":{
            "minBuckets":{
                "description":"Minimum number of compliant buckets",
                "type":"string"
            },
            "minQueues":{
                "description":"Minimum number of compliant queues",
                "type":"string"
            },
            "encryptionAlgorithm":{
                "description":"Encryption algorithm for SSE",
                "default":"AES256",
                "type":"string"
            }
        },
        "required":[
            
        ],
        "additionalProperties":false
    },
    "handlers":{
        "preCreate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preUpdate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preDelete":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                "s3:ListBucket",
                "s3:ListAllMyBuckets",
                "s3:GetEncryptionConfiguration",
                "sqs:ListQueues",
                "sqs:GetQueueAttributes",
                "sqs:GetQueueUrl"
            ]
        }
    },
    "additionalProperties":false
}

Hook configuration schema

CloudFormation supports Hook configurations which are set by the Hook users. CloudFormation refers to this configuration schema at runtime when invoking a Hook in an Amazon Web Services account. Hooks are configured when the type configuration is set to initiate from the stacks. To enable your Hook to proactively inspect the configuration of your stack, set the TargetStacks to ALL, after the Hook has been registered and activated in your account. 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.

In this section

Hook configuration schema properties
Specifying target names, action, and invocation points for Hook targets

Hook configuration schema properties

The following schema is the structure for a Hook configuration schema.


{
    "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {
                ...
            }
            "TargetFilters": {
                ...
            }
        }
    }
}

HookConfiguration

Hook configuration supports activating or deactivating Hooks at stack level, failure modes, and Hook properties values.

The Hook configuration supports the following properties.

TargetStacks

If the mode is set to ALL, the Hook applies to all stacks in your account during a CREATE, UPDATE, or DELETE resource operation.

If the mode is set to NONE, the Hook won't apply to stacks in your account.

Valid values: ALL | NONE

FailureMode

This field tells the service how to treat Hook failures.

If the mode is set to FAIL, and the Hook fails, then the fail configuration stops provisioning resources and rolls back the stack.
If the mode is set to WARN and the Hook fails, then the warn configuration allows provisioning to continue with a warning message.

Valid values: FAIL | WARN

Properties

Specifies Hook runtime properties. These should match the shape of the properties supported by Hooks schema.

TargetFilters

Specifies the target filters for the Hook. You can use target filters to invoke the Hook only when specified target from the targets that the Hook is registered for in the Hook schema. For example, if a Hook targets AWS::S3::Bucket and AWS::DynamoDB::Table in the Hook schema, then target filters in the Hook configuration will apply only to those targets.

The target filter configuration supports the following properties.

Targets

An object array that specifies the list of targets to use for target filtering.

Each target in the targets array has the following properties.

TargetNames

The resource type name to target.

Actions

The action for the specified target.

Valid values: CREATE | UPDATE | DELETE

InvocationPoints

The invocation point for the specified target.

Valid values: PRE_PROVISION

Important

The Hook configuration schema doesn't support using the Targets object array in conjunction with the following TargetNames, Actions, and InvocationPoints list arrays. For more information, see Specifying target names, action, and invocation points for Hook targets.

TargetNames

A string array that specifies the resource type names to target.

Target names support concrete target names and full wildcard matching.

Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

Maximum: 50

Actions

A string array that specifies the target actions for the targets that you list in TargetNames.

Valid values: CREATE | UPDATE | DELETE

InvocationPoints

A string array that specifies the invocation points for the targets that you list in TargetNames.

Valid values: PRE_PROVISION

Specifying target names, action, and invocation points for Hook targets

You can use either the Targets object array to list specific target, action, and invocation point combinations, or you can use the individual TargetNames, Actions, and InvocationPoints list arrays to specify a list of target names, and the actions and invocation points that apply to all of those targets. The following example configurations have the same result:

Example 1: Using the Targets object array


{
   "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {},
            "TargetFilters":{
                 "Targets": [
                    {
                        "TargetName": "AWS::S3::Bucket",
                        "Action": "CREATE",
                        "InvocationPoint": "PRE_PROVISION"
                    },
                    {
                        "TargetName": "AWS::S3::Bucket",
                        "Action": "UPDATE",
                        "InvocationPoint": "PRE_PROVISION"
                    },
                    {
                        "TargetName": "AWS::DynamoDB::Table",
                        "Action": "CREATE",
                        "InvocationPoint": "PRE_PROVISION"
                    },
                    {
                        "TargetName": "AWS::DynamoDB::Table",
                        "Action": "UPDATE",
                        "InvocationPoint": "PRE_PROVISION"
                    }
                 ]               
            }
        }
   }
}

Example 2: Using the TargetNames, Actions, and InvocationPoints list arrays


{
   "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {},
            "TargetFilters":{
                "TargetNames": [
                    "AWS::S3::Bucket",
                    "AWS::DynamoDB::Table"
                ],
                "Actions": [
                    "CREATE",
                    "UPDATE"
                ],
                "InvocationPoints": [
                    "PRE_PROVISION"
                ]
            }
        }
   }
}

In these examples, the configuration that uses the list arrays is more concise, but both configurations set the Hook to be invoked only before a CREATE or UPDATE operation on AWS::S3::Bucket or AWS::DynamoDB::Table.

However, if you want to set the Hook to be invoked before CREATE operations only on AWS::S3::Bucket, and before UPDATE operations on AWS::DynamoDB::Table, you must use the Targets object array for more precise control over your Hook configuration. For example:

Example 3: Using Targets object array with different Actions for each TargetName


{
   "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {},
            "TargetFilters":{
                 "Targets": [
                    {
                        "TargetName": "AWS::S3::Bucket",
                        "Action": "CREATE",
                        "InvocationPoint": "PRE_PROVISION"
                    },
                    {
                        "TargetName": "AWS::DynamoDB::Table",
                        "Action": "UPDATE",
                        "InvocationPoint": "PRE_PROVISION"
                    }
                 ]               
            }
        }
   }
}

Using wildcards with Hook target names

You can use wildcards as part of the target name. You can use wildcard characters (* and ?) within your Hook target names. The asterisk (*) represents any combination of characters. The question mark (?) represents any single character. You can use multiple * and ? characters in a target name.

Example : Examples of target name wildcards in Hook schemas

The following example targets all resource types supported by Amazon S3.


{
...
    "handlers": {
       "preCreate": {
            "targetNames": [
                "AWS::S3::*"
            ],
            "permissions": []
       }
    }
...
}

The following example matches all resource types that have "Bucket" in the name.


{
...
    "handlers": {
       "preCreate": {
            "targetNames": [
                "AWS::*::Bucket*"
            ],
            "permissions": []
       }
    }
...
}

The AWS::*::Bucket* might resolve to any of the following concrete resource types:

AWS::Lightsail::Bucket
AWS::S3::Bucket
AWS::S3::BucketPolicy
AWS::S3Outpost::Bucket
AWS::S3Outpost::BucketPolicy

Example : Examples of target name wildcards in Hook configuration schemas

The following example configuration invokes the Hook for CREATE operations on all Amazon S3 resource types, and for UPDATE operations on all named table resource types, such as AWS::DynamobDB::Table or AWS::Glue::Table.


{
   "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {},
            "TargetFilters":{
                 "Targets": [
                    {
                        "TargetName": "AWS::S3::*",
                        "Action": "CREATE",
                        "InvocationPoint": "PRE_PROVISION"
                    },
                    {
                        "TargetName": "AWS::*::Table",
                        "Action": "UPDATE",
                        "InvocationPoint": "PRE_PROVISION"
                    }
                 ]               
            }
        }
   }
}

The following example configuration invokes the Hook for CREATE and UPDATE operations on all Amazon S3 resource types, and also for CREATE and UPDATE operations on all named table resource types, such as AWS::DynamobDB::Table or AWS::Glue::Table.


{
   "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "Properties": {},
            "TargetFilters":{
                "TargetNames": [
                    "AWS::S3::*",
                    "AWS::*::Table"
                ],
                "Actions": [
                    "CREATE",
                    "UPDATE"
                ],
                "InvocationPoints": [
                    "PRE_PROVISION"
                ]
            }
        }
   }
}

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Concepts and terminology

Stack level filtering

Amazon CloudFormation Hooks structure overview

On this page

Hook schema

In this section

Hook schema properties

Note

Note

Note

Note

Important

Warning

Example Hooks schema

Hook configuration schema

In this section

Hook configuration schema properties

Important

Specifying target names, action, and invocation points for Hook targets

Example 1: Using the Targets object array

Example 2: Using the TargetNames, Actions, and InvocationPoints list arrays

Example 3: Using Targets object array with different Actions for each TargetName

Using wildcards with Hook target names

Example : Examples of target name wildcards in Hook schemas

Example : Examples of target name wildcards in Hook configuration schemas