Hooks structure

A hook schema is a JSON-formatted text file that defines properties and attributes for a specific hook. The following is an example of a hook schema and its structure.

Hooks schema

A hook includes a hook specification represented by a JSON schema and handlers that are invoked at each hook invocation point.

The first step in creating a hook is modeling a schema that defines the hook, its properties, and their attributes. When you initialize a hook project using the CloudFormation CLI init command, a hook schema file is created for you. Use this schema file as a starting point for defining the shape and semantics of your hook.

The following schema is the structure for a hook.

{
    "typeName": "string",
    "description": "string",
    "sourceUrl": "string",
    "documentationUrl": "string",
    "definitions": {
        "definitionName": {
          . . .
        }
    },
    "typeConfiguration": {
        "properties": {
             "propertyName": {
                "description": "string",
                "type": "string",
                 . . .
            },
        },
    "required": [
        "propertyName"
         . . .
            ],
    "additionalProperties": false
    },
    "handlers": {
        "preCreate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preUpdate": {
            "targetNames": [
            ],
            "permissions": [
            ]
        },
        "preDelete": {
            "targetNames": [
            ],
            "permissions": [
            ]
        }
   },
   "additionalProperties": false
}

Properties

typeName

The unique name for your hook. Specifies a three-part namespace for your hook, with a recommended pattern of Organization::Service::Hook.

Note

The following organization namespaces are reserved and can't be used in your hook type names:

• Alexa

• AMZN

• Amazon

• ASK

• AWS

• Custom

• Dev

Required: Yes

Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

Minimum: 10

Maximum: 196

description

A short description of the hook that's displayed in the CloudFormation console.

Required: Yes

sourceUrl

The URL of the source code for the hook, if public.

Required: No

Maximum: 4096

documentationUrl

The URL of a page providing detailed documentation for the hook.

Required: Yes

Pattern: ^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$

Maximum: 4096

Note

Although the hook schema should include complete and accurate property descriptions, you can use the documentationURL property to provide users with more details, including examples, use cases, and other detailed information.

definitions

Use the definitions block to provide shared hook property schemas.

It's considered a best practice to use the definitions section to define schema elements that can be used at multiple points in your hook type schema. You can then use a JSON pointer to reference that element at the appropriate places in your hook type schema.

Required: No

typeConfiguration

The definition of a hook’s configuration data.

Required: Yes

properties

The properties of the hook. All properties of a hook must be expressed in the schema. Align the hook schema properties with the hook type configuration properties.

Note

Nested properties aren't allowed. Instead, define any nested properties in the definitions element, and use a $ref pointer to reference them in the desired property.

additionalProperties

additionalProperties must be set to false. All properties of a hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

handlers

Handlers specify the operations which can initiate the hook defined in the schema, such as hook invocation points. For example, a preUpdate handler is invoked before the update operations for all specified targets in the handler.

Valid values: preCreate | preUpdate | preDelete

Note

At least one value must be specified for the handler.

Important

Stacks operations that result in the status of UpdateCleanup will not invoke a hook. For example, during the following two scenarios, the hook's preDelete handler will not be invoked:

• the stack is updated after removing one resource from the template.

• a resource with the update type of replacement is deleted.

targetNames

A string array of type names that hook targets. For example, if a preCreate handler has an AWS::S3::Bucket target, the hook initiates for Amazon S3 buckets during the preprovisioning phase.

• TargetName

  Specify at least one target name for each implemented handler.

  Pattern: ^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$

  Minimum: 1

  Required: Yes

permissions

A string array that specifies the AWS permissions needed to invoke the handler.

Required: Yes

additionalProperties

additionalProperties must be set to false. All properties of a hook must be expressed in the schema: arbitrary inputs aren't allowed.

Required: Yes

Valid values: false

Example hooks schema

The Java and the Python walkthroughs use the following code example. The following is an example structure for a hook called mycompany-testing-mytesthook.json.

{
    "typeName":"MyCompany::Testing::MyTestHook",
    "description":"Verifies S3 bucket and SQS queues properties before create and update",
    "sourceUrl":"https://mycorp.com/my-repo.git",
    "documentationUrl":"https://mycorp.com/documentation",
    "typeConfiguration":{
        "properties":{
            "minBuckets":{
                "description":"Minimum number of compliant buckets",
                "type":"string"
            },
            "minQueues":{
                "description":"Minimum number of compliant queues",
                "type":"string"
            },
            "encryptionAlgorithm":{
                "description":"Encryption algorithm for SSE",
                "default":"AES256",
                "type":"string"
            }
        },
        "required":[
            
        ],
        "additionalProperties":false
    },
    "handlers":{
        "preCreate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preUpdate":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                
            ]
        },
        "preDelete":{
            "targetNames":[
                "AWS::S3::Bucket",
                "AWS::SQS::Queue"
            ],
            "permissions":[
                "s3:ListBucket",
                "s3:ListAllMyBuckets",
                "s3:GetEncryptionConfiguration",
                "sqs:ListQueues",
                "sqs:GetQueueAttributes",
                "sqs:GetQueueUrl"
            ]
        }
    },
    "additionalProperties":false
}

Hook configuration schema

CloudFormation supports hook configurations which are set by the hook users. CloudFormation refers to this configuration schema at runtime when invoking a hook in an AWS account. Hooks are configured when the type configuration is set to initiate from the stacks. To enable your hook to proactively inspect the configuration of your stack, you must set the TargetStacks to ALL, after the hook has been registered and activated in your account. 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 SetTypeConfiguration operation.

The following is an example of a hook configuration schema.

{
    "CloudFormationConfiguration": {
        "HookConfiguration": {
            "TargetStacks": "ALL",
            "FailureMode": "FAIL",
            "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.

TargetStacks

If the mode is set to ALL, the hook applies to all stacks in your account during a CREATE, UPDATE, or DELETE operation.

If the mode is set to NONE, the hook won't apply to stacks in your account.

Valid values: ALL | 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.

• 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 | WARN

Properties

Specifies hook runtime properties. These should match the shape of the properties supported by hooks schema.

To activate a hook in your account, use the set-type-configuration operation, and specify ALL for the TargetStack property. This operation enables the hook’s properties that are defined in the hook’s schema properties section.

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