Registering hooks - CloudFormation Command Line Interface

Registering hooks

Next, you must package and register your hook for use in your AWS account.

Packaging a hook

Build and package the hook to deploy it to the registry.

Registering a hook

Register your hook with CloudFormation, so it's available for use in the AWS CloudFormation registry.

To register a hook

  1. (Optional) Configure your default AWS Region name to us-west-2, by submitting the configure operation.

    aws configure AWS Access Key ID [None]: <Your Access Key ID> AWS Secret Access Key [None]: <Your Secret Key> Default region name [None]: us-west-2 Default output format [None]: json
  2. (Optional) The following command builds and packages your hook project without registering it.

    $ cfn submit --dry-run
  3. Register your hook by using the CloudFormation CLI submit operation.

    cfn submit --set-default

    The command returns the following command.

    {‘ProgressStatus’: ‘COMPLETE’}

    Results: You've successfully registered your hook.

Verifying hooks are accessible in your account

Verify that you are subscribed to the hook in your AWS account

  1. To verify your hook, use the list-types command to list your newly registered hook and return a summary description of it.

    aws cloudformation list-types

    The command returns the following output and will also show you publicly available hooks you can subscribe to.

    {
        "TypeSummaries": [
            {
                "Type": "HOOK",
                "TypeName": "MyCompany::Testing::MyTestHook",
                "DefaultVersionId": "00000001",
                "TypeArn": "arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook",
                "LastUpdated": "2021-08-04T23:00:03.058000+00:00",
                "Description": "Verifies S3 bucket and SQS queues properties before creating or updating"
            }
        ]
    }
  2. Retrieve the TypeArn from the list-type output for your hook and save it.

    export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook

To learn how to publish hooks for public use, see Publishing hooks for public use.

Activate hooks

After you've developed and registered your hook, you can activate your hook in your AWS account by publishing it to the registry.

  • To activate a hook in your account, use the SetTypeConfiguration operation. This operation enables the hook’s properties that are defined in the hook’s schema properties section. In the following example, the limitSize property is set to 1 in the configuration.

    Note

    By enabling hooks in your account, you are authorizing a hook to use defined permissions from your AWS account. CloudFormation removes non-required permissions before passing your permissions to the hook. CloudFormation recommends customers or hook users to review the hook permissions and be aware of what permissions the hooks are allowed to before enabling hooks in your account.

    Specify the configuration data for your registered hook extension in the same account and AWS Region.

    aws cloudformation --region us-west-2 set-type-configuration \ --configuration "{\"CloudFormationConfiguration\":{\"HookConfiguration\":{\"TargetStacks\":\"ALL\",\"FailureMode\":\"FAIL\",\"Properties\":{\"limitSize\": \"1\",\"encryptionAlgorithm\": \"aws:kms\"}}}}" \ --type-arn $HOOK_TYPE_ARN
    Important

    To enable your hook to proactively inspect the configuration of your stack, you must set the TargetStacks to ALL in the HookConfiguration section, after the hook has been registered and activated in your account.

Accessing AWS APIs in handlers

If your hooks uses an AWS API in any of its handlers, create an IAM execution role template, hook-role.yaml. The hook-role.yaml template is based on the permissions specified for reach handler in the handler's section of the hook schema. If --role-arn flag is not used during the submit operation, the role in this stack will be provisioned and used as the execution role of the hook.

For more information, see Accessing AWS APIs from a resource type.

hook-role.yaml template

Note

If you choose to create your own execution role, we highly recommend practicing the principle of least privilege by allow listing only resources.cloudformation.amazonaws.com and hooks.cloudformation.amazonaws.com.

The following template uses the IAM, Amazon S3, and Amazon SQS permissions.

AWSTemplateFormatVersion: 2010-09-09 Description: > This CloudFormation template creates a role assumed by CloudFormation during Hook operations on behalf of the customer. Resources: ExecutionRole: Type: 'AWS::IAM::Role' Properties: MaxSessionDuration: 8400 AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Principal: Service: - resources.cloudformation.amazonaws.com - hooks.cloudformation.amazonaws.com Action: 'sts:AssumeRole' Condition: StringEquals: aws:SourceAccount: !Ref AWS::AccountId StringLike: aws:SourceArn: !Sub arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:type/hook/MyCompany-Testing-MyTestHook/* Path: / Policies: - PolicyName: HookTypePolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 's3:GetEncryptionConfiguration' - 's3:ListBucket' - 's3:ListAllMyBuckets' - 'sqs:GetQueueAttributes' - 'sqs:GetQueueUrl' - 'sqs:ListQueues' Resource: '*' Outputs: ExecutionRoleArn: Value: !GetAtt - ExecutionRole - Arn