在 CloudFormation 中使用公有扩展 - AWS CloudFormation

在 CloudFormation 中使用公有扩展

公有扩展是 CloudFormation 扩展,例如资源类型或模块,它们在注册表中公开发布以供所有 CloudFormation 用户使用。这包括 AWS 发布的所有扩展。第三方也可以发布公有扩展。

有两种公有扩展:

  • AWS 公有扩展 - AWS 发布的扩展始终为公有且默认已激活,因此您无需执行任何操作即可在账户中使用它们。此外,AWS 控制扩展的版本控制,因此您始终使用最新的可用版本。

  • 第三方公有扩展 - 这些扩展可供 AWS 以外的发布者通用。要使用公有扩展,您必须首先在账户和区域中激活该扩展。

    您可以发布自己的第三方扩展,使其可供普通 CloudFormation 用户使用。有关更多信息,请参阅《CloudFormation 命令行界面用户指南》中的发布扩展

注意

与私有扩展一样,来自第三方发布者的公有扩展可以实现在资源创建、读取、更新、列出和删除堆栈操作期间运行的事件处理程序。因此,在 CloudFormation 堆栈中使用这些扩展可能会在您的账户中产生费用。这不包括创建的资源产生的任何费用。有关更多信息,请参阅AWS CloudFormation 定价

激活公有扩展以在 AWS 账户 中使用

为了在模板中使用公有第三方扩展,您必须首先为要使用它的账户和区域激活该扩展。启用扩展使其在激活它的账户和区域的堆栈操作中可用。激活公有第三方扩展时,CloudFormation 会在账户的扩展注册表中为激活的扩展创建一个条目作为私有扩展。这样便可通过以下方式在您的账户中激活扩展时对其进行自定义:

  • 指定要使用的别名,而不是公有第三方扩展名称。这有助于避免第三方扩展之间的命名冲突。

  • 指定在新的次要版本或补丁版本可用时是否自动更新扩展。

  • 指定 CloudFormation 用于激活扩展的执行角色,以及为扩展配置日志记录。

激活公有第三方扩展时,还可以设置扩展包含的任何配置属性。配置属性定义如何为给定账户和区域配置扩展。有关配置的更多信息,请参阅以下内容:

将 CloudFormation 设置为自动使用新版本的扩展

激活扩展时,您还可以指定扩展类型以使用最新的次要版本。每次发布者发布您激活的扩展的新版本时,您的扩展类型都会更新次要版本。

例如,下次使用包含该扩展的模板执行堆栈操作(例如创建或更新堆栈)时,CloudFormation 将使用新的次要版本。

自动或手动更新为新的扩展版本,不会影响堆栈中已预置的任何扩展实例。

CloudFormation 将扩展的主要版本更新视为可能包含重大更改,因此需要您手动更新为扩展的新主要版本。

默认情况下,AWS 发布的扩展将为其可用的所有账户和区域激活,并且始终使用每个 AWS 区域 区域中可用的最新版本。

重要

由于您可以控制扩展是否以及何时更新为账户中的最新版本,因此最终可能会在不同的账户和区域部署同一扩展的不同版本。

跨这些账户和区域使用包含该扩展的相同模板时,可能会导致意外结果。

指定别名以引用扩展

您不能激活给定账户和区域中具有给定名称的多个扩展。由于不同的发布者可能提供具有相同扩展名称的公有扩展,CloudFormation 可让您为激活的任何第三方公有扩展指定别名。

如果指定扩展的别名,CloudFormation 会将别名视为该账户和区域内的扩展类型名称。必须使用别名来引用模板、API 调用和 CloudFormation 控制台中的扩展。

扩展别名在指定的账户和区域内必须唯一。您可以使用不同的类型名称别名在同一账户和区域中多次激活同一公有资源。

重要

虽然扩展别名只要求在给定账户和区域中唯一,但我们强烈建议用户不要为跨账户和区域的不同第三方公有扩展分配相同的别名。使用包含跨多个账户或区域的扩展别名的模板时,这样做可能会导致意外结果。

激活扩展时指定执行角色

激活资源时,您可以指定 CloudFormation 在您的账户和区域中调用该扩展时要承担的 IAM 执行角色。

为了让 CloudFormation 承担执行角色,该角色必须具有使用 CloudFormation 定义的信任策略。此外,通过创建 IAM policy 并附加到执行角色来授予执行操作的权限。所需的权限在扩展架构的处理程序部分中定义。

