Registering extensions for use in the CloudFormation registry - Extension Development for CloudFormation
Registering extensions using the submit commandResource type provisioningExtension versions and scopeDeregistering extensions and extension versions

Registering extensions for use in the CloudFormation registry

Once you've completed developing your extension, you'll need to register it with CloudFormation to make it available for use in the CloudFormation registry. From the CloudFormation CLI, use the submit command to register your extension with CloudFormation. You can also register your resource directly using the register-type operation.

For detailed information about registering private extensions, see Using private extensions in the AWS CloudFormation User Guide.

Registering extensions using the submit command

In general, the submit command does the following:

  • Validates the extension schema.

  • Packages up the extension project files and uploads them to CloudFormation.

    • This includes any source code, such as resource handlers for resource type extensions.

    • Extension source code, such as resource handlers runs within the CloudFormation service account.

  • Runs the unit and contract tests defined in the extension project.

  • For resource type extensions, determines which handlers have been specified for the resource, to determine how CloudFormation provisions the resource.

  • Returns a registration token that you can use with the describe-type-registration operation to track the status of the registration request.

To validate and package your extension project, but not register it with CloudFormation, use the --dry-run option for the submit command.

You must register your extension in each AWS Region in which you want to use it.

Use the list-types operation for summary information about types that have been registered with CloudFormation, and the describe-type operation for detailed information about specific registered resource type or resource type version.

To enable activated Hooks

After you've registered and enabled your Hook, you must set the TargetStacks to ALL in the HookConfiguration section. For example, the following command uses the set-type-configuration operation and lists the TargetStacks as ALL. You may specify the FailureMode as FAIL or WARN and add additional properties.

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

Resource type provisioning

During registration, CloudFormation examines which resource handlers have been implemented for the resource. The handlers implemented determine what provisioning actions CloudFormation takes with respect to the resource during various stack operations.

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

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

Extension versions and scope

When you register an extension, you are actually registering a specific version of that extension. You can register multiple versions of an extension, and specify which version you want to use. Use the SetTypeDefaultVersion action to specify the default version of an extension. The default version of an extension will be used in CloudFormation operations.

Any extension you register is only visible and usable within the account(s) in which you register it.

Deregistering extensions and extension versions

To remove an extension or extension version from active use in CloudFormation, you must deregister it using the DeregisterType action. If an extension or extension version is deregistered, it can no longer be used in CloudFormation operations.

You can deregister a specific extension version, or the extension as a whole. To deregister an extension, you must individually deregister all registered versions of that extension. If an extension has only a single registered version, deregistering that version results in the extension itself being deregistered. You can't deregister the default version of an extension, unless it's the only registered version of that extension, in which case the extension itself is deregistered as well.

You can't deregister an extension using the CloudFormation console.