# Hook configuration schema syntax reference
This section outlines the schema syntax used to configure Hooks. CloudFormation uses this configuration schema at runtime when invoking a Hook in an AWS account.
To enable your Hook to proactively inspect the configuration of your stack, set the `HookInvocationStatus` to `ENABLED` after the Hook has been registered and activated in your account.
**Topics**
+ [Hook configuration schema properties](#hook-configuration-schema-properties)
+ [Hook configuration examples](#hook-configuration-examples)
+ [CloudFormation Hooks stack level filters](hooks-stack-level-filtering.md)
+ [CloudFormation Hooks target filters](hooks-target-filtering.md)
+ [Using wildcards with Hook target names](wildcard-hook-targets.md)
**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 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html) operation.
## Hook configuration schema properties
The following schema is the structure for a Hook configuration schema.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": ["STACK"],
"FailureMode": "FAIL",
"EncryptionConfiguration": {
"KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/abc-123"
},
"Properties": {
...
}
}
}
}
```
`HookConfiguration`
Hook configuration supports activating or deactivating Hooks at stack level, failure modes, and Hook properties values.
The Hook configuration supports the following properties.
`HookInvocationStatus`
Specifies if the Hook is `ENABLED` or `DISABLED`.
*Valid values*: `ENABLED` \$1 `DISABLED`
`TargetOperations`
Specifies the list of operations the Hook is run against. For more information, see [Hook targets](hooks-concepts.md#hook-terms-hook-target).
*Valid values*: `STACK` \$1 `RESOURCE` \$1 `CHANGE_SET` \$1 `CLOUD_CONTROL`
`TargetStacks`
*Available for backward compatibility. Use `HookInvocationStatus` instead.*
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` \$1 `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` \$1 `WARN`
`EncryptionConfiguration`
Specifies encryption settings for Hook annotations data.
`KmsKeyId`
The alias, alias ARN, key ID, or key ARN of the symmetric encryption AWS KMS key used to encrypt Hook annotations data. For more information, see [KeyId](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html#API_DescribeKey_RequestParameters) in the AWS KMS docs.
Before you can create Hooks with customer managed AWS KMS keys, your user or role must have AWS KMS permissions to `DescribeKey` and `GenerateDataKey`. For more information, see [AWS KMS key policy and permissions for encrypting CloudFormation Hooks results at rest](hooks-kms-key-policy.md).
`Properties`
Specifies Hook runtime properties. These should match the shape of the properties supported by Hooks schema.
## Hook configuration examples
For examples of configuring Hooks from the AWS CLI, see the following sections:
+ [Activate a proactive control-based Hook (AWS CLI)](proactive-controls-hooks-activate-hooks.md#proactive-controls-hooks-activate-hooks-cli)
+ [Activate a Guard Hook (AWS CLI)](guard-hooks-activate-hooks.md#guard-hooks-activate-hooks-cli)
+ [Activate a Lambda Hook (AWS CLI)](lambda-hooks-activate-hooks.md#lambda-hooks-activate-hooks-cli)
# CloudFormation Hooks stack level filters
You can add stack level filters to your CloudFormation Hooks to target specific stacks based on stack names and roles. This is useful in cases where you have multiple stacks with the same resource types, but the Hook is intended for specific stacks.
This section explains how these filters work and provides examples you can follow.
The basic structure of a Hook configuration without stack level filtering looks like this:
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"TargetFilters": {
"Actions": [
"CREATE",
"UPDATE",
"DELETE"
]
}
}
}
}
```
For more information about the `HookConfiguration` syntax, see [Hook configuration schema syntax reference](hook-configuration-schema.md).
To use stack level filters, add a `StackFilters` key under `HookConfiguration`.
The `StackFilters` key has one required member and has two optional members.
+ `FilteringCriteria` (required)
+ `StackNames` (optional)
+ `StackRoles` (optional)
The `StackNames` or `StackRoles` properties are optional. However, you must specify at least one of these properties.
If you create a Hook that targets [Cloud Control API](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html) operations, all stack level filters will be ignored.
## `FilteringCriteria`
`FilteringCriteria` is a required parameter that specifies the filtering behavior. It can be set to either `ALL` or `ANY`.
+ `ALL` invokes the Hook if all the filters are matched.
+ `ANY` invokes the Hook if any one filter is matched.
## `StackNames`
To specify one or more stack names as filters in your Hooks configuration, use the following JSON structure:
```
"StackNames": {
"Include": [
"string"
],
"Exclude": [
"string"
]
}
```
You must specify one of the following:
+ `Include`: List of stack names to include. Only the stacks specified in this list will invoke the Hook.
+ Type: Array of strings
+ Max items: 50
+ Min items: 1
+ `Exclude`: List of stack names to exclude. All stacks except those listed here will invoke the Hook.
+ Type: Array of strings
+ Max items: 50
+ Min items: 1
Each stack name in the `Include` and `Exclude` arrays must adhere to the following pattern and length requirements:
+ Pattern: `^[a-zA-Z][-a-zA-Z0-9]*$`
+ Max length: 128
`StackNames` support concrete stack names and full wildcard matching. To see examples using wildcards, see [Using wildcards with Hook target names](wildcard-hook-targets.md).
## `StackRoles`
To specify one or more [IAM roles](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html) as filters in your Hook configuration, use the following JSON structure:
```
"StackRoles": {
"Include": [
"string"
],
"Exclude": [
"string"
]
}
```
You must specify one of the following:
+ `Include`: List of IAM role ARNs to target stacks associated with these roles. Only stack operations initiated by these roles will invoke the Hook.
+ Type: Array of strings
+ Max items: 50
+ Min items: 1
+ `Exclude`: List of IAM role ARNs for stacks you want to exclude. The Hook will be invoked on all stacks except those initiated by the specified roles.
+ Type: Array of strings
+ Max items: 50
+ Min items: 1
Each stack role in the `Include` and `Exclude` arrays must adhere to the following pattern and length requirements:
+ Pattern: `arn:.+:iam::[0-9]{12}:role/.+`
+ Max length: 256
`StackRoles` allow wildcard characters in the following [ARN syntax](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax) sections:
+ `partition`
+ `account-id`
+ `resource-id`
To see examples using wildcards in the ARN syntax sections, see [Using wildcards with Hook target names](wildcard-hook-targets.md).
## `Include` and `Exclude`
Each filter (`StackNames` and `StackRoles`) has an `Include` list and `Exclude` list. Using `StackNames` as an example, the Hook is only invoked on the stacks that are specified in `Include` list. If stack names are only specified in the `Exclude` list, the hook is only invoked on stacks that are *not* in the `Exclude` list. If both `Include` and `Exclude` are specified, the Hook targets what's in the `Include` list and not what's in the `Exclude` list.
For example, suppose you have four stacks: A, B, C, and D.
+ `"Include": ["A","B"]` The Hook is invoked on A and B.
+ `"Exclude": ["B"]` The Hook is invoked on A, C, and D.
+ `"Include": ["A","B","C"], "Exclude": ["A","D"]` The Hook is invoked on B and C.
+ `"Include": ["A","B","C"], "Exclude": ["A”,"B","C"]` The Hook is not invoked on any stack.
## Examples of stack level filters
This section provides examples you can follow to create stack level filters for CloudFormation Hooks.
### Example 1: Include specific stacks
The following example specifies an `Include` list. The Hook is only invoked on stacks named `stack-test-1`, `stack-test-2` and `stack-test-3`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
]
}
}
}
}
}
```
### Example 2: Exclude specific stacks
If the stack names are instead added to the `Exclude` list, the Hook is invoked on any stack that is *not* named `stack-test-1`, `stack-test-2` or `stack-test-3`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Exclude": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
]
}
}
}
}
}
```
### Example 3: Combining include and exclude
If `Include` and `Exclude` lists aren't specified, the Hook is only invoked on the stacks in the `Include` that aren't in the `Exclude` list. In the following example, the Hook is only invoked on `stack-test-3`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
],
"Exclude": [
"stack-test-1",
"stack-test-2"
]
}
}
}
}
}
```
### Example 4: Combining stack names and roles with `ALL` criteria
The following Hook includes three stack names, and one stack role. Because the `FilteringCriteria` is specified as `ALL`, the Hook is only invoked for stack that have *both* a matching stack name *and* the matching stack role.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
]
},
"StackRoles": {
"Include": ["arn:aws:iam::123456789012:role/hook-role"]
}
}
}
}
}
```
### Example 5: Combining stack names and roles with `ANY` criteria
The following Hook includes three stack names, and one stack role. Because the `FilteringCriteria` is specified as `ANY`, the Hook is invoked for stack that have *either* a matching stack name *or* the matching stack role.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ANY",
"StackNames": {
"Include": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
]
},
"StackRoles": {
"Include": ["arn:aws:iam::123456789012:role/hook-role"]
}
}
}
}
}
```
# CloudFormation Hooks target filters
This topic provides guidance on configuring target filters for CloudFormation Hooks. You can use target filters for more granular control over when and on which resources your Hook is invoked. You can configure filters ranging from simple resource type targeting to more complex combinations of resource types, actions, and invocation points.
To specify one or more stack names as filters in your Hooks configuration, add a `TargetFilters` key under `HookConfiguration`.
`TargetFilters` supports the following properties.
`Actions`
A string array that specifies the actions to target. For an example, see [Example 1: Basic target filter](#target-filtering-example-1).
*Valid values*: `CREATE` \$1 `UPDATE` \$1 `DELETE`
For `RESOURCE`, `STACK`, and `CLOUD_CONTROL` targets, all target actions are applicable. For `CHANGE_SET` targets, only the `CREATE` action is applicable. For more information, see [Hook targets](hooks-concepts.md#hook-terms-hook-target).
`InvocationPoints`
A string array that specifies the invocation points to target.
*Valid values*: `PRE_PROVISION`
`TargetNames`
A string array that specifies the resource type names to target, for example, `AWS::S3::Bucket`.
Target names support concrete target names and full wildcard matching. For more information, see [Using wildcards with Hook target names](wildcard-hook-targets.md).
*Pattern*: `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$`
*Maximum*: `50`
`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.
`Actions`
The action for the specified target.
*Valid values*: `CREATE` \$1 `UPDATE` \$1 `DELETE`
`InvocationPoints`
The invocation point for the specified target.
*Valid values*: `PRE_PROVISION`
`TargetNames`
The resource type name to target.
**Note**
You can't include both the `Targets` object array and the `TargetNames`, `Actions`, or `InvocationPoints` arrays at the same time. If you want to use these three items and `Targets`, you must include them within the `Targets` object array. For an example, see [Example 2: Using the `Targets` object array](#target-filtering-example-2).
## Examples of target filters
This section provides examples you can follow to create target filters for CloudFormation Hooks.
### Example 1: Basic target filter
To create a basic target filter that focuses on specific resource types, use the `TargetFilters` object with the `Actions` array. The following target filter configuration will invoke the Hook on all `Create`, `Update`, and `Delete` actions for the specified target operations (in this case, both `RESOURCE` and `STACK` operations).
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"TargetFilters": {
"Actions": [
"Create",
"Update",
"Delete"
]
}
}
}
}
```
### Example 2: Using the `Targets` object array
For more advanced filters, you can use the `Targets` object array to list specific target, action, and invocation point combinations. This following target filter configuration will invoke the Hook before `CREATE` and `UPDATE` actions on S3 buckets and DynamoDB tables. It applies to both `STACK` and `RESOURCE` operations.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"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"
}
]
}
}
}
}
```
# 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"
]
}
}
}
}
```
**Example : `Include` specific stacks**
The following examples specifies an `Include` list. The Hook is only invoked if the stack names begins with `stack-test-`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-*"
]
}
}
}
}
}
```
**Example : `Exclude` specific stacks**
The following examples specifies an `Exclude` list. The Hook is invoked on any stack that does not begin with `stack-test-`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Exclude": [
"stack-test-*"
]
}
}
}
}
}
```
**Example : Combining `Include` and `Exclude` for specific stacks**
If `Include` and `Exclude` lists are specified, the Hook is only invoked on stacks matching in the `Include` that do not match in the `Exclude` list. In the following example, the Hook is invoked on all stacks that begin with `stack-test-` except for stacks named `stack-test-1`, `stack-test-2`, and `stack-test-3`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-*"
],
"Exclude": [
"stack-test-1",
"stack-test-2",
"stack-test-3"
]
}
}
}
}
}
```
**Example : `Include` specific roles**
The following example specifies an `Include` list with two wildcard patterns. The first entry will run the Hook for any role that begins with `hook-role` in any `partition` and `account-id`. The second entry will run any for any role in any `partition` that belongs to `account-id` `123456789012`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackRoles": {
"Include": [
"arn:*:iam::*:role/hook-role*",
"arn:*:iam::123456789012:role/*
]
}
}
}
}
}
```
**Example : `Exclude` specific roles**
The following examples specifies an `Exclude` list with two wildcard patterns. The first entry will skip Hook execution when a role has `exempt` in its name in any `partition` and any `account-id`. The second entry will skip Hook execution when a role belonging to `account-id` `123456789012` is used with the stack operation.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackRoles": {
"Exclude": [
"arn:*:iam::*:role/*exempt*",
"arn:*:iam::123456789012:role/*
]
}
}
}
}
}
```
**Example : Combining `Include` and `Exclude` for specific role ARN patterns**
If `Include` and `Exclude` lists are specified, the Hook is only invoked on stacks used with roles that match those in `Include` that do not match in the `Exclude` list. In the following example, the Hook is invoked on stack operations with any `partition`, `account-id`, and `role` name, except if the role belongs to `account-id` `123456789012`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackRoles": {
"Include": [
"arn:*:iam::*:role/*"
],
"Exclude": [
"arn:*:iam::123456789012:role/*"
]
}
}
}
}
}
```
**Example : Combining stack names and roles with all criteria**
The following Hook includes one stack name wildcard and one stack role wildcard. Because the `FilteringCriteria` is specified as `ALL`, the Hook is only invoked for stacks that have both, the matching `StackName` and matching `StackRoles`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Include": [
"stack-test-*"
]
},
"StackRoles": {
"Include": ["arn:*:iam::*:role/hook-role*"]
}
}
}
}
}
```
**Example : Combining `StackNames` and `StackRoles` with any criteria**
The following Hook includes one stack name wildcard and one stack role wildcard. Because the `FilteringCriteria` is specified as `ANY`, the Hook is invoked for the stack that have either matching `StackNames` or matching `StackRoles`.
```
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"HookInvocationStatus": "ENABLED",
"TargetOperations": [
"STACK",
"RESOURCE"
],
"FailureMode": "WARN",
"Properties": {},
"StackFilters": {
"FilteringCriteria": "ANY",
"StackNames": {
"Include": [
"stack-test-*"
]
},
"StackRoles": {
"Include": ["arn:*:iam::*:role/hook-role*"]
}
}
}
}
}
```