# Managing extensions with the CloudFormation registry The CloudFormation registry serves as a centralized hub for managing extensions that can be integrated into the CloudFormation templates in your AWS account. Extensions include resource types, modules, and Hooks from AWS and third-party publishers, and your own custom extensions. The registry makes it easier to discover and provision extensions in your CloudFormation templates in the same manner you use AWS-provided resources. This section describes how to use the CloudFormation registry to activate third-party extensions in your account, including: + Activating public extensions + Registering and activating private extensions **Topics** + [Related documentation](#registry-related-documentation) + [CloudFormation registry concepts](registry-concepts.md) + [View the available and activated extensions in the CloudFormation registry](registry-view.md) + [Use third-party public extensions from the CloudFormation registry](registry-public.md) + [Use third-party private extensions that have been shared with you](registry-private.md) + [Edit configuration data for extensions in your account](registry-set-configuration.md) + [Record resource types in AWS Config](registry-config-record.md) ## Related documentation If you are a developer interested in creating your own extensions, see the following documentation: + [Developing modules using the CloudFormation CLI](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/modules.html) in the *CloudFormation Command Line Interface User Guide* + [Creating resource types using the CloudFormation CLI](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-types.html) in the *CloudFormation Command Line Interface User Guide* + [Developing custom Hooks using the CloudFormation CLI](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hooks-develop.html) in the *CloudFormation Hooks User Guide* Additionally, all provisionable AWS resource types available in the CloudFormation registry can be used with the AWS Cloud Control API, with their attributes and properties defined in a standard JSON schema. For more information, see the [Cloud Control API User Guide](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html). When using Cloud Control API to perform CRUDL (Create, Read, Update, Delete, List) operations on AWS resources, you can only do so on AWS resources within your own AWS account. # CloudFormation registry concepts This topic explains key concepts to help you understand and begin using the CloudFormation registry. ## Extension types The CloudFormation registry offers the following extension types: **Hooks** Hooks are validation checks that inspect your stacks or specific resources before CloudFormation creates, updates, or deletes them. Hooks can also be invoked during create change set operations. They provide a mechanism for enforcing organizational standards and best practices by validating resource configurations against specific requirements. If a Hook detects any configurations that don't comply with its logic, it can either issue a warning or fail the provisioning process to prevent non-compliant resources from being deployed. For more information, see the [CloudFormation Hooks User Guide](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/what-is-cloudformation-hooks.html). For documentation on how to configure Hooks using the CloudFormation console, see the following sections of the *CloudFormation Hooks User Guide*: + [AWS Control Tower proactive controls as Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/proactive-controls-hooks.html) + [Guard Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/guard-hooks.html) + [Lambda Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/lambda-hooks.html) **Modules** Modules are reusable resource configurations that can be included across multiple CloudFormation stack templates. They simplify the the creation and maintenance of CloudFormation templates by encapsulating complex or frequently used resource configurations into reusable components. This promotes consistency and standardization across your organization's infrastructure deployments. **Resource types** Resource types allow you to model and automate third-party resources or custom resources that aren't natively supported by CloudFormation. By developing resource types, you can extend CloudFormation's capabilities to provision and manage resources from various third-party services. ## Public extensions *Public extensions* are CloudFormation extensions that are publicly published in the registry for use by all AWS accounts. These include: + **AWS extensions** – Extensions published by AWS are always public, and activated by default, so you don't have to take any action before using them in your account. AWS controls the versioning of these extensions, so you are always using the latest available version. + **Third-party extensions** – These extensions are made available for general use by publishers other than AWS. To use a third-party public extension, you must first activate it in your account and Region. ## Activated extensions The CloudFormation registry in your specific AWS account includes three types of activated extensions: + **AWS extensions** – All AWS public extensions are automatically activated. + **Activated third-party** – These are local copies of third-party public extensions that you have explicitly activated for your account and Region. When you activate a third-party public extension, CloudFormation creates a local copy in your account's registry. For more information, see [Use third-party public extensions from the CloudFormation registry](registry-public.md). + **Privately registered** – These are private extensions that aren't listed in the public CloudFormation registry. These may be extensions you've created yourself or ones shared with you by your organization or other third parties. To use such a private extension in your account, you must first register it. Registering the extension uploads a copy to the CloudFormation registry in your account and activates it. For more information, see [Use third-party private extensions that have been shared with you](registry-private.md). Using privately registered extensions and activated public extensions from third-party publishers in your account is like using them in a sandbox environment. Extensions are managed with version control, so their provisioning behavior is tied to a specific version. As a result, these extensions function in the same way as public extensions, adhering to the same version-specific rules. **Note** Privately registered extensions and activated third-party public extensions may implement event handlers that run during create, read, update, list, and delete operations. Using these extensions in your CloudFormation stacks may incur charges to your account, in addition to any charges for the resources created. For more information, see [CloudFormation pricing](https://aws.amazon.com/cloudformation/pricing/). # View the available and activated extensions in the CloudFormation registry To view the available and activated extensions in the CloudFormation registry, you can use the AWS Management Console or the AWS CLI. **To view the available and activated extensions (console)** 1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. On the navigation bar at the top of the screen, choose your AWS Region. 1. From the navigation pane, under **Registry**, choose what extension category you want to view: + **Public extensions** displays the public extensions available in your account. 1. For **Filter**, **Extension type**, choose your extension type: **Resource types**, **Modules**, or **Hooks**. 1. For **Filter**, **Publisher**, choose a publisher: **AWS** or **Third party**. + **Activated extensions** displays the public and private extensions activated in your account. 1. Choose your extension type: **Resource types**, **Modules**, or **Hooks**. 1. Use the **Filter** drop-down menu to further choose the extensions to view: + **AWS** – lists extensions published by AWS. Extensions published by AWS are activated by default. + **Third-party** – lists any public extensions from publishers other than AWS that you have activated in this account. + **Registered** – lists any private extensions you have activated in this account. + **Publisher** displays any public extensions that you have published using this account. 1. Search or choose the extension name to view extension details. **To view the available and activated extensions (AWS CLI)** Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) command. # Use third-party public extensions from the CloudFormation registry To use a third-party public extension in your template, you must first *activate* the extension for the account and Region where you want to use it. Activating an extension makes it usable in stack operations in the account and Region where it's activated. When you activate a third-party public extension, CloudFormation creates an entry in your account's extension registry for the activated extension as a private extension. This allows you to set any configuration properties the extension includes. Configuration properties define how the extension is configured for a given AWS account and Region. In addition to setting configuration properties, you can also customize the extension in the following ways: + Specify the execution role CloudFormation uses to activate the extension, in addition to configure logging for the extension. + Specify whether the extension is automatically updated when a new minor or patch version becomes available. + Specify an alias to use rather than the third-party public extension name. This can help avoid naming collisions between third-party extensions. **Topics** + [Configure an execution role with IAM permissions and a trust policy for public extension access](#registry-public-enable-execution-role) + [Automatically use new versions of extensions](#registry-public-enable-auto) + [Use aliases to refer to extensions](#registry-public-enable-alias) + [Commonly used AWS CLI commands for working with public extensions](#registry-commonly-used-commands-public-extensions) + [Activate a third-party public extension in your account](registry-public-activate-extension.md) + [Update a public third-party extension in your account](registry-public-update-extension-console.md) + [Deactivate third-party public extensions in your account](registry-public-deactivate-extension.md) ## Configure an execution role with IAM permissions and a trust policy for public extension access When you activate a public extension from the CloudFormation registry, you can provide an execution role that gives CloudFormation the necessary permissions to invoke that extension in your AWS account and Region. The permissions required for the execution role are defined in the handler section of the extension schema. You must create an IAM policy that grants the specific permissions needed by the extension and attach it to the execution role. In addition to the permissions policy, the execution role must also have a trust policy that allows CloudFormation to assume the role. Follow the guidance at [Create a role using custom trust policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) in the *IAM User Guide* to create a role with a custom trust policy. ### Trust relationship The following shows example trust policies you can use. You can optionally restrict the scope of the permission for cross-service confused deputy prevention by using one or more global condition context keys with the `Condition` field. For more information, see [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md). + Set the `aws:SourceAccount` value to your account ID. + Set the `aws:SourceArn` value to your extension's ARN. **Example trust policy 1** The following is an example IAM role trust policy for a resource type extension. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "resources.cloudformation.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/Organization-Service-Resource" } } } ] } ``` ------ **Example trust policy 2** The following is an example IAM role trust policy for a Hook extension. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "resources.cloudformation.amazonaws.com", "hooks.cloudformation.amazonaws.com" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook" } } } ] } ``` ------ ## Automatically use new versions of extensions When you activate an extension, you can also specify the extension type to use the latest minor version. Your extension type updates the minor version, whenever the publisher releases a new version on your activated extension. For example, the next time you perform a stack operation, such as creating or updating a stack, using a template that includes that extension, CloudFormation uses the new minor version. Updating to a new extension version, either automatically or manually and doesn't affect any extension instances already provisioned in stacks. CloudFormation treats major version updates of extensions as potentially containing breaking changes, and so requires you to manually update to a new major version of an extension. Extensions published by AWS are activated by default for all accounts and Regions where they're available, and always use the latest version available in each AWS Region. **Important** Because you control if and when extensions gets updated to the latest version in your account, you could end up with different versions of the same extension deployed in different accounts and Regions. This might potentially lead to unexpected results when using the same template, containing that extension, across those accounts and Regions. ## Use aliases to refer to extensions You can't activate more than one extension with a given name in a given AWS account and Region. Because different publishers may offer public extensions with the same extension name, CloudFormation lets you specify an alias for any third-party public extension you activate. If you specify an alias for the extension, CloudFormation treats the alias as the extension type name within the account and Region. You must use the alias to refer to the extension in your templates, API calls, and CloudFormation console. Extension aliases must be unique within a given account and Region. You can activate the same public resource multiple times in the same account and Region, using different type name aliases. **Important** While extension aliases are only required to be unique in a given account and Region, we strongly suggest that users *not* assign the same alias to different third-party public extensions across accounts and Regions. Doing so could lead to unexpected results when using a template that contains the extension alias across multiple accounts or Regions. ## Commonly used AWS CLI commands for working with public extensions The commonly used commands for working with public extensions include: + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) to activate a public third-party module or resource type in your account. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) to specify the configuration data for an extension in your account and to disable and enable Hooks. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) to list the extensions in your account. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) to return detailed information about a specific extension or specific extension version, including current configuration data. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) to specify which version of an extension is the default version. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html) to deactivate a public third-party module or resource type that was previously activated in your account. # Activate a third-party public extension in your account The following topic shows you how to activate a third-party public extension in your account, which makes it usable in the account and Region it was activated in. **Note** Before you continue, confirm that you have created the [IAM role](registry-public.md#registry-public-enable-execution-role) that you'll use with this extension. **Topics** + [Activate a public extension (console)](#registry-public-activate-extension-console) + [Activate a public extension (AWS CLI)](#registry-public-activate-extension-cli) ## Activate a public extension (console) Follow the steps in this section to use the console to: + Activate a third-party public extension + Specify additional extension configuration data for your account **To activate a public extension for use in your account** 1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. On the navigation bar at the top of the screen, choose your AWS Region. 1. From the navigation pane, under **Registry**, choose **Public extensions**. 1. Use the **Filter** to choose the extension type, and choose **Third party**. (Extensions published by AWS are activated by default.) 1. Choose the extension, then choose **Activate**. If multiple versions of an extension are available, you can use the **Version** menu to choose the version of the extension you want to activate. The default is the most current version. 1. For **Extension name**, you can either keep **Use default** selected, or choose **Override default**, and then enter the extension type alias you want to use with this extension. The alias must follow the recommended format for the extension type. For more information, see [Use aliases to refer to extensions](registry-public.md#registry-public-enable-alias). 1. If the extension you are activating is a Hook or resource type, for **Execution role ARN**, specify the IAM role for CloudFormation to assume when invoking the extension. For more information, see [Configure an execution role with IAM permissions and a trust policy for public extension access](registry-public.md#registry-public-enable-execution-role). 1. For **Logging config**, specify logging configuration information for an extension, if desired. For example: ``` { "logRoleArn": "arn:aws:iam::account:role/rolename", "logGroupName": "log-group-name" } ``` Logging configuration information isn't required but it's recommended for debugging purposes. To use logging configuration with Hooks, add the same trust policy as the execution role specified, so that the log role can write logs to your log group. `logRoleArn` and `logGroupName` key names are case-sensitive. 1. For **Versioning**, **Automatic updates**, choose how to receive updates. + **On** – Automatically updates to the latest minor version. Major versions are updated manually. + **Off** – Never automatically update to the latest version. All versions are updated manually. For more information, see [Automatically use new versions of extensions](registry-public.md#registry-public-enable-auto). If the extension requires additional configuration, you have the option to specify the configuration data now, or after the extension has been activated. **Important** If the extension you are activating is a Hook, this step is required. You must specify `ENABLED` for the `HookInvocationStatus` property. This operation enables the Hook’s properties that are defined in the Hook’s schema `properties` section. For more information, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) in the *CloudFormation Hooks User Guide*. **To specify the configuration data** 1. For **Configuration**, choose **Configure now**, and then choose **Activate extension**. CloudFormation displays the **Configure extension** page. To view the current configuration schema for the extension, make sure **View configuration schema** is activated. 1. In the **Configuration JSON** text box, enter a JSON string that represents the configuration data you want to specify for this extension. The JSON you specify must validate against the extension's configuration schema. 1. Choose **Configure extension**. If you prefer to configure the extension after activation, you can skip this step and provide the configuration data at a later time. 1. For **Configuration**, choose **Configure later**, and then choose **Activate extension**. 1. After the extension is activated, you can configure it by navigating to the extension from the activated extensions page and providing the configuration data. ## Activate a public extension (AWS CLI) Follow the steps in this section to use the AWS CLI to: + Activate a third-party public extension + Specify additional extension configuration data for your account ### Activate public Hooks By activating 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 activating Hooks in your account. **To activate a public Hook for use in your account (AWS CLI)** 1. Get the ARN for your Hook and save it. You can get the ARN of a Hook using the AWS Management Console or AWS CLI. For more information see [View the available and activated extensions in the CloudFormation registry](registry-view.md). ``` export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/" ``` 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) command to specify the configuration data. The JSON you pass for `--configuration` must validate against the Hook's configuration schema. To activate the Hook for all stack operations, you must set the `HookInvocationStatus` property to `ENABLED` in the `HookConfiguration` section. ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn $HOOK_TYPE_ARN --region us-west-2 ``` For more information on the `HookConfiguration` configuration options, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html#) in the *CloudFormation Hooks User Guide*. ### Activate public modules and resource types **To activate a public extension for use in your account (AWS CLI)** + Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) command to activate the extension, and specify whether to auto update the extension whenever a new minor version of the extension is published. The example below specifies the public Amazon Resource Name (ARN) of a public extension to activate for this account. In addition, it specifies that CloudFormation updates the extension whenever a new minor version is published. ``` aws cloudformation activate-type \ --public-type-arn public_extension_ARN \ --execution-role-arn arn:aws:iam::123456789012:role/my-execution-role \ --auto-update true --region us-west-2 ``` This command returns an ARN of the activated extension. ``` { "Arn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example" } ``` ### Update the version of a public extension (AWS CLI) Use [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) to activate the extension again. Use the `--version-bump` option to specify whether to update the extension to the newest `MAJOR` version or newest `MINOR` version. ``` aws cloudformation activate-type --type RESOURCE \ --type-name Example::Test::1234567890abcdef0 \ --type-name-alias Example::Test::Alias \ --version-bump MAJOR --region us-west-2 ``` # Update a public third-party extension in your account After you activate a third-party public extension, you can update most extension details from your account. **To update a public extension in your account (console)** 1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. On the navigation bar at the top of the screen, choose your AWS Region. 1. From the navigation pane, under **Registry**, choose **Activated extensions**. 1. Find the extension you want to update and select it. For more information, see [View the available and activated extensions in the CloudFormation registry](registry-view.md). 1. From the **Actions** menu, choose **Edit**, and then the appropriate editing option: + To update the configuration schema, see [Edit configuration data for extensions in your account](registry-set-configuration.md). + To activate or deactivate automatic updates: 1. Choose **Edit automatic updates**. 1. Choose **On** or **Off**, and then choose **Save**. For more information, see [Automatically use new versions of extensions](registry-public.md#registry-public-enable-auto). + To update the execution role: 1. Choose **Edit execution role**. 1. Specify the ARN of the IAM role you want CloudFormation to use when invoking this extension, and then choose **Save**. For more information, see [Configure an execution role with IAM permissions and a trust policy for public extension access](registry-public.md#registry-public-enable-execution-role). + To update the logging configuration: 1. Choose **Edit logging config**. 1. Edit the logging configuration JSON, and then choose **Save**. # Deactivate third-party public extensions in your account When you no longer need an activated third-party public extension, use the following procedures to deactivate it in your account. **Topics** + [Deactivate a public extension in your account (console)](#registry-public-deactivate-extension-console) + [Deactivate a public extension in your account (AWS CLI)](#registry-public-deactivate-extension-cli) + [Disable a Hook in your account (AWS CLI)](#registry-public-deactivate-extension-cli-hook) ## Deactivate a public extension in your account (console) **To deactivate a public extension in your account** 1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. On the navigation bar at the top of the screen, choose your AWS Region. 1. From the navigation pane, under **Registry**, choose **Activated extensions**. 1. Find the extension you want to deactivate and select it. For more information, see [View the available and activated extensions in the CloudFormation registry](registry-view.md). 1. From the **Actions** menu, choose **Deactivate**. 1. Choose **Deactivate**. ## Deactivate a public extension in your account (AWS CLI) Use the following [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html) command. ``` aws cloudformation deactivate-type --type MODULE \ --type-name Example::Test::Type::MODULE \ --region us-west-2 ``` ## Disable a Hook in your account (AWS CLI) Disabling a Hook prevents the Hook from running in your AWS account without removing it. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) command and specify `HookInvocationStatus` as `DISABLED` to disable a Hook. The following example specifies the AWS Region and the Amazon Resource Name (ARN) of the Hook that's being disabled. ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "DISABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn "arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyTestHook" --region us-west-2 ``` For more information, see [Disable and enable CloudFormation Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hooks-disable-enable.html) in the *CloudFormation Hooks User Guide*. # Use third-party private extensions that have been shared with you To use third-party private extensions that have been shared with you, you must first *register* them with CloudFormation, in the accounts and Regions where you want to use them. Registering the extension uploads a copy of it to the CloudFormation registry in your account, and activates it. Once you're registered a private extension, it will appear in the CloudFormation registry for that AWS account and Region, and you can use it in your stack templates. **Topics** + [IAM permissions for registering a third-party private extension](#registry-register-permissions) + [Commonly used AWS CLI commands for working with private extensions](#registry-commonly-used-commands-private-extensions) + [Register a third-party private extension in your account](registry-register-private-extension.md) + [Remove third-party private extensions from your account](registry-private-deregister-extension.md) ## IAM permissions for registering a third-party private extension As part of registering a private extension, you might specify an Amazon S3 bucket that contains the extension project package. This package contains any source files necessary for the extension you want to register. The user registering the extension must be able to access the project package in that Amazon S3 bucket. To do so, the user must have [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) permissions for the extension package. This is true whether you're either using the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) command of the AWS CLI, or the [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html) command of the CloudFormation CLI. For more information, see [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html) in the *Service Authorization Reference*. ## Commonly used AWS CLI commands for working with private extensions The commonly used commands for working with private extensions include: + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) to register a private extension in your account. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html) to return the current status of a registration request. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) to list the extensions in your account. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) to return detailed information about a specific extension or specific extension version, including current configuration data. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) to specify the configuration data for an extension in your account and to disable and enable Hooks. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) to specify which version of an extension is the default version. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) to remove a private extension or extension version from your account. # Register a third-party private extension in your account This topic covers the steps to register a third-party private extension that's shared with you so it's available for use in your account. **Note** Before you continue, confirm that you have the required [IAM permissions](registry-private.md#registry-register-permissions) to register a private extension. **To register a private extension that's shared with you (AWS CLI)** 1. Locate the Amazon S3 bucket that contains the project package for the private extension you want to register in your account. 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) command to register the private extension in your account. For example, the following command registers the `My::Resource::Example` resource type in the specified AWS account. ``` aws cloudformation register-type --type RESOURCE \ --type-name My::Resource::Example \ --schema-handler-package [s3 object path] --region us-west-2 ``` `RegisterType` is an asynchronous operation, and returns a registration token you can use to track the progress of your registration request. ``` { "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample" } ``` If your extension calls AWS APIs as part of its functionality, you must create an IAM execution role that includes the necessary permissions to call those AWS APIs, and provision that execution role in your account. You can then specify this execution role using the `--execution-role-arn` option. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials. ``` --execution-role-arn arn:aws:iam::123456789012:role/MyIAMRole ``` 1. (Optional) Use the registration token with the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html) command to track the progress of your registration request. When CloudFormation completes the registration request, it sets the progress status of the request to `COMPLETE`. The following example uses the registration token returned by the `describe-type-registration` command above to return registration status information. ``` aws cloudformation describe-type-registration \ --registration-token f5525280-104e-4d35-bef5-8f1fexample \ --region us-west-2 ``` The command returns the following output. ``` { "ProgressStatus": "COMPLETE", "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example", "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ", "TypeVersionArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example/00000001" } ``` **Important** If the extension you are registering is a Hook, this next step is required. You must specify `ENABLED` for the `HookInvocationStatus` property. This operation enables the Hook’s properties that are defined in the Hook’s schema `properties` section. For more information, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) in the *CloudFormation Hooks User Guide*. **To specify the configuration data for a Hook (AWS CLI)** 1. Get the ARN for your Hook and save it. You can get the ARN of a Hook using the AWS Management Console or AWS CLI. For more information see [View the available and activated extensions in the CloudFormation registry](registry-view.md). ``` export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/" ``` 1. Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) command to specify the configuration data. The JSON you pass for `--configuration` must validate against the Hook's configuration schema. To activate the Hook, you must set the `HookInvocationStatus` property to `ENABLED` in the `HookConfiguration` section. ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn $HOOK_TYPE_ARN --region us-west-2 ``` For more information, see [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) in the *CloudFormation Hooks User Guide*. # Remove third-party private extensions from your account To remove a third-party private extension or extension version, use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) command. 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. **Warning** Deregistering a private extension can't be undone. This action will: Make the extension unusable in all CloudFormation operations. Cause failures in future stack updates that use this extension (for modules and resource types). Although you can reregister the extension privately later, this could cause failures if CloudFormation relies on an earlier version. Before proceeding, use the [list-stacks](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stacks.html) and [get-template](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html) commands to verify that no active stacks are using this extension. ## Example deregister extension commands This section provides examples that show the different ways to deregister private extensions. **Deregister by type name** Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) command with `--type` and `--type-name` options to deregister your extension. ``` aws cloudformation deregister-type \ --type MODULE \ --type-name My::S3::SampleBucket::MODULE ``` **Deregister by type name and version** To deregister a specific version of your extension, specify the `--version-id` option in the command. ``` aws cloudformation deregister-type \ --type MODULE \ --type-name My::S3::SampleBucket::MODULE \ --version-id 00000001 ``` **Tip** To set a different version of the extension as default first, use the [set-type-default-version](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) command. **Deregister by ARN** Use the `--arn` option and specify your extension's ARN to deregister it. ``` aws cloudformation deregister-type \ --arn arn:aws:cloudformation:us-west-2:123456789012:type/resource/Organization-Service-Resource ``` # Edit configuration data for extensions in your account This topic provides guidance on editing configuration data for extensions in your account within a specific Region. Extensions can include configuration properties that apply to all instances of the extension for a given account and Region. These are defined by the extension author in the extension's configuration definition. If there are any required properties in the extension's configuration definition, you must specify those properties before you can use the extension in your account and Region. For more information about how configuration definitions are defined when developing an extension, see the following documentation. + [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) + [Defining the account-level configuration of an extension](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-model.html#resource-type-howto-configuration) **Topics** + [Permissions required to use dynamic references](#registry-set-configuration-considerations) + [Edit configuration data for an extension (console)](#registry-set-configuration-procedure-console) + [Edit configuration data for an extension (AWS CLI)](#registry-set-configuration-procedure-cli) ## Permissions required to use dynamic references If your configuration data includes dynamic references to values stored in AWS Systems Manager or AWS Secrets Manager, any role used to provision the type (for example, when creating or updating a stack) must have the proper permissions to retrieve that value. Specifically: + If the configuration data contains a parameter stored in AWS Systems Manager Parameter Store, the user or role used to provision the type must have permissions to call [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html). + If the configuration data contains a secret stored in AWS Secrets Manager, the user or role used to provision the type must have permissions to call [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html). For more information, see [Get values stored in other services using dynamic references](dynamic-references.md). ## Edit configuration data for an extension (console) Follow the steps in this section to use the console to: + View the current configuration data for an extension + Update extension configuration data for your account **To view the current configuration data for an extension** 1. Sign in to the AWS Management Console and open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. On the navigation bar at the top of the screen, choose your AWS Region. 1. From the navigation pane, under **Registry**, choose **Activated extensions**. 1. Find the extension you want to view. For more information, see [View the available and activated extensions in the CloudFormation registry](registry-view.md). 1. Choose the extension to view the extension details. 1. On the extension details page, choose the **Configuration** tab. 1. Expand the **Configuration schema** tab to see the configuration schema defined for the extension. 1. Expand the **Configuration** tab to see the current configuration that you have set for this extension. **To update configuration data for an extension** 1. On the extension details page, from the **Configuration** tab, choose **Edit configuration**. Alternatively, from **Actions**, choose **Edit**, and then choose **Edit configuration**. CloudFormation displays the **Configure extension** page. Make sure that **View configuration schema** is toggled on to see the extension's current configuration definition schema. 1. In the **Configuration JSON** text box, enter a JSON string that represents the configuration schema you want to set for this extension. It must validate against the schema defined in **Configuration schema**. 1. Choose **Configure extension**. ## Edit configuration data for an extension (AWS CLI) Follow the steps in this section to use the AWS CLI to: + View the current configuration data for an extension + Update extension configuration data for your account **To view the current configuration data for an extension** + Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) command to return detailed information about the extension. The `ConfigurationSchema` element of the output contains the current configuration definition of the extension in a given Region. Alternatively, use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/batch-describe-type-configurations.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/batch-describe-type-configurations.html) command to return configuration data about multiple extensions. **To update configuration data for an extension** + Use the [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) command to specify the configuration data. The JSON you pass for `--configuration` must validate against the extension's configuration schema. In the following example, the **set-type-configuration** command specifies the configuration data *`"{"CredentialKey": "testUserCredential"}"`* for the `--configuration` option. ``` aws cloudformation set-type-configuration --type RESOURCE \ --type-name My::Resource::Example \ --configuration-alias default \ --configuration "{"CredentialKey": "testUserCredential"}" \ --region us-west-2 ``` # Record resource types in AWS Config You can specify that AWS Config automatically track your private resource types and record changes to those resources as *configuration items*. This enables you to view configuration history for these private resource types, in addition to write AWS Config Rules rules to verify configuration best practices. AWS Config is required for the Hook extension. To have AWS Config automatically track your private resource types: + Manage the resources through CloudFormation. This includes performing all resource create, updated, and delete operations through CloudFormation. **Note** If you use an IAM role to perform your stack operations, that IAM role must have permission to call the following AWS Config actions: [PutResourceConfig](https://docs.aws.amazon.com/config/latest/APIReference/API_PutResourceConfig.html) [DeleteResourceConfig](https://docs.aws.amazon.com/config/latest/APIReference/API_DeleteResourceConfig.html) + Configure AWS Config to record all resource types. For more information, see [Recording Configurations for Third-Party Resources using the AWS CLI](https://docs.aws.amazon.com/config/latest/developerguide/customresources.html) in the *AWS Config Developer Guide*. **Note** AWS Config doesn't support recording of private resources containing properties defined as both required *and* write-only. By design, resource properties defined as write-only aren't returned in the schema used to create AWS Config configuration item. Because of this, including a property that's defined as both write-only and required will cause the configuration item creation to fail, as a required property will not be present. To view the schema that will be used to create the configuration item, you can review the `schema` property of the [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html) action. For more information about configuration items, see [Configuration items](https://docs.aws.amazon.com/config/latest/developerguide/config-concepts.html#config-items) in the *AWS Config Developer Guide*. ## Preventing sensitive properties being recorded in a configuration item Your resource type may contain properties that you consider sensitive information, such as passwords, secrets, or other sensitive data, that you don't want recorded as part of the configuration item. To prevent a property from being recorded in the configuration item, you can include that property in the `writeOnlyproperties` list in your resource type schema. Resource properties listed as `writeOnlyproperties` can be specified by the user, but won't be returned by a `read` or `list` request. For more information, see [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-writeonlyproperties](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-writeonlyproperties) in the *CloudFormation CLI User Guide*.