Developing resource types for use in Amazon CloudFormation templates - Extension Development for CloudFormation
Implementing resource handlersMonitoring runtime logging for resource types
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Developing resource types for use in Amazon CloudFormation templates

Once you've modeled your resource type, and validated its schema, the next step is to develop the resource. Developing the resource consists of two main steps:

  • Implementing the appropriate event handlers for your resource.

  • Testing the resource locally to ensure it works as expected.

Implementing resource handlers

When you generate your resource package, the CloudFormation CLI stubs out empty handler functions, each of which each corresponds to a specific event in the resource lifecycle. You add logic to these handlers to control what happens to your resource type at each stage of its lifecycle.

  • create: CloudFormation invokes this handler when the resource is initially created during stack create operations.

  • read: CloudFormation invokes this handler as part of a stack update operation when detailed information about the resource's current state is required.

  • update: CloudFormation invokes this handler when the resource is updated as part of a stack update operation.

  • delete: CloudFormation invokes this handler when the resource is deleted, either when the resource is deleted from the stack as part of a stack update operation, or the stack itself is deleted.

  • list: CloudFormation invokes this handler when summary information about multiple resources of this resource type is required.

You can only specify a single handler for each event.

Which handlers you implement for a resource determine what provisioning actions CloudFormation takes with respect to the resource during various stack operations:

  • If the resource type contains both create and update handlers, CloudFormation invokes the appropriate handler during stack create and update operation.

  • If the resource type doesn't contain an update handler, CloudFormation can't update the resource during stack update operations, and will instead replace it. CloudFormation invokes the create handler to creates a new resource, then deletes the old resource by invoking the delete handler.

  • If the resource type doesn't contain create, read, and delete handlers, CloudFormation can't actually provision the resource.

Use the resource schema to specify which handlers you have implemented. If you choose not to implement a specific handler, remove it from the handlers section of the resource schema.

Accessing Amazon APIs from a resource type

If your resource type calls Amazon APIs in any of its handlers, you must create an IAM execution role that includes the necessary permissions to call those Amazon APIs, and provision that execution role in your account. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials.

When you call generate, the CloudFormation CLI automatically generates an execution role template, resource-role.yaml, as part of generating the code files for the resource type package. This template is based on the permissions specified for each handler in the handlers section of the Resource type schema. When you use submit to register the resource type, the CloudFormation CLI attempts to create or update an execution role based on the template, and then passes this execution role to CloudFormation as part of the registration.

For more information about the permissions available per Amazon service, see Actions, resources, and condition keys for Amazon services in the Amazon Identity and Access Management User Guide.

Monitoring runtime logging for resource types

When you register a resource type using cfn submit, CloudFormation creates a CloudWatch log group for the resource type in your account. This enables you to access the logs for your resource to help you diagnose any faults. The log group is named according to the following pattern:

/my-resource-type-stack-ResourceHandler-string

Where:

  • my-resource-type is the three-part resource type name.

  • string is a unique string generated by CloudFormation.

Now, when you initiate stack operations for stacks that contain the resource type, CloudFormation delivers log events emitted by the resource type to this log group.