The AWS::CloudFormation::LambdaHook
resource creates and activates a
Lambda Hook. You can use a Lambda Hook to evaluate your
resources before allowing stack operations. This resource forwards requests for resource
evaluation to a Lambda function.
For more information, see Lambda Hooks in the AWS CloudFormation Hooks User Guide.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{
"Type" : "AWS::CloudFormation::LambdaHook",
"Properties" : {
"Alias" : String
,
"ExecutionRole" : String
,
"FailureMode" : String
,
"HookStatus" : String
,
"LambdaFunction" : String
,
"StackFilters" : StackFilters
,
"TargetFilters" : TargetFilters
,
"TargetOperations" : [ String, ... ]
}
}
YAML
Type: AWS::CloudFormation::LambdaHook
Properties:
Alias: String
ExecutionRole: String
FailureMode: String
HookStatus: String
LambdaFunction: String
StackFilters:
StackFilters
TargetFilters:
TargetFilters
TargetOperations:
- String
Properties
Alias
-
The type name alias for the Hook. This alias must be unique per account and Region.
The alias must be in the form
Name1::Name2::Name3
and must not begin withAWS
. For example,Private::Lambda::MyTestHook
.Required: Yes
Type: String
Pattern:
^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$
Update requires: Replacement
ExecutionRole
-
The IAM role that the Hook assumes to invoke your Lambda function.
Required: Yes
Type: String
Pattern:
arn:.+:iam::[0-9]{12}:role/.+
Maximum:
256
Update requires: No interruption
FailureMode
-
Specifies how the Hook responds when the Lambda function invoked by the Hook returns a
FAILED
response.-
FAIL
: Prevents the action from proceeding. This is helpful for enforcing strict compliance or security policies. -
WARN
: Issues warnings to users but allows actions to continue. This is useful for non-critical validations or informational checks.
Required: Yes
Type: String
Allowed values:
FAIL | WARN
Update requires: No interruption
-
HookStatus
-
Specifies if the Hook is
ENABLED
orDISABLED
.Required: Yes
Type: String
Allowed values:
ENABLED | DISABLED
Update requires: No interruption
LambdaFunction
-
Specifies the Lambda function for the Hook. You can use:
-
The full Amazon Resource Name (ARN) without a suffix.
-
A qualified ARN with a version or alias suffix.
Required: Yes
Type: String
Pattern:
(arn:(aws[a-zA-Z-]*)?:lambda:)?([a-z]{2}(-gov)?(-iso([a-z])?)?-[a-z]+-\d{1}:)?(\d{12}:)?(function:)?([a-zA-Z0-9-_]+)(:(\$LATEST|[a-zA-Z0-9-_]+))?
Minimum:
1
Maximum:
170
Update requires: No interruption
-
StackFilters
-
Specifies the stack level filters for the Hook.
Required: No
Type: StackFilters
Update requires: No interruption
TargetFilters
-
Specifies the target filters for the Hook.
Required: No
Type: TargetFilters
Update requires: No interruption
TargetOperations
-
Specifies which type of operation the Hook is run against.
Valid values:
STACK
|RESOURCE
|CHANGE_SET
|CLOUD_CONTROL
Required: Yes
Type: Array of String
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the Hook Amazon Resource Name (ARN). For example:
arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyLambdaHook
.
For more information about using the Ref
function, see Ref
.
Fn::GetAtt
The Fn::GetAtt
intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.
For more information about using the Fn::GetAtt
intrinsic function, see Fn::GetAtt
.
HookArn
-
Returns the ARN of a Lambda Hook.
Examples
Creating a Lambda Hook in a template
The following example demonstrates how to create a Lambda Hook in a template.
JSON
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "Create a Lambda Hook",
"Parameters": {
"HookFunctionArn": {
"Description": "Hook Lambda Function ARN",
"Type": "String"
},
"HookName": {
"Description": "The name of your Hook",
"Type": "String",
"Default": "Test::Lambda::Hook",
"AllowedPattern": "^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$"
}
},
"Resources": {
"LambdaInvokerHookRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": ["hooks.cloudformation.amazonaws.com"]
},
"Action": "sts:AssumeRole"
}
]
},
"Path": "/",
"Policies": [
{
"PolicyName": "LambdaInvokerHookPolicy",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["lambda:InvokeFunction"],
"Resource": {"Ref" : "HookFunctionArn"}
}
]
}
}
]
}
},
"MyLambdaHook": {
"Type": "AWS::CloudFormation::LambdaHook",
"Properties": {
"LambdaFunction": {"Ref" : "HookFunctionArn"},
"HookStatus": "ENABLED",
"TargetOperations": [
"RESOURCE",
"STACK"
],
"FailureMode": "WARN",
"Alias": {"Ref" : "HookName"},
"ExecutionRole": {
"Fn::GetAtt": [
"LambdaInvokerHookRole",
"Arn"
]
},
"StackFilters": {
"FilteringCriteria": "ALL",
"StackNames": {
"Exclude": [{"Ref" : "AWS::StackName"}]
}
}
}
}
}
}
YAML
AWSTemplateFormatVersion: 2010-09-09
Description: Create a Lambda Hook
Parameters:
HookFunctionArn:
Description: Hook Lambda Function ARN
Type: String
HookName:
Description: The name of your Hook
Type: String
Default: 'Test::Lambda::Hook'
AllowedPattern: '^(?!(?i)aws)[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$'
Resources:
LambdaInvokerHookRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service:
- hooks.cloudformation.amazonaws.com
Action: 'sts:AssumeRole'
Path: /
Policies:
- PolicyName: LambdaInvokerHookPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'lambda:InvokeFunction'
Resource: !Ref HookFunctionArn
MyLambdaHook:
Type: 'AWS::CloudFormation::LambdaHook'
Properties:
LambdaFunction: !Ref HookFunctionArn
HookStatus: ENABLED
TargetOperations:
- RESOURCE
- STACK
FailureMode: WARN
Alias: !Ref HookName
ExecutionRole: !GetAtt LambdaInvokerHookRole.Arn
StackFilters:
FilteringCriteria: ALL
StackNames:
Exclude:
- !Ref AWS::StackName