Getting started with AWS CloudFormation Hooks
This tutorial provides a quick introduction to AWS CloudFormation Hooks. Follow these steps to activate a sample Hook from the Public Registry.
Step 1: Find a Hook in the Public Registry
To locate a sample Hook:
-
Access the CloudFormation console
. -
In the CloudFormation menu, in the Registry group, choose Public extensions to display the Registry: Public extensions dashboard.
-
In the Filter panel, from the Extension type list, select Hooks.
-
In the Filter panel, from the Publisher list, select Third party. A list of third-party Hooks is displayed. You can scroll the list to browse the available Hooks. Each Hook displays publisher and update information, a summary, and activation status.
-
In the Extensions list, find
AWSSamples::IamPolicyDoesNotGiveAdmin::Hook
. This Hook checks that policy definitions do not give the equivalent of theAdminAccess
managed policy. It specifically checks thatAWS::IAM::Policy
,AWS::IAM::Role
,AWS::IAM::Group
, andAWS::IAM::User
resources don't contain the followingPolicyDocument
statement.- Effect: Allow Action: '*' Resource: '*'
-
Click the
AWSSamples::IamPolicyDoesNotGiveAdmin::Hook
link to display the Hook overview. The overview provides the following information about the Hook.-
Amazon Resource Name (ARN)
-
Publisher
-
Release date
-
Description
-
Hook behavior
-
Target stacks
-
Registry
The bottom panel has the following three tabs.
- Target resource types
-
The Target resource types tab lists the resource types the Hook targets, and the handlers available in the Hook.
- Schema
-
The Schema tab displays the Hook's schema.
- Configuration
-
The Configuration tab displays the Hook's configuration schema, and the configuration for the active Hook. You can also edit the configuration for the active Hook in this tab.
-
-
Click the View documentation link to view the
README.md
for the Hook. The documentation provides example CloudFormation templates, including one that causes the Hook to fail, and an example configuration. -
Copy the example template that causes the Hook to fail, and save it to a YAML file so that you can test the Hook in a later step.
-
Copy the configuration example to a file so that you can configure the Hook in a later step.
-
Return to the CloudFormation console.
Step 2: Enable the Hook
To enable the Hook:
-
Choose Activate so that you can configure the Hook and enable it for your CloudFormation account.
Step 3: Set the Execution role ARN
In Extension details, enter the Execution role ARN of the IAM
execution role for CloudFormation to assume when the Hook is invoked in your account and region. In order
for CloudFormation to assume the execution role, the role must have a trust policy defined with CloudFormation.
Create a new role in the IAM Consoleaccount
and region:account
in trust policy.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "resources.cloudformation.amazonaws.com", "hooks.cloudformation.amazonaws.com" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "
account
" }, "StringLike": { "aws:SourceArn": [ "arn:aws:cloudformation:region
:account
:type/hook/AWSSamples-IamPolicyDoesNotGiveAdmin-Hook/*" ] } } } ] }
Step 4: (Optional) Enable logging
In Logging config, specify logging configuration information for the Hook, if
desired. In the following example, be sure to include your account
, rolename
, and
log-group-name
.
{ "logRoleArn": "arn:aws:iam::
account
:role/rolename
", "logGroupName": "log-group-name
" }
The logging role requires the custom trust policy in Step 3: Set the Execution role ARN and the following permissions:
Step 5: Activate the Hook
-
Ensure that Configure now is selected, so that you can configure the Hook in the next step.
-
Choose Activate extension.
Step 6: Configure the Hook
Once a public Hook is activated in your account, you must set the configuration so that it applies to
your stack operations. Configuring a Hook allows you to turn the Hook on or off
(TargetStacks
= ALL
or NONE
), set FailureMode
as
FAIL
or WARN
, and set any type configuration properties specific to the Hook. For
more information on TargetStacks
, and FailureMode
options, refer to Hook configuration schema.
To configure a Hook:
-
Ensure that the Configuration alias is set to
default
. -
Use the following code for the Hook's configuration JSON. This configuration targets all stacks and fails when invoked for a stack that has a policy definition that gives the equivalent of the
AdminAccess
managed policy.{ "CloudFormationConfiguration": { "HookConfiguration": { "TargetStacks":"ALL", "FailureMode":"FAIL", "Properties": {} } } }
-
Choose Configure extension to proceed.
Step 7: Test the Hook
The Hook is now configured and activated for your CloudFormation account. To test the Hook, create a stack with the example CloudFormation template that you saved in Step 1: Find a Hook in the Public Registry.
-
In the CloudFormation menu, choose Stacks.
-
In the Stacks console, choose Create stack.
-
In the Prerequisite - Prepare template pane, choose Template is ready.
-
In the Specify template pane, choose Upload a template file.
-
Use Choose file to upload the failure example CloudFormation template that you saved in Step 1: Find a Hook in the Public Registry.
-
Choose Next to continue.
-
In Specify stack details, provide a name for your test stack, such as
TestHookFailure
. -
Choose Next to continue.
-
In Configure stack options, the default settings are sufficient for testing the Hook. Choose Next to continue.
-
Review the stack settings, and choose Submit to continue.
CloudFormation attempts to create the stack but fails when the Hook is invoked. The operation is rolled back, and the stack is deleted. You can verify this in the stack's Events list.
Step 7: Deactivate the Hook
To deactivate the Hook, do the following.
-
In the CloudFormation menu, choose Activated extensions.
-
In Registry: Activated extensions, choose the Hooks tab.
-
From the Filter extension type list, choose Activated third-party.
-
In the list, click the radio button to the left of
AWSSamples::IamPolicyDoesNotGiveAdmin::Hook
to select it. -
From the Actions list, choose Deactivate.
-
In the information popup, choose Deactivate again to disable the Hook.
Conclusion
Having completed the preceding steps, AWSSamples::IamPolicyDoesNotGiveAdmin::Hook
runs when
you create a stack with an applicable Hook target. For additional information about testing and managing
Hooks, refer the chapter Developing Hooks.