以下是资源类型扩展的示例 IAM 角色信任策略:

{ "Version": "2012-10-17", "Statement":[ { "Effect": "Allow", "Principal":{ "Service": "resources.cloudformation.amazonaws.com" }, "Action":"sts:AssumeRole", "Condition":{ "StringEquals":{ "aws:SourceAccount":"123456789012" }, "StringLike":{ "aws:SourceArn":"arn:aws:cloudformation:us-east-1:123456789012:type/resource/Organization-Service-Resource/*" } } } ] }

以下是挂钩扩展的示例 IAM 角色信任策略:

{ "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" }, "StringLike":{ "aws:SourceArn":"arn:aws:cloudformation:us-east-1:123456789012:type/hook/Organization-Service-Hook/*" } } } ] }

有关更多信息,请参阅《AWS Identity and Access Management 用户指南》中修改角色信任策略

在注册表中激活公有扩展

在 AWS CloudFormation 注册表中激活您的扩展,使其可供使用。

使用 CloudFormation 控制台激活公有扩展以在您的账户中使用

  1. 登录到 AWS Management Console 并打开 AWS CloudFormation 控制台 https://console.aws.amazon.com/cloudformation

  2. CloudFormation 导航窗格的 CloudFormation registry(CloudFormation 注册表)下,选择 Public extensions(公有扩展)。

  3. 使用 Filter(筛选条件)选择扩展类型,然后选择 Third party(第三方)。(AWS 发布的扩展默认已激活。)

  4. 选择扩展,然后选择 Activate(激活)。

    注意

    如果有多个版本的扩展可用,您可以使用 Version(版本)菜单选择要激活的扩展版本。默认为最新版本。

  5. 使用 Activate extension(激活扩展)页面上的选项自定义扩展在此账户中的激活方式。

    • 使用扩展类型别名激活扩展:

      1. 选择 Override default(覆盖默认值)

      2. 输入要用于此扩展的扩展类型别名。别名必须遵循扩展类型的推荐格式。

      有关更多信息,请参阅指定别名以引用扩展

    • 如果要启用私有资源,您可以指定 CloudFormation 在调用扩展时要承担的 IAM 角色。有关更多信息,请参阅激活扩展时指定执行角色

    • 如果需要,在 Logging config(日志记录配置)下指定扩展的日志记录配置信息。例如:

      { "logRoleArn": "arn:aws:iam::account:role/rolename", "logGroupName": "log-group-name" }

      日志记录配置信息并非必需,但建议用于调试目的。要使用带有挂钩的日志记录配置,请添加与指定的执行角色相同的信任策略,以便日志角色可以将日志写入日志组。

      logRoleArnlogGroupName 键名区分大小写。

    • Versioning(版本控制)下,指定接收更新的方式。

      • On(开)- 自动更新为最新次要版本。主要版本手动更新。

      • Off(关)- 永不自动更新为最新版本。所有版本均手动更新。

      有关更多信息,请参阅将 CloudFormation 设置为自动使用新版本的扩展

  6. 指定配置数据。

    注意

    此步骤对于挂钩是必需的。您必须为 TargetStack 属性指定 ALL。此操作启用挂钩架构属性部分中定义的挂钩属性。

    如果扩展需要在账户和区域级别进行额外配置,CloudFormation 会在 Activate extension(激活扩展)页面上包含 Configuration(配置)部分。您可以选择现在指定配置数据,也可以在扩展激活后指定该数据。如果扩展不需要配置,您将不会看到 Configuration(配置)部分。

    • 在启用扩展时指定配置数据:

      1. 选择 Configure now(立即配置),然后选择 Activate extension(激活扩展)。

        CloudFormation 将显示 Configure extension(配置扩展)页面。要查看扩展的当前配置架构,请确保 View configuration schema(查看配置架构)已激活。

      2. Configuration JSON(配置 JSON)文本框中,输入一个 JSON 字符串,该字符串表示要为此扩展指定的配置架构。

      3. 选择 Configure extension(配置扩展)。

    • 稍后指定配置数据:

      • 选择 Configure later(稍后配置),然后选择 Activate extension(激活扩展)。

      要为已激活的扩展指定配置数据,请访问已激活扩展的详细信息页面。

    成功激活扩展后,CloudFormation 将显示该扩展的详细信息页面。

使用 CloudFormation 控制台更新您账户中已激活的公有扩展

在 AWS CloudFormation 注册表中更新您的扩展,使其可供使用。

在您的账户和区域中激活扩展后,您可以在该扩展激活时更新其以下属性,包括:

  • 配置架构。

  • 是否激活自动版本更新。

  • 对于私有注册扩展,要使用的执行角色。

  • 日志记录配置信息。

  1. 登录到 AWS Management Console 并打开 AWS CloudFormation 控制台 https://console.aws.amazon.com/cloudformation

  2. CloudFormation 导航窗格的 CloudFormation registry(CloudFormation 注册表)下,选择 Public extensions(公有扩展)。

  3. Actions(操作)菜单,选择 Edit(编辑),然后选择适用的编辑选项:

    • 要更新配置架构,请参阅在 CloudFormation 控制台中指定扩展的配置属性

    • 激活或停用自动更新:

      1. 选择 Edit automatic updates(编辑自动更新)。

      2. 选择 On(开)或 Off(关),然后选择 Save(保存)。

    • 更新执行角色:

      1. 选择 Edit execution role(编辑扩展角色)。

      2. 指定调用此扩展时希望 CloudFormation 使用的 IAM 角色的 ARN,然后选择 Save(保存)。

    • 更新日志记录配置:

      1. 选择 Edit logging config(编辑日志记录配置)。

      2. 编辑日志记录配置 JSON,然后选择 Save(保存)。

使用 AWS CLI 激活公有扩展以在您的账户中使用

通过 AWS CLI 在 AWS CloudFormation 注册表中激活您的扩展。

激活挂钩

开发并注册挂钩后,您可以通过将其发布的注册表在 AWS 账户 中激活挂钩。

  • 要在您的账户中激活挂钩,请使用 SetTypeConfiguration 操作。此操作启用挂钩架构架构 properties 部分中定义的挂钩属性。

    注意

    通过在您的账户中启用挂钩,您授权挂钩使用您的 AWS 账户 定义的权限。CloudFormation 在将您的权限传递给挂钩之前会删除非必需的权限。CloudFormation 建议客户或挂钩用户在您的账户中启用挂钩之前查看挂钩权限并了解允许的挂钩权限。

    为在相同账户和 AWS 区域 中注册的挂钩扩展指定配置数据。

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

    要使挂钩能够主动检查堆栈的配置,您必须在HookConfiguration 部分中将 TargetStacks 设置为 ALL

激活资源类型和模块
使用 AWS CLI 激活公有扩展以在您的账户中使用
  • 使用 activate-type 激活扩展,并指定在发布扩展的新次要版本时是否自动更新扩展。

    下面的示例指定要为此账户激活的公有扩展的公共 Amazon 资源名称(ARN)。此外,它指定 CloudFormation 在每次发布新的次要版本时更新扩展。

    aws cloudformation activate-type \ --public-type-arn public_extension_ARN \ --auto-update true

    此命令返回特定于此账户和区域的已激活扩展的 ARN。

    { "Arn": "624af370-311a-11e8-b6b7-500cexample" }
使用 AWS CLI 更新公有扩展的版本

使用 activate-type 再次激活该扩展。

使用 --version-bump 参数可指定是否将扩展更新为最新 MAJOR 版本、最新 MINOR 版本。

aws cloudformation activate-type \ --region us-west-2 \ --type RESOURCE \ --type-name Example::Test::1234567890abcdef0 \ --type-name-alias Example::Test::Alias \ --version-bump MAJOR

停用账户中的公有扩展

以下各节介绍如何停用账户中的公有扩展。

使用 CloudFormation 控制台停用账户中的公有扩展

  1. 使用 CloudFormation 注册表查找扩展

  2. Actions(操作)菜单中,选择 Deactivate(停用)。

  3. 选择 Deactivate(停用)。

使用 AWS CLI 停用账户中的公有扩展

要停用账户中的公有扩展,请指定 deactivate-type。以下是 AWS CLI deactivate 命令的示例。

aws cloudformation deactivate-type \ --region us-west-2 \ --type MODULE \ --type-name Example::Test::Type::MODULE

使用 AWS CLI 停用账户中的挂钩

停用挂钩会阻止挂钩运行您的 AWS 账户。

TargetStacks 设置为 NONE 会在您的账户中关闭挂钩,因此它不适用于堆栈操作。

使用 set-type-configuration 操作并将 TargetStacks 指定为 NONE 以停用挂钩。

以下示例指定要停用的挂钩的 AWS 区域 和 Amazon 资源名称(ARN)。

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