Skip to main content
The CloudFormation Registry extends AWS CloudFormation by enabling custom and third‑party resource types (also called “extensions”) to be used inside CloudFormation templates. This lets you manage additional resources with the same declarative lifecycle (create, update, delete) and drift detection that CloudFormation provides.
Quick overview: Use the CloudFormation Registry to publish, version, and activate custom resource providers (resource types). Providers package a JSON schema and handler code (create/update/delete) so CloudFormation can perform lifecycle operations for non‑native resources.
This guide gives a concise, actionable overview: what the Registry provides, naming conventions, the typical provider lifecycle, example CLI commands, how to use custom types in templates, recommended tooling, versioning concepts, security considerations, and best practices.

​
What the Registry provides

  • A central place to publish and register resource types (extensions) so CloudFormation can use them.
  • Support for:
    • Private extensions (owned and maintained within your account/organization).
    • Public third‑party extensions available in the CloudFormation Registry.
  • A mechanism to define a resource’s schema (JSON Schema) and handlers (the code executed on create/update/delete).
  • Versioning, activation, and lifecycle management for type versions.
Table: Registry resource types and use cases
Resource TypeUse CaseExample
Private TypeInternal automation, custom resources for your orgMyCompany::MyService::MyResource
Public Third‑party TypeVendor-provided integrations that extend CloudFormationVendorX::Service::Resource
AWS TypeNative AWS resources maintained by AWSAWS::S3::Bucket

​
Type namespaces and naming

  • AWS types: begin with AWS:: (built-in).
  • Third‑party/public types: typically use the vendor namespace, e.g., Vendor::Service::Resource.
  • Private types: use your company or account scope, e.g., MyCompany::Service::Resource.
Example: 
MyCompany::MyService::MyResource
Use clear naming and semantic versioning so consumers understand scope and compatibility.

​
Typical provider workflow

  1. Author a resource provider:
    • Define the resource schema (JSON Schema) describing properties, required fields, and return values.
    • Implement handlers that perform create, read, update, delete, and list (CRUDL) operations.
    • Use the cloudformation-cli to scaffold, build, and test handlers in supported languages (Python, Java, Go).
  2. Package the provider into a Schema Handler Package (SHP) and upload to a supported location (for example, Amazon S3).
  3. Register the type with CloudFormation (register-type).
  4. Activate the type version you want to use.
  5. Reference the registered type inside CloudFormation templates.
  6. Manage new versions: register, test, and activate updates when ready.

​
Common CLI commands

Table: Core CloudFormation Registry commands
ActionAWS CLI commandNotes
Register typeaws cloudformation register-typeProvide --schema-handler-package pointing to SHP
Check registration statusaws cloudformation describe-type-registrationUse the registration token
List typesaws cloudformation list-typesFilter by --visibility PRIVATE or PUBLIC
Describe a typeaws cloudformation describe-typeUse --type-name to get details and TypeVersionArn
Deregister typeaws cloudformation deregister-typeRemoves a type registration
Example: Register a resource type 
aws cloudformation register-type \
  --type RESOURCE \
  --type-name MyCompany::MyService::MyResource \
  --schema-handler-package s3://my-bucket/my-shp.zip
Check registration status 
aws cloudformation describe-type-registration --registration-token <token>
List registered private types 
aws cloudformation list-types --visibility PRIVATE
Describe a specific type (show TypeVersionArn) 
aws cloudformation describe-type \
  --type RESOURCE \
  --type-name MyCompany::MyService::MyResource \
  --query "TypeVersionArn"
Deregister a type 
aws cloudformation deregister-type --type-name MyCompany::MyService::MyResource --type RESOURCE

​
Using custom types in templates

After you’ve registered and activated a type, reference it in your CloudFormation templates using its Type name and supply the properties defined by the provider schema. Example (YAML): 
AWSTemplateFormatVersion: '2010-09-09'
Resources:
  MyCustomResource:
    Type: MyCompany::MyService::MyResource
    Properties:
      PropertyOne: "value"
      PropertyTwo: 42
CloudFormation routes lifecycle events for that resource to the provider’s handlers, so the provider is responsible for provisioning the underlying resource and returning the required attributes and identifiers.

​
Development tools

  • cloudformation-cli: Official tool to initialize, build, test, and submit resource providers in supported languages.
  • Local testing: cloudformation-cli includes contract testing and local invocation helpers to validate handler behavior against the provider schema.
  • Packaging: Build an SHP (Schema Handler Package) containing schema and handler artifacts; host it in a secure location such as an S3 bucket.
Example: Bootstrapping a Python provider 
pip install cloudformation-cli
cfn init
# follow prompts to scaffold a provider
Use unit tests and the cloudformation-cli contract tests to validate lifecycle behavior before registering types in your account.

​
Versioning and activation

  • Types support multiple versions. Register new versions when you update schema or handler code.
  • Activation is explicit: you can register versions without immediately activating them for production stacks.
  • Inspect versions and activation state with describe-type and list-type-registrations.
  • Follow semantic versioning and document breaking changes. Activate new versions in a controlled fashion (CI/CD pipeline) to reduce disruption.

​
Security and IAM

Registering types and executing handler code requires IAM permissions. Handler code might run in your account (for private types) and will need the appropriate execution environment permissions. Always review handler behavior and grant least privilege.
Additional security recommendations:
  • Review public third‑party extension source and required permissions before use.
  • Store SHPs in private, access‑controlled S3 buckets with encryption and restricted IAM roles.
  • Use separate IAM execution roles for provider handlers and scope permissions using least privilege.
  • Audit CloudFormation stack events and provider logs to detect unexpected behavior.

​
Best practices

  • Test providers thoroughly using the cloudformation-cli local and contract tests prior to registration.
  • Document the provider schema and examples for consumers.
  • Use semantic versioning and keep release notes for each registered type version.
  • Prefer private types for internal automations; adopt public types only after security and functional review.
  • Automate registration and activation via CI/CD pipelines with gating and automated tests.
This lesson covered the CloudFormation Registry: its purpose, how to author and register resource providers, the commands you’ll commonly use, security considerations, and recommended best practices for developing and operating custom CloudFormation types.

Watch Video