在 CloudFormation 中使用私有扩展 - Amazon CloudFormation
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

在 CloudFormation 中使用私有扩展

私有扩展是指您显式允许以在 Amazon Web Services 账户 中使用的扩展。

有两种私有扩展:

  • 已激活的私有扩展 - 是您的账户和区域已激活的第三方扩展的本地副本。激活第三方公有扩展时,CloudFormation 会在您账户的注册表中创建该扩展的本地副本。

  • 已注册的私有扩展 - 也可以激活未在公共 CloudFormation 注册表中列出的私有扩展。这些可能是您自己创建的扩展,也可能是贵组织或其他第三方与您共享的扩展。要在您的账户中使用此类私人扩展,您必须先注册该扩展。注册扩展会将其副本上传到您账户中的 CloudFormation 注册表并激活它。

在您的账户中使用任何私有扩展都类似于在沙盒环境中使用它。这是因为扩展是受版本控制的,而预置行为是特定于版本的,这意味着私有扩展的行为与公有扩展的行为相同。

注意

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

有关开发自己的私有扩展的信息,请参阅《CloudFormation 命令行界面用户指南》。

注册私有扩展

要使用未在 CloudFormation 注册表中列出的私有扩展(您自己开发的扩展或与您共享的扩展),您必须先在要使用它们的账户和区域的 CloudFormation 中注册它们。注册扩展会将其副本上传到您账户中的 CloudFormation 注册表并激活它。注册私有扩展后,其会显示在该账户和区域的 CloudFormation 注册表中,您可以在堆栈模板中使用该扩展。

您可以使用 Amazon CLI 的 register-type 命令或 CloudFormation CLI 的 submit 命令注册扩展。

要使用 CloudFormation CLI 注册私有扩展,请参阅《CloudFormation CLI 用户指南》中的注册扩展

用于注册私有扩展的 IAM 权限

作为注册私有扩展的一部分,您指定一个包含扩展项目包的 Amazon S3 桶。此项目包中包含您要注册的扩展必需的所有源文件。注册扩展的用户必须能够访问 Amazon S3 桶中的项目包。也就是说,用户需要具有扩展项目包的 GetObject 权限。

无论您使用 Amazon CLI 的 register-type 命令还是 CloudFormation CLI 的 submit 命令,都是如此。

有关更多信息,请参阅《Amazon Identity and Access Management 用户指南》中的 Amazon S3 的操作、资源和条件键

注册扩展

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

使用 Amazon CLI 注册挂钩

使用 CloudFormation 注册您的挂钩,使其在 Amazon CloudFormation 注册表中可供使用。

  1. (可选)通过提交 configure 操作,将默认 Amazon Web Services 区域 名称配置为 us-west-2

    aws configure AWS Access Key ID [None]: <Your Access Key ID> AWS Secret Access Key [None]: <Your Secret Key> Default region name [None]: us-west-2 Default output format [None]: json
  2. (可选)以下命令在不注册的情况下构建和打包您的挂钩项目。

    $ cfn submit --dry-run
  3. 使用 CloudFormation CLI cfn submit 注册挂钩。

    cfn submit --set-default

    该命令将返回以下命令。

    {‘ProgressStatus’: ‘COMPLETE’}

    结果:您已成功注册挂钩。

使用 Amazon CLI 注册资源类型

使用 CloudFormation 注册您的资源类型,使其在 Amazon CloudFormation 注册表中可供使用。

  1. 找到包含要在您的账户中注册的私有扩展项目包的 Amazon S3 桶。

  2. 使用 register-type 命令在您的账户中注册扩展:

    RegisterType 是一个异步操作,返回一个注册令牌,您可以使用该令牌跟踪注册请求进度。

    注意

    如果您的扩展调用 Amazon API 作为其功能的一部分,您必须创建一个包含调用这些 Amazon API 所需的权限的 IAM 执行角色,并在您的账户中预置该执行角色。然后,您可以使用 --execution-role-arn 参数指定该执行角色。接下来,CloudFormation 担任该执行角色,以便为您的资源类型提供相应的凭证。

    例如,以下命令在当前 Amazon Web Services 账户 中注册 My::Resource::Example 资源类型:

    aws cloudformation register-type --type-name My::Resource::Example --schema-handler-package [s3 object path] --type RESOURCE { "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample" }
  3. 可选:将注册令牌与 describe-type-registration 命令一起使用以跟踪注册请求进度。

    在 CloudFormation 完成注册请求时,它将请求的进度状态设置为 COMPLETE

    以下示例使用上面的 describe-type-registration 命令返回的注册令牌以返回注册状态信息。

    aws cloudformation describe-type-registration --registration-token f5525280-104e-4d35-bef5-8f1fexample { "ProgressStatus": "COMPLETE", "TypeArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example", "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ", "TypeVersionArn": "arn:aws:cloudformation:us-east-1:111122223333:type/resource/My-Resource-Example/00000001" }

在账户级别配置扩展

扩展可包含旨在应用于给定账户和区域所有扩展实例的配置属性。扩展作者在扩展的定义配置中定义这些属性。如果扩展的配置定义中有任何必需的属性,则必须先指定这些属性,然后才能在您的账户和区域中使用扩展。

注意

如果类型配置包含对存储在 Amazon Systems Manager 或 Amazon Secrets Manager 中的值的动态引用,则用于预置类型的任何角色(例如,在创建或更新堆栈时)必须具有检索该值的适当权限。具体来说:

  • 如果类型配置包含存储在 Amazon Systems Manager Parameter Store 中的参数,则用于预置该类型的用户或角色必须有权调用 GetParameter

  • 如果类型配置包含存储在 Amazon Secrets Manager 中的密钥,则用于预置该类型的用户或角色必须有权调用 GetSecretValue

有关动态引用的更多信息,请参阅使用动态引用以指定模板值

有关在开发扩展时如何定义配置定义的更多信息,请参阅《CloudFormation 扩展开发用户指南》中的定义扩展的账户级别配置

在 CloudFormation 控制台中查看扩展的当前配置数据
  1. 使用 CloudFormation 注册表查找扩展

  2. 选择扩展以查看扩展详细信息。

  3. 在扩展详细信息页面上,选择 Configuration(配置)选项卡。

  4. 展开 Configuration schema(配置架构)选项卡以查看为扩展定义的配置架构。

  5. 展开 Configuration(配置)选项卡以查看为此扩展设置的当前配置。

在 Amazon CLI 中查看扩展的当前配置数据
  • 使用 describe-type 命令返回有关扩展的详细信息。输出的 ConfigurationSchema 元素包含给定区域中扩展的当前配置定义。

    或者,使用 batch-describe-type-configurations 命令返回有关多个扩展的配置数据。

指定扩展类型的配置属性

使用 CloudFormation 控制台指定扩展的配置属性

  1. 使用 CloudFormation 注册表在账户的已激活扩展中查找扩展

  2. 选择扩展以查看扩展详细信息。

  3. 在扩展详细信息页面上,从 Configuration(配置)选项卡中选择 Edit configuration(编辑配置)。

    或者,从 Actions(操作)中选择 Edit(编辑),然后选择 Edit configuration(编辑配置)。

    CloudFormation 将显示 Configure extension(配置扩展)页面。确保打开 View configuration schema(查看配置架构)以查看扩展的当前配置定义架构。

  4. Configuration JSON(配置 JSON)文本框中,输入一个 JSON 字符串,该字符串表示要为此扩展设置的配置架构。它必须根据 Configuration schema(配置架构)中定义的架构进行验证。

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

使用 Amazon CLI 指定扩展的配置属性

  • 使用 set-type-configuration 命令指定要与您的账户和区域中的扩展一起使用的配置。

    --configuration 传递的 JSON 必须根据扩展的配置定义架构进行验证。以下是指定配置的 set-type-configuration 命令的示例。

    aws cloudformation set-type-configuration \ --region us-west-2 \ --type RESOURCE \ --type-name My::Resource::Example \ --configuration-alias default \ --configuration "{"CredentialKey": "testUserCredential"}"

使用 Amazon CLI 指定要使用的私有扩展版本

随着时间的推移,您可能会注册同一扩展的多个版本。您可以指定要用于 CloudFormation 操作的扩展版本。

指定扩展的版本

使用 set-type-default-version 命令指定用于您账户中 CloudFormation 操作的扩展版本。

例如,以下命令将当前账户的 My::Resource::Example 资源类型的默认版本设置为 00000003

aws cloudformation set-type-default-version \ --type RESOURCE \ --type-name My::Resource::Example \ --version-id 00000003

指定默认挂钩版本

要在账户中指定挂钩的默认版本,请使用 set-type-default-version 命令并指定类型、类型名称和版本 ID。

aws cloudformation set-type-default-version \ --type HOOK \ --type-name MyCompany::Testing::MyTestHook \ --version-id 00000003