# 使用 CloudFormation 注册表中的第三方公有扩展 要在模板中使用第三方公有扩展，您必须首先为要使用它的账户和区域*激活*该扩展。激活扩展使其在激活它的账户和区域的堆栈操作中可用。 激活第三方公有扩展时，CloudFormation 会在账户的扩展注册表中为激活的扩展创建一个条目作为私有扩展。这允许您设置该扩展包含的任何配置属性。配置属性定义如何为给定 AWS 账户和区域配置扩展。 除了设置配置属性外，您还可以通过以下方式自定义扩展： + 指定 CloudFormation 用于激活扩展的执行角色，以及为扩展配置日志记录。 + 指定在新的次要版本或补丁版本可用时是否自动更新扩展。 + 指定要使用的别名，而不是第三方公有扩展名称。这有助于避免第三方扩展之间的命名冲突。 **Topics** + [配置具有 IAM 权限的执行角色和公有扩展访问权限的信任策略](#registry-public-enable-execution-role) + [自动使用新版本的扩展](#registry-public-enable-auto) + [使用别名以引用扩展](#registry-public-enable-alias) + [处理公有扩展的常用 AWS CLI 命令](#registry-commonly-used-commands-public-extensions) + [激活账户中的第三方公有扩展](registry-public-activate-extension.md) + [更新账户中的第三方公有扩展](registry-public-update-extension-console.md) + [停用账户中的第三方公有扩展](registry-public-deactivate-extension.md) ## 配置具有 IAM 权限的执行角色和公有扩展访问权限的信任策略 从 CloudFormation 注册表中激活公有扩展时，您可以提供一个执行角色，该角色向 CloudFormation 授予在您的 AWS 账户和区域中调用该扩展所需的权限。 该执行角色所需的权限在扩展架构的处理程序部分中定义。您必须创建 IAM 策略来授予扩展所需的特定权限，并将其附加到执行角色。 除权限策略外，该执行角色还需要具有允许 CloudFormation 承担角色的信任策略。按照《IAM 用户指南》**中[使用自定义信任策略创建角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)的指导，使用自定义信任策略创建角色。 ### 信任关系 下面所示为您可以使用的示例信任策略。 您可以选择使用带有 `Condition` 字段的一个或多个全局条件上下文键来限制权限范围，以防止跨服务混淆代理。有关更多信息，请参阅 [防止跨服务混淆代理](cross-service-confused-deputy-prevention.md)。 + 将 `aws:SourceAccount` 值设置为您的账户 ID。 + 将 `aws:SourceArn` 值设置为扩展的 ARN。 **示例信任策略 1** 以下是资源类型扩展的示例 IAM 角色信任策。 ------ #### [ 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" } } } ] } ``` ------ **示例信任策略 2** 以下是挂钩扩展的示例 IAM 角色信任策略。 ------ #### [ 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" } } } ] } ``` ------ ## 自动使用新版本的扩展 激活扩展时，您还可以指定扩展类型以使用最新的次要版本。每次发布者发布您激活的扩展的新版本时，您的扩展类型都会更新次要版本。 例如，下次使用包含该扩展的模板执行堆栈操作（例如创建或更新堆栈）时，CloudFormation 将使用新的次要版本。 自动或手动更新为新的扩展版本，不会影响堆栈中已预置的任何扩展实例。 CloudFormation 将扩展的主要版本更新视为可能包含重大更改，因此需要您手动更新为扩展的新主要版本。 默认情况下，AWS 发布的扩展将为其可用的所有账户和区域激活，并且始终使用每个 AWS 区域中可用的最新版本。 **重要** 由于您可以控制扩展是否以及何时更新为账户中的最新版本，因此最终可能会在不同的账户和区域部署同一扩展的不同版本。 跨这些账户和区域使用包含该扩展的相同模板时，可能会导致意外结果。 ## 使用别名以引用扩展 您不能激活给定 AWS 账户和区域中具有给定名称的多个扩展。由于不同的发布者可能提供具有相同扩展名称的公有扩展，CloudFormation 可让您为激活的任何第三方公有扩展指定别名。 如果指定扩展的别名，则 CloudFormation 会将别名视为该账户和区域内的扩展类型名称。必须使用别名来引用模板、API 调用和 CloudFormation 控制台中的扩展。 扩展别名在指定的账户和区域内必须唯一。您可以使用不同的类型名称别名在同一账户和区域中多次激活同一公有资源。 **重要** 虽然扩展别名只要求在给定账户和区域中唯一，但强烈建议用户*不要*为跨账户和区域的不同第三方公有扩展分配相同的别名。使用包含跨多个账户或区域的扩展别名的模板时，这样做可能会导致意外结果。 ## 处理公有扩展的常用 AWS CLI 命令 处理公有扩展的常用命令包括： + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) 可在账户中激活公有第三方模块或资源类型。 + [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) 可指定您账户中扩展的配置数据，以及禁用和启用挂钩。 + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) 可列出您账户中的扩展。 + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) 可返回有关特定扩展或特定扩展版本的详细信息，包括当前配置数据。 + [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) 可指定哪个扩展版本是默认版本。 + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html) 可停用先前在您账户中激活的公有第三方模块或资源类型。 # 激活账户中的第三方公有扩展 以下主题向您展示如何在您的账户中激活第三方公有扩展，从而使其在激活该扩展的账户和区域中可用。 **注意** 在继续操作之前，请确认您已创建将与此扩展一起使用的 [IAM 角色](registry-public.md#registry-public-enable-execution-role)。 **Topics** + [激活公有扩展（控制台）](#registry-public-activate-extension-console) + [激活公有扩展（AWS CLI）](#registry-public-activate-extension-cli) ## 激活公有扩展（控制台） 请按照本部分中的步骤，使用控制台来执行以下操作： + 激活第三方公有扩展 + 为您的账户指定其他扩展配置数据 **激活公有扩展以在您的账户中使用** 1. 登录到 AWS 管理控制台 并打开 CloudFormation 控制台 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。 1. 在屏幕顶部的导航栏中，选择您的 AWS 区域。 1. 从导航窗格的**注册表**下，选择**公共扩展程序**。 1. 使用**筛选条件**选择扩展类型，然后选择**第三方**。（AWS 发布的扩展默认已激活。） 1. 选择扩展，然后选择**激活**。 如果有多个版本的扩展可用，则您可以使用**版本**菜单选择要激活的扩展版本。默认为最新版本。 1. 对于扩展程序名称，您可以保留**使用默认设置**选项，或选择**覆盖默认设置**，然后输入要与此扩展程序一起使用的扩展程序类型别名。别名必须遵循扩展类型的推荐格式。有关更多信息，请参阅 [使用别名以引用扩展](registry-public.md#registry-public-enable-alias)。 1. 如果要激活的扩展程序是钩子或资源类型，那么对于**执行角色 ARN**，请指定调用扩展程序时 CloudFormation 要承担的 IAM 角色。有关更多信息，请参阅 [配置具有 IAM 权限的执行角色和公有扩展访问权限的信任策略](registry-public.md#registry-public-enable-execution-role)。 1. 对于**日志配置**，如果需要，则为扩展程序指定日志配置信息。例如： ``` { "logRoleArn": "arn:aws:iam::account:role/rolename", "logGroupName": "log-group-name" } ``` 日志记录配置信息并非必需，但建议用于调试目的。要使用带有挂钩的日志记录配置，请添加与指定的执行角色相同的信任策略，以便日志角色可以将日志写入日志组。 `logRoleArn` 和 `logGroupName` 键名称应区分大小写。 1. 对于**版本控制**、**自动更新**，请选择接收更新的方式。 + **On**（开）- 自动更新为最新次要版本。主要版本手动更新。 + **Off**（关）- 永不自动更新为最新版本。所有版本均手动更新。 有关更多信息，请参阅 [自动使用新版本的扩展](registry-public.md#registry-public-enable-auto)。 如果扩展需要其他配置，则您可以选择现在指定配置数据，也可以在扩展激活后指定该数据。 **重要** 如果您要激活的扩展是挂钩，则必须执行此步骤。您必须为 `HookInvocationStatus` 属性指定 `ENABLED`。此操作启用挂钩架构 `properties` 部分中定义的挂钩属性。有关更多信息，请参阅《CloudFormation Hooks User Guide》**中的 [Hooks configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html)。 **指定配置数据** 1. 对于**配置**，选择**立即配置**，然后选择**激活扩展**。 CloudFormation 将显示 **Configure extension**（配置扩展）页面。要查看扩展的当前配置架构，请确保 **View configuration schema**（查看配置架构）已激活。 1. 在**配置 JSON** 文本框中，输入一个 JSON 字符串，该字符串表示要为此扩展指定的配置数据。您指定的 JSON 必须根据扩展的配置架构进行验证。 1. 选择**配置扩展程序**。 如果您希望在激活后配置扩展，则可以跳过此步骤并稍后提供配置数据。 1. 对于**配置**，选择**稍后配置**，然后选择**激活扩展**。 1. 激活扩展后，您可以通过从已激活的扩展页面导航到该扩展并提供配置数据以对其进行配置。 ## 激活公有扩展（AWS CLI） 请按照本部分中的步骤，使用 AWS CLI 来执行以下操作： + 激活第三方公有扩展 + 为您的账户指定其他扩展配置数据 ### 激活公有挂钩 在您的账户中激活挂钩，即授权挂钩使用您的 AWS 账户中定义的权限。CloudFormation 会删除不需要的权限，然后再将您的权限传递给挂钩。CloudFormation 建议，客户或挂钩用户在您的账户中激活挂钩之前，先查看挂钩权限并了解允许挂钩使用的权限。 **激活公有挂钩以在您的账户中使用（AWS CLI）** 1. 获取并保存挂钩的 ARN。您可以使用 AWS 管理控制台 或 AWS CLI 获取挂钩的 ARN。有关更多信息，请参阅 [查看 CloudFormation 注册表中可用和已激活的扩展](registry-view.md)。 ``` export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/" ``` 1. 使用 [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) 命令指定配置数据。为 `--configuration` 传递的 JSON 必须根据挂钩的配置架构进行验证。要激活所有堆栈操作的挂钩，必须在 `HookConfiguration` 部分中将 `HookInvocationStatus` 属性设置为 `ENABLED`。 ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn $HOOK_TYPE_ARN --region us-west-2 ``` 有关 `HookConfiguration` 配置选项的更多信息，请参阅*《CloudFormation Hooks User Guide》*中的 [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html#)。 ### 激活公有模块和资源类型 **激活公有扩展以在您的账户中使用 (AWS CLI)** + 使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) 命令来激活扩展，并指定在发布扩展的新次要版本时是否自动更新扩展。 下面的示例指定要为此账户激活的公有扩展的公共 Amazon 资源名称 (ARN)。此外，它指定 CloudFormation 在每次发布新的次要版本时更新扩展。 ``` 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 ``` 此命令返回已激活扩展的 ARN。 ``` { "Arn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example" } ``` ### 更新公有扩展的版本 (AWS CLI) 使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) 再次激活该扩展。 使用 `--version-bump` 选项可指定是否将扩展更新为最新 `MAJOR` 版本或最新 `MINOR` 版本。 ``` aws cloudformation activate-type --type RESOURCE \ --type-name Example::Test::1234567890abcdef0 \ --type-name-alias Example::Test::Alias \ --version-bump MAJOR --region us-west-2 ``` # 更新账户中的第三方公有扩展 激活第三方公有扩展后，您可以从账户中更新大部分扩展详细信息。 **要更新账户中的公有扩展（控制台）** 1. 登录到 AWS 管理控制台 并打开 CloudFormation 控制台 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。 1. 在屏幕顶部的导航栏中，选择您的 AWS 区域。 1. 从导航窗格的**注册表**下，选择**已激活的扩展程序**。 1. 找到您要更新的扩展，然后将其选中。有关更多信息，请参阅 [查看 CloudFormation 注册表中可用和已激活的扩展](registry-view.md)。 1. 从**操作**菜单，选择**编辑**，然后选择适用的编辑选项： + 要更新配置架构，请参阅 [编辑账户中扩展的配置数据](registry-set-configuration.md)。 + 激活或停用自动更新： 1. 选择**编辑自动更新**。 1. 选择**开**或**关**，然后选择**保存**。有关更多信息，请参阅 [自动使用新版本的扩展](registry-public.md#registry-public-enable-auto)。 + 更新执行角色： 1. 选择**编辑执行角色**。 1. 指定调用此扩展时希望 CloudFormation 使用的 IAM 角色的 ARN，然后选择**保存**。有关更多信息，请参阅 [配置具有 IAM 权限的执行角色和公有扩展访问权限的信任策略](registry-public.md#registry-public-enable-execution-role)。 + 更新日志记录配置： 1. 选择**编辑日志记录配置**。 1. 编辑日志记录配置 JSON，然后选择**保存**。 # 停用账户中的第三方公有扩展 当您不再需要已激活的第三方公有扩展时，请按照以下步骤在您的账户中将其停用。 **Topics** + [停用账户中的公有扩展（控制台）](#registry-public-deactivate-extension-console) + [停用账户中的公有扩展（AWS CLI）](#registry-public-deactivate-extension-cli) + [在您的账户中停用挂钩（AWS CLI）](#registry-public-deactivate-extension-cli-hook) ## 停用账户中的公有扩展（控制台） **停用账户中的公有扩展** 1. 登录到 AWS 管理控制台 并打开 CloudFormation 控制台 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。 1. 在屏幕顶部的导航栏中，选择您的 AWS 区域。 1. 从导航窗格的**注册表**下，选择**已激活的扩展程序**。 1. 找到您想要停用的扩展，然后选中它。有关更多信息，请参阅 [查看 CloudFormation 注册表中可用和已激活的扩展](registry-view.md)。 1. 从**操作**菜单中，选择**停用**。 1. 选择**停用**。 ## 停用账户中的公有扩展（AWS CLI） 使用以下 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html) 命令。 ``` aws cloudformation deactivate-type --type MODULE \ --type-name Example::Test::Type::MODULE \ --region us-west-2 ``` ## 在您的账户中停用挂钩（AWS CLI） 停用挂钩可阻止挂钩在 AWS 账户中运行，而无需将其移除。 使用 [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) 命令并将 `HookInvocationStatus` 指定为 `DISABLED` 以停用挂钩。 以下示例指定要禁用的挂钩的 AWS 区域和 Amazon 资源名称（ARN）。 ``` 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 ``` 有关更多信息，请参阅*《CloudFormation 挂钩用户指南》*中的[禁用和启用 CloudFormation 挂钩](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hooks-disable-enable.html)。