AWS 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.
In this section
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 tofalse
. 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'spreDelete
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 anAWS::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 AWS permissions needed to invoke the handler.
Required: Yes
additionalProperties
-
additionalProperties
must be set tofalse
. 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
AWS 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
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 aCREATE
,UPDATE
, orDELETE
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
andAWS::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 followingTargetNames
,Actions
, andInvocationPoints
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" ] } } } }