# Use third-party public extensions from the CloudFormation registry Public extensions 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 IAM role 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 Activate a public extension 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) 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) 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 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 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) Update the version (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 Update a public extension 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 Deactivate public extensions 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) Deactivate a public extension (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) Deactivate a public extension (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) Deactivate a Hook (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*.