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:

1. Access the CloudFormation console.

2. In the CloudFormation menu, in the Registry group, choose Public extensions to display the Registry: Public extensions dashboard.

3. In the Filter panel, from the Extension type list, select Hooks.

4. 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.

5. In the Extensions list, find AWSSamples::IamPolicyDoesNotGiveAdmin::Hook. This Hook checks that policy definitions do not give the equivalent of the AdminAccess managed policy. It specifically checks that AWS::IAM::Policy, AWS::IAM::Role, AWS::IAM::Group, and AWS::IAM::User resources don't contain the following PolicyDocument statement.

     - Effect: Allow
       Action: '*'
       Resource: '*' 
                   

   

6. 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.

7. 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.

8. 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.

9. Copy the configuration example to a file so that you can configure the Hook in a later step.

10. 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 Console with the following custom trust policy. Be sure to specify your account 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:

• cloudwatch:ListMetrics

• cloudwatch:PutMetricData

• logs:CreateLogStream

• logs:DescribeLogGroups

• logs:DescribeLogStreams

• logs:CreateLogGroup

• logs:PutLogEvents

Step 5: Activate the Hook

1. Ensure that Configure now is selected, so that you can configure the Hook in the next step.

2. 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:

1. Ensure that the Configuration alias is set to default.

2. 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": {}
           }
       }
   }
                   

3. 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.

1. In the CloudFormation menu, choose Stacks.

2. In the Stacks console, choose Create stack.

3. In the Prerequisite - Prepare template pane, choose Template is ready.

4. In the Specify template pane, choose Upload a template file.

5. Use Choose file to upload the failure example CloudFormation template that you saved in Step 1: Find a Hook in the Public Registry.

6. Choose Next to continue.

7. In Specify stack details, provide a name for your test stack, such as TestHookFailure.

8. Choose Next to continue.

9. In Configure stack options, the default settings are sufficient for testing the Hook. Choose Next to continue.

10. 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.

1. In the CloudFormation menu, choose Activated extensions.

2. In Registry: Activated extensions, choose the Hooks tab.

3. From the Filter extension type list, choose Activated third-party.

4. In the list, click the radio button to the left of AWSSamples::IamPolicyDoesNotGiveAdmin::Hook to select it.

5. From the Actions list, choose Deactivate.

6. 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.