本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 CloudFormation CLI 开发自定义 Hook 本节适用于想要开发自定义 Hook 并将其注册到 CloudFormation注册表的客户。它概述了 CloudFormation Hook 的结构，以及使用 Python 或 Java 开发、注册、测试、管理和发布你自己的 Hook 的指南。 开发自定义 Hook 有三个主要步骤： 1. **启动** 要开发自定义 Hook，必须配置和使用 CloudFormation CLI。要启动 Hook 的项目及其必需的文件，请使用 CloudFormation CLI [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html)命令并指定要创建挂钩。有关更多信息，请参阅 [启动自定义 CloudFormation Hooks 项目](hooks-init.md)。 1. **模型** 要建模、创作和验证您的 Hook 架构，请定义 Hook 及其属性和属性。 CloudFormation CLI 会创建与特定的 Hook 调用点相对应的空处理函数。将您自己的逻辑添加到这些处理程序中，以控制在目标生命周期的每个阶段调用 Hook 期间发生的情况。有关更多信息，请参阅 [建模自定义 CloudFormation 挂钩](hooks-model.md)。 1. **注册** 要注册 Hook，请提交您的 Hook 以注册为私有或公共第三方扩展。在`[submit](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html)`操作中注册您的 Hook。有关更多信息，请参阅 [向注册自定义 Hook CloudFormation](registering-hooks.md)。 以下任务与注册您的 Hook 相关联： 1. *发布* — 挂钩发布到注册表。 1. *配置* — 在对堆栈调用类型配置时配置挂钩。 **注意** Hook 将在 30 秒后超时，最多重试 3 次。有关更多信息，请参阅 [超时和重试限制](hooks-concepts.md#hook-timeout-and-retry-limits)。 **Topics** + [先决条件](hooks-prerequisites.md) + [启动一个 Hooks 项目](hooks-init.md) + [建模挂钩](hooks-model.md) + [注册挂钩](registering-hooks.md) + [测试挂钩](testing-hooks.md) + [更新挂钩](updating-registered-hook.md) + [取消注册挂钩](deregistering-hooks.md) + [发布挂钩](hooks-publishing.md) + [架构语法](hooks-schema.md) # 开发自定义 CloudFormation Hook 的先决条件 你可以用 Java 或 Python 开发一个自定义 Hook。以下是开发自定义 Hook 的先决条件： **Java 先决条件** + [Apache Maven](https://maven.apache.org/install.html) + [JDK 17](https://www.oracle.com/java/technologies/downloads/#java17) **注意** 如果您打算使用[CloudFormation 命令行界面 (CLI)](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) 启动适用于 Java 的 Hooks 项目，则还必须安装 Python 3.8 或更高版本。 CloudFormation CLI 的 Java 插件可以通过`pip`（Python 的包管理器）安装，该插件由 Python 分发。 要为您的 Java Hooks 项目实现 Hook 处理程序，您可以下载 [Java Hook 处理程序示例文件](samples/java-handlers.zip)。 **Python 先决条件** + [Python 版本 3.8](https://www.python.org/downloads/) 或更高版本。 要为你的 Python Hooks 项目实现钩子处理程序，你可以下载 [Python Hook 处理程序示例文件](samples/python-handlers.zip)。 ## 开发 Hook 的权限 除了 CloudFormation `Create``Update`、和`Delete`堆栈权限外，您还需要访问以下 AWS CloudFormation 操作。对这些操作的访问权限通过您的 IAM 角色的 CloudFormation 策略进行管理。 + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.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/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-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) 有关更多信息，请参阅 [为 CloudFormation Hook 授予 IAM 权限](grant-iam-permissions-for-hooks.md)。 ## 为 Hooks 设置开发环境 要开发 Hook，你应该熟悉[CloudFormation 模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)以及 Python 或 Java。 **要安装 CloudFormation CLI 和相关插件，请执行以下操作：** 1. 使用 Python 包管理器安装 CloudFormation CLI。`pip` ``` pip3 install cloudformation-cli ``` 1. 安装用于 CloudFormation CLI 的 Python 或 Java 插件。 ------ #### [ Python ] ``` pip3 install cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install cloudformation-cli-java-plugin ``` ------ 要升级 CloudFormation CLI 和插件，您可以使用升级选项。 ------ #### [ Python ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-java-plugin ``` ------ # 启动自定义 CloudFormation Hooks 项目 创建自定义 Hooks 项目的第一步是启动该项目。你可以使用 CloudFormation CLI `init` 命令来启动你的自定义 Hooks 项目。 该`init`命令将启动一个向导，引导您完成项目的设置，包括 Hooks 架构文件。使用此架构文件作为起点来定义 Hook 的形状和语义。有关更多信息，请参阅 [架构语法](hooks-schema.md)。 **要启动 Hook 项目，请执行以下操作：** 1. 为项目创建目录。 ``` mkdir ~/mycompany-testing-mytesthook ``` 1. 导航到新目录。 ``` cd ~/mycompany-testing-mytesthook ``` 1. 使用 C CloudFormation LI `init` 命令启动项目。 ``` cfn init ``` 该命令将返回以下输出。 ``` Initializing new project ``` 1. 该`init`命令将启动一个向导，引导您完成项目的设置。出现提示时，输入`h`以指定 Hooks 项目。 ``` Do you want to develop a new resource(r) a module(m) or a hook(h)? ``` ``` h ``` 1. 为您的挂钩类型输入一个名称。 ``` What's the name of your hook type? (Organization::Service::Hook) ``` ``` MyCompany::Testing::MyTestHook ``` 1. 如果只安装了一个语言插件，则默认选择该插件。如果安装了多个语言插件，则可以选择所需的语言。输入您选择的语言的数字选择。 ``` Select a language for code generation: [1] java [2] python38 [3] python39 (enter an integer): ``` 1. 根据所选的开发语言设置打包。 ------ #### [ Python ] （*可选*）选择 Docker 进行独立于平台的打包。虽然不需要 Docker，但强烈建议让打包变得更简单。 ``` Use docker for platform-independent packaging (Y/n)? This is highly recommended unless you are experienced with cross-platform Python packaging. ``` ------ #### [ Java ] 设置 Java 软件包名称并选择代码生成模型。您可以使用默认的软件包名称，也可以创建一个新的软件包名称。 ``` Enter a package name (empty for default 'com.mycompany.testing.mytesthook'): ``` ``` Choose codegen model - 1 (default) or 2 (guided-aws): ``` ------ *结果*：您已成功启动项目并生成了开发 Hook 所需的文件。以下是构成 Python 3.8 的 Hooks 项目的目录和文件的示例。 ``` mycompany-testing-mytesthook.json rpdk.log README.md requirements.txt hook-role.yaml template.yml docs README.md src __init__.py handlers.py models.py target_models aws_s3_bucket.py ``` **注意** `src`目录中的文件是根据您的语言选择创建的。生成的文件中有一些有用的注释和示例。当你运行`generate`命令为处理程序添加运行时代码时`models.py`，某些文件（例如）会在稍后的步骤中自动更新。 # 建模自定义 CloudFormation 挂钩 对自定义 CloudFormation Hook 进行建模涉及创建一个用于定义 Hook、其属性和属性的架构。使用`cfn init`命令创建自定义 Hook 项目时，会将示例 Hook 架构创建为 JSON 格式的文本文件。`hook-name.json` 目标调用点和目标操作指定了调用 Hook 的确切位置。*Hook 处理程序*为这些点托管可执行的自定义逻辑。例如，`CREATE`操作的目标操作使用`preCreate`处理程序。当 Hook 目标和服务执行匹配操作时，您在处理程序中编写的代码将调用。*挂钩目标*是调用挂钩的目的地。您可以指定目标，例如 CloudFormation 公共资源、私有资源或自定义资源。Hook 支持无限数量的钩子目标。 该架构包含挂钩所需的权限。创作 Hook 需要您为每个 Hook 处理程序指定权限。 CloudFormation 鼓励作者编写遵循标准安全建议的策略，即授予*最低权限*或仅授予执行任务所需的权限。确定用户（和角色）需要做什么，然后制定策略，*仅*允许他们为 Hook 操作执行这些任务。 CloudFormation 使用这些权限来限定 Hook 用户提供的权限。这些权限将传递给 Hook。Hook 处理程序使用这些权限来访问 AWS 资源。 您可以使用以下架构文件作为起点来定义您的 Hook。使用 Hook 架构来指定要实现的处理程序。如果您选择不实现特定的处理程序，请将其从 Hook 架构的处理程序部分中删除。有关架构的更多详细信息，请参阅[架构语法](hooks-schema.md)。 ``` { "typeName":"MyCompany::Testing::MyTestHook", "description":"Verifies S3 bucket and SQS queues properties before create and update", "sourceUrl":"https://mycorp.com/my-repo.git", "documentationUrl":"https://mycorp.com/documentation", "typeConfiguration":{ "properties":{ "minBuckets":{ "description":"Minimum number of compliant buckets", "type":"string" }, "minQueues":{ "description":"Minimum number of compliant queues", "type":"string" }, "encryptionAlgorithm":{ "description":"Encryption algorithm for SSE", "default":"AES256", "type":"string" } }, "required":[ ], "additionalProperties":false }, "handlers":{ "preCreate":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ ] }, "preUpdate":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ ] }, "preDelete":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ "s3:ListBucket", "s3:ListAllMyBuckets", "s3:GetEncryptionConfiguration", "sqs:ListQueues", "sqs:GetQueueAttributes", "sqs:GetQueueUrl" ] } }, "additionalProperties":false } ``` **Topics** + [使用 Java 对自定义 CloudFormation 挂钩进行建模](hooks-model-java.md) + [使用 Python 对自定义 CloudFormation 挂钩进行建模](hooks-model-python.md) # 使用 Java 对自定义 CloudFormation 挂钩进行建模 对自定义 CloudFormation Hook 进行建模涉及创建一个用于定义 Hook、其属性和属性的架构。本教程将引导你使用 Java 对自定义 Hook 进行建模。 ## 步骤 1：添加项目依赖关系 基于 Java 的 Hooks 项目依赖于 Maven `pom.xml` 的文件作为依赖项。展开以下部分，将源代码复制到项目根目录下的`pom.xml`文件中。 ### 挂钩项目依赖关系 (pom.xml) ``` 4.0.0 com.mycompany.testing.mytesthook mycompany-testing-mytesthook-handler mycompany-testing-mytesthook-handler 1.0-SNAPSHOT jar 1.8 1.8 UTF-8 UTF-8 2.16.1 8.36.2 2.8.0 2.11.3 3.1.1 3.6.0 4.1.4 2.5.0 3.2.0 3.2.1 software.amazon.awssdk bom 2.16.1 pom import software.amazon.cloudformation aws-cloudformation-rpdk-java-plugin [2.0.0,3.0.0) software.amazon.awssdk sdk-core software.amazon.awssdk cloudformation software.amazon.awssdk s3 software.amazon.awssdk utils software.amazon.awssdk apache-client software.amazon.awssdk sqs software.amazon.cloudformation cloudformation-cli-java-plugin-testing-support 1.0.0 com.amazonaws aws-java-sdk-s3 1.12.85 commons-io commons-io ${commons-io.version} org.apache.commons commons-lang3 3.9 org.apache.commons commons-collections4 4.4 com.google.guava guava 29.0-jre com.amazonaws aws-java-sdk-cloudformation 1.11.555 test commons-codec commons-codec 1.14 software.amazon.cloudformation aws-cloudformation-resource-schema [2.0.5, 3.0.0) com.fasterxml.jackson.core jackson-databind ${jackson.version} com.fasterxml.jackson.dataformat jackson-dataformat-cbor ${jackson.version} com.fasterxml.jackson.datatype jackson-datatype-jsr310 ${jackson.version} com.fasterxml.jackson.module jackson-modules-java8 ${jackson.version} pom runtime org.json json 20180813 com.amazonaws aws-java-sdk-core 1.11.1034 com.amazonaws aws-lambda-java-core 1.2.0 com.amazonaws aws-lambda-java-log4j2 1.2.0 com.google.code.gson gson 2.8.8 org.projectlombok lombok 1.18.4 provided org.apache.logging.log4j log4j-api 2.17.1 org.apache.logging.log4j log4j-core 2.17.1 org.apache.logging.log4j log4j-slf4j-impl 2.17.1 org.assertj assertj-core 3.12.2 test org.junit.jupiter junit-jupiter 5.5.0-M1 test org.mockito mockito-core 3.6.0 test org.mockito mockito-junit-jupiter 3.6.0 test org.apache.maven.plugins maven-compiler-plugin 3.8.1 -Xlint:all,-options,-processing org.apache.maven.plugins maven-shade-plugin 2.3 false *:* **/Log4j2Plugins.dat package shade org.codehaus.mojo exec-maven-plugin 1.6.0 generate generate-sources exec cfn generate ${cfn.generate.args} ${project.basedir} org.codehaus.mojo build-helper-maven-plugin 3.0.0 add-source generate-sources add-source ${project.basedir}/target/generated-sources/rpdk org.apache.maven.plugins maven-resources-plugin 2.4 maven-surefire-plugin 3.0.0-M3 org.jacoco jacoco-maven-plugin 0.8.4 **/BaseHookConfiguration* **/BaseHookHandler* **/HookHandlerWrapper* **/ResourceModel* **/TypeConfigurationModel* **/model/**/* prepare-agent report test report jacoco-check check PACKAGE BRANCH COVEREDRATIO 0.8 INSTRUCTION COVEREDRATIO 0.8 ${project.basedir} mycompany-testing-mytesthook.json ${project.basedir}/target/loaded-target-schemas **/*.json ``` ## 第 2 步：生成 Hook 项目包 生成你的 Hook 项目包。 CloudFormation CLI 创建空的处理程序函数，这些函数对应于 Hook 规范中定义的目标生命周期中的特定 Hook 操作。 ``` cfn generate ``` 该命令将返回以下输出。 ``` Generated files for MyCompany::Testing::MyTestHook ``` **注意** 确保您的 Lambda 运行时 up-to-date避免使用已弃用的版本。有关更多信息，请参阅[更新资源类型的 Lambda 运行时和挂钩](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html)。 ## 第 3 步：添加 Hook 处理程序 将您自己的 Hook 处理程序运行时代码添加到您选择实现的处理程序中。例如，您可以添加以下用于记录的代码。 ``` logger.log("Internal testing Hook triggered for target: " + request.getHookContext().getTargetName()); ``` CloudFormation CLI 会生成一个普通的旧 Java 对象 (Java POJO)。以下是生成的输出示例`AWS::S3::Bucket`。 **Example awss3 .java BucketTargetModel** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import... @Data @NoArgsConstructor @EqualsAndHashCode(callSuper = true) @ToString(callSuper = true) @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class AwsS3BucketTargetModel extends ResourceHookTargetModel { @JsonIgnore private static final TypeReference TARGET_REFERENCE = new TypeReference() {}; @JsonIgnore private static final TypeReference MODEL_REFERENCE = new TypeReference() {}; @JsonIgnore public static final String TARGET_TYPE_NAME = "AWS::S3::Bucket"; @JsonIgnore public TypeReference getHookTargetTypeReference() { return TARGET_REFERENCE; } @JsonIgnore public TypeReference getTargetModelTypeReference() { return MODEL_REFERENCE; } } ``` **Example AwsS3Bucket.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @EqualsAndHashCode(callSuper = true) @ToString(callSuper = true) @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class AwsS3Bucket extends ResourceHookTarget { @JsonIgnore public static final String TYPE_NAME = "AWS::S3::Bucket"; @JsonIgnore public static final String IDENTIFIER_KEY_ID = "/properties/Id"; @JsonProperty("InventoryConfigurations") private List inventoryConfigurations; @JsonProperty("WebsiteConfiguration") private WebsiteConfiguration websiteConfiguration; @JsonProperty("DualStackDomainName") private String dualStackDomainName; @JsonProperty("AccessControl") private String accessControl; @JsonProperty("AnalyticsConfigurations") private List analyticsConfigurations; @JsonProperty("AccelerateConfiguration") private AccelerateConfiguration accelerateConfiguration; @JsonProperty("PublicAccessBlockConfiguration") private PublicAccessBlockConfiguration publicAccessBlockConfiguration; @JsonProperty("BucketName") private String bucketName; @JsonProperty("RegionalDomainName") private String regionalDomainName; @JsonProperty("OwnershipControls") private OwnershipControls ownershipControls; @JsonProperty("ObjectLockConfiguration") private ObjectLockConfiguration objectLockConfiguration; @JsonProperty("ObjectLockEnabled") private Boolean objectLockEnabled; @JsonProperty("LoggingConfiguration") private LoggingConfiguration loggingConfiguration; @JsonProperty("ReplicationConfiguration") private ReplicationConfiguration replicationConfiguration; @JsonProperty("Tags") private List tags; @JsonProperty("DomainName") private String domainName; @JsonProperty("BucketEncryption") private BucketEncryption bucketEncryption; @JsonProperty("WebsiteURL") private String websiteURL; @JsonProperty("NotificationConfiguration") private NotificationConfiguration notificationConfiguration; @JsonProperty("LifecycleConfiguration") private LifecycleConfiguration lifecycleConfiguration; @JsonProperty("VersioningConfiguration") private VersioningConfiguration versioningConfiguration; @JsonProperty("MetricsConfigurations") private List metricsConfigurations; @JsonProperty("IntelligentTieringConfigurations") private List intelligentTieringConfigurations; @JsonProperty("CorsConfiguration") private CorsConfiguration corsConfiguration; @JsonProperty("Id") private String id; @JsonProperty("Arn") private String arn; @JsonIgnore public JSONObject getPrimaryIdentifier() { final JSONObject identifier = new JSONObject(); if (this.getId() != null) { identifier.put(IDENTIFIER_KEY_ID, this.getId()); } // only return the identifier if it can be used, i.e. if all components are present return identifier.length() == 1 ? identifier : null; } @JsonIgnore public List getAdditionalIdentifiers() { final List identifiers = new ArrayList(); // only return the identifiers if any can be used return identifiers.isEmpty() ? null : identifiers; } } ``` **Example BucketEncryption.java** ``` package software.amazon.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class BucketEncryption { @JsonProperty("ServerSideEncryptionConfiguration") private List serverSideEncryptionConfiguration; } ``` **Example ServerSideEncryptionRule.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class ServerSideEncryptionRule { @JsonProperty("BucketKeyEnabled") private Boolean bucketKeyEnabled; @JsonProperty("ServerSideEncryptionByDefault") private ServerSideEncryptionByDefault serverSideEncryptionByDefault; } ``` **Example ServerSideEncryptionByDefault.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class ServerSideEncryptionByDefault { @JsonProperty("SSEAlgorithm") private String sSEAlgorithm; @JsonProperty("KMSMasterKeyID") private String kMSMasterKeyID; } ``` 使用 POJOs 生成的，您现在可以编写实际实现 Hook 功能的处理程序。在此示例中，为处理程序实现`preCreate`和`preUpdate`调用点。 ## 第 4 步：实现 Hook 处理程序 **Topics** + [编码 API 客户端生成器](#java-code-api-client-builder) + [对 API 请求生成器进行编码](#code-the-api-request-maker) + [实现帮助程序代码](#implement-helper-code) + [实现基本处理程序](#implement-base-hook-handler) + [实现处理`preCreate`程序](#implementing-precreate-handler) + [对`preCreate`处理程序进行编码](#coding-the-precreate-handler) + [更新`preCreate`测试](#updating-the-precreate-handler) + [实现处理`preUpdate`程序](#implementing-preupdate-handler) + [对`preUpdate`处理程序进行编码](#coding-preupdate-handler) + [更新`preUpdate`测试](#update-the-preupdate-handler) + [实现处理`preDelete`程序](#implement-the-predelete-hander) + [对`preDelete`处理程序进行编码](#code-the-predelete-handler) + [更新处理`preDelete`程序](#update-the-predelete-handler) ### 编码 API 客户端生成器 1. 在 IDE 中，打开位于`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`ClientBuilder.java`文件。 1. 用以下代码替换`ClientBuilder.java`文件的全部内容。 **Example ClientBuilder.java** ``` package com.awscommunity.kms.encryptionsettings; import software.amazon.awssdk.services.ec2.Ec2Client; import software.amazon.cloudformation.HookLambdaWrapper; /** * Describes static HTTP clients (to consume less memory) for API calls that * this hook makes to a number of AWS services. */ public final class ClientBuilder { private ClientBuilder() { } /** * Create an HTTP client for Amazon EC2. * * @return Ec2Client An {@link Ec2Client} object. */ public static Ec2Client getEc2Client() { return Ec2Client.builder().httpClient(HookLambdaWrapper.HTTP_CLIENT).build(); } } ``` ### 对 API 请求生成器进行编码 1. 在 IDE 中，打开位于`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`Translator.java`文件。 1. 用以下代码替换`Translator.java`文件的全部内容。 **Example Translator.java** ``` package com.mycompany.testing.mytesthook; import software.amazon.awssdk.services.s3.model.GetBucketEncryptionRequest; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.sqs.model.ListQueuesRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; /** * This class is a centralized placeholder for * - api request construction * - object translation to/from aws sdk */ public class Translator { static ListBucketsRequest translateToListBucketsRequest(final HookTargetModel targetModel) { return ListBucketsRequest.builder().build(); } static ListQueuesRequest translateToListQueuesRequest(final String nextToken) { return ListQueuesRequest.builder().nextToken(nextToken).build(); } static ListBucketsRequest createListBucketsRequest() { return ListBucketsRequest.builder().build(); } static ListQueuesRequest createListQueuesRequest() { return createListQueuesRequest(null); } static ListQueuesRequest createListQueuesRequest(final String nextToken) { return ListQueuesRequest.builder().nextToken(nextToken).build(); } static GetBucketEncryptionRequest createGetBucketEncryptionRequest(final String bucket) { return GetBucketEncryptionRequest.builder().bucket(bucket).build(); } } ``` ### 实现帮助程序代码 1. 在 IDE 中，打开位于`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`AbstractTestBase.java`文件。 1. 用以下代码替换`AbstractTestBase.java`文件的全部内容。 **Example Translator.java** ``` package com.mycompany.testing.mytesthook; import com.google.common.collect.ImmutableMap; import org.mockito.Mockito; import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider; import software.amazon.awssdk.auth.credentials.AwsSessionCredentials; import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; import software.amazon.awssdk.awscore.AwsRequest; import software.amazon.awssdk.awscore.AwsRequestOverrideConfiguration; import software.amazon.awssdk.awscore.AwsResponse; import software.amazon.awssdk.core.SdkClient; import software.amazon.awssdk.core.pagination.sync.SdkIterable; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.Credentials; import software.amazon.cloudformation.proxy.LoggerProxy; import software.amazon.cloudformation.proxy.OperationStatus; import software.amazon.cloudformation.proxy.ProgressEvent; import software.amazon.cloudformation.proxy.ProxyClient; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; import javax.annotation.Nonnull; import java.time.Duration; import java.util.concurrent.CompletableFuture; import java.util.function.Function; import java.util.function.Supplier; import static org.assertj.core.api.Assertions.assertThat; @lombok.Getter public class AbstractTestBase { protected final AwsSessionCredentials awsSessionCredential; protected final AwsCredentialsProvider v2CredentialsProvider; protected final AwsRequestOverrideConfiguration configuration; protected final LoggerProxy loggerProxy; protected final Supplier awsLambdaRuntime = () -> Duration.ofMinutes(15).toMillis(); protected final AmazonWebServicesClientProxy proxy; protected final Credentials mockCredentials = new Credentials("mockAccessId", "mockSecretKey", "mockSessionToken"); @lombok.Setter private SdkClient serviceClient; protected AbstractTestBase() { loggerProxy = Mockito.mock(LoggerProxy.class); awsSessionCredential = AwsSessionCredentials.create(mockCredentials.getAccessKeyId(), mockCredentials.getSecretAccessKey(), mockCredentials.getSessionToken()); v2CredentialsProvider = StaticCredentialsProvider.create(awsSessionCredential); configuration = AwsRequestOverrideConfiguration.builder() .credentialsProvider(v2CredentialsProvider) .build(); proxy = new AmazonWebServicesClientProxy( loggerProxy, mockCredentials, awsLambdaRuntime ) { @Override public ProxyClient newProxy(@Nonnull Supplier client) { return new ProxyClient() { @Override public ResponseT injectCredentialsAndInvokeV2(RequestT request, Function requestFunction) { return proxy.injectCredentialsAndInvokeV2(request, requestFunction); } @Override public CompletableFuture injectCredentialsAndInvokeV2Async(RequestT request, Function> requestFunction) { return proxy.injectCredentialsAndInvokeV2Async(request, requestFunction); } @Override public > IterableT injectCredentialsAndInvokeIterableV2(RequestT request, Function requestFunction) { return proxy.injectCredentialsAndInvokeIterableV2(request, requestFunction); } @SuppressWarnings("unchecked") @Override public ClientT client() { return (ClientT) serviceClient; } }; } }; } protected void assertResponse(final ProgressEvent response, final OperationStatus expectedStatus, final String expectedMsg) { assertThat(response).isNotNull(); assertThat(response.getStatus()).isEqualTo(expectedStatus); assertThat(response.getCallbackContext()).isNull(); assertThat(response.getCallbackDelaySeconds()).isEqualTo(0); assertThat(response.getMessage()).isNotNull(); assertThat(response.getMessage()).isEqualTo(expectedMsg); } protected HookTargetModel createHookTargetModel(final Object resourceProperties) { return HookTargetModel.of(ImmutableMap.of("ResourceProperties", resourceProperties)); } protected HookTargetModel createHookTargetModel(final Object resourceProperties, final Object previousResourceProperties) { return HookTargetModel.of( ImmutableMap.of( "ResourceProperties", resourceProperties, "PreviousResourceProperties", previousResourceProperties ) ); } } ``` ### 实现基本处理程序 1. 在 IDE 中，打开位于`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`BaseHookHandlerStd.java`文件。 1. 用以下代码替换`BaseHookHandlerStd.java`文件的全部内容。 **Example Translator.java** ``` package com.mycompany.testing.mytesthook; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueue; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.sqs.SqsClient; import software.amazon.cloudformation.exceptions.UnsupportedTargetException; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.ProgressEvent; import software.amazon.cloudformation.proxy.ProxyClient; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; public abstract class BaseHookHandlerStd extends BaseHookHandler { public static final String HOOK_TYPE_NAME = "MyCompany::Testing::MyTestHook"; protected Logger logger; @Override public ProgressEvent handleRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final Logger logger, final TypeConfigurationModel typeConfiguration ) { this.logger = logger; final String targetName = request.getHookContext().getTargetName(); final ProgressEvent result; if (AwsS3Bucket.TYPE_NAME.equals(targetName)) { result = handleS3BucketRequest( proxy, request, callbackContext != null ? callbackContext : new CallbackContext(), proxy.newProxy(ClientBuilder::createS3Client), typeConfiguration ); } else if (AwsSqsQueue.TYPE_NAME.equals(targetName)) { result = handleSqsQueueRequest( proxy, request, callbackContext != null ? callbackContext : new CallbackContext(), proxy.newProxy(ClientBuilder::createSqsClient), typeConfiguration ); } else { throw new UnsupportedTargetException(targetName); } log( String.format( "Result for [%s] invocation for target [%s] returned status [%s] with message [%s]", request.getHookContext().getInvocationPoint(), targetName, result.getStatus(), result.getMessage() ) ); return result; } protected abstract ProgressEvent handleS3BucketRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final ProxyClient proxyClient, final TypeConfigurationModel typeConfiguration ); protected abstract ProgressEvent handleSqsQueueRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final ProxyClient proxyClient, final TypeConfigurationModel typeConfiguration ); protected void log(final String message) { if (logger != null) { logger.log(message); } else { System.out.println(message); } } } ``` ### 实现处理`preCreate`程序 `preCreate`处理程序验证`AWS::S3::Bucket`或`AWS::SQS::Queue`资源的服务器端加密设置。 + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过： + Amazon S3 存储桶加密已设置。 + 已为该存储桶启用了 Amazon S3 存储桶密钥。 + 为 Amazon S3 存储桶设置的加密算法是所需的正确算法。 + 密 AWS Key Management Service 钥 ID 已设置。 + 对于`AWS::SQS::Queue`资源，只有在满足以下条件时，Hook 才会通过： + 密 AWS Key Management Service 钥 ID 已设置。 ### 对`preCreate`处理程序进行编码 1. 在 IDE 中，打开位于`src/main/java/software/mycompany/testing/mytesthook`文件夹中的`PreCreateHookHandler.java`文件。 1. 用以下代码替换`PreCreateHookHandler.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3BucketTargetModel; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.BucketEncryption; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionByDefault; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionRule; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueue; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueueTargetModel; import org.apache.commons.collections.CollectionUtils; import org.apache.commons.lang3.StringUtils; import software.amazon.cloudformation.exceptions.UnsupportedTargetException; import software.amazon.cloudformation.proxy.HandlerErrorCode; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.hook.HookStatus; import software.amazon.cloudformation.proxy.hook.HookProgressEvent; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.ResourceHookTargetModel; import java.util.List; public class PreCreateHookHandler extends BaseHookHandler { @Override public HookProgressEvent handleRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final Logger logger, final TypeConfigurationModel typeConfiguration) { final String targetName = request.getHookContext().getTargetName(); if ("AWS::S3::Bucket".equals(targetName)) { final ResourceHookTargetModel targetModel = request.getHookContext().getTargetModel(AwsS3BucketTargetModel.class); final AwsS3Bucket bucket = targetModel.getResourceProperties(); final String encryptionAlgorithm = typeConfiguration.getEncryptionAlgorithm(); return validateS3BucketEncryption(bucket, encryptionAlgorithm); } else if ("AWS::SQS::Queue".equals(targetName)) { final ResourceHookTargetModel targetModel = request.getHookContext().getTargetModel(AwsSqsQueueTargetModel.class); final AwsSqsQueue queue = targetModel.getResourceProperties(); return validateSQSQueueEncryption(queue); } else { throw new UnsupportedTargetException(targetName); } } private HookProgressEvent validateS3BucketEncryption(final AwsS3Bucket bucket, final String requiredEncryptionAlgorithm) { HookStatus resultStatus = null; String resultMessage = null; if (bucket != null) { final BucketEncryption bucketEncryption = bucket.getBucketEncryption(); if (bucketEncryption != null) { final List serverSideEncryptionRules = bucketEncryption.getServerSideEncryptionConfiguration(); if (CollectionUtils.isNotEmpty(serverSideEncryptionRules)) { for (final ServerSideEncryptionRule rule : serverSideEncryptionRules) { final Boolean bucketKeyEnabled = rule.getBucketKeyEnabled(); if (bucketKeyEnabled) { final ServerSideEncryptionByDefault serverSideEncryptionByDefault = rule.getServerSideEncryptionByDefault(); final String encryptionAlgorithm = serverSideEncryptionByDefault.getSSEAlgorithm(); final String kmsKeyId = serverSideEncryptionByDefault.getKMSMasterKeyID(); // "KMSMasterKeyID" is name of the property for an AWS::S3::Bucket; if (!StringUtils.equals(encryptionAlgorithm, requiredEncryptionAlgorithm) && StringUtils.isBlank(kmsKeyId)) { resultStatus = HookStatus.FAILED; resultMessage = "KMS Key ID not set and SSE Encryption Algorithm is incorrect for bucket with name: " + bucket.getBucketName(); } else if (!StringUtils.equals(encryptionAlgorithm, requiredEncryptionAlgorithm)) { resultStatus = HookStatus.FAILED; resultMessage = "SSE Encryption Algorithm is incorrect for bucket with name: " + bucket.getBucketName(); } else if (StringUtils.isBlank(kmsKeyId)) { resultStatus = HookStatus.FAILED; resultMessage = "KMS Key ID not set for bucket with name: " + bucket.getBucketName(); } else { resultStatus = HookStatus.SUCCESS; resultMessage = "Successfully invoked PreCreateHookHandler for target: AWS::S3::Bucket"; } } else { resultStatus = HookStatus.FAILED; resultMessage = "Bucket key not enabled for bucket with name: " + bucket.getBucketName(); } if (resultStatus == HookStatus.FAILED) { break; } } } else { resultStatus = HookStatus.FAILED; resultMessage = "No SSE Encryption configurations for bucket with name: " + bucket.getBucketName(); } } else { resultStatus = HookStatus.FAILED; resultMessage = "Bucket Encryption not enabled for bucket with name: " + bucket.getBucketName(); } } else { resultStatus = HookStatus.FAILED; resultMessage = "Resource properties for S3 Bucket target model are empty"; } return HookProgressEvent.builder() .status(resultStatus) .message(resultMessage) .errorCode(resultStatus == HookStatus.FAILED ? HandlerErrorCode.ResourceConflict : null) .build(); } private HookProgressEvent validateSQSQueueEncryption(final AwsSqsQueue queue) { if (queue == null) { return HookProgressEvent.builder() .status(HookStatus.FAILED) .message("Resource properties for SQS Queue target model are empty") .errorCode(HandlerErrorCode.ResourceConflict) .build(); } final String kmsKeyId = queue.getKmsMasterKeyId(); // "KmsMasterKeyId" is name of the property for an AWS::SQS::Queue if (StringUtils.isBlank(kmsKeyId)) { return HookProgressEvent.builder() .status(HookStatus.FAILED) .message("Server side encryption turned off for queue with name: " + queue.getQueueName()) .errorCode(HandlerErrorCode.ResourceConflict) .build(); } return HookProgressEvent.builder() .status(HookStatus.SUCCESS) .message("Successfully invoked PreCreateHookHandler for target: AWS::SQS::Queue") .build(); } } ``` ### 更新`preCreate`测试 1. 在 IDE 中，打开位于`src/test/java/software/mycompany/testing/mytesthook`文件夹中的`PreCreateHandlerTest.java`文件。 1. 用以下代码替换`PreCreateHandlerTest.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.google.common.collect.ImmutableMap; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.BucketEncryption; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionByDefault; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionRule; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueue; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import software.amazon.cloudformation.exceptions.UnsupportedTargetException; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.HandlerErrorCode; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.hook.HookContext; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.HookProgressEvent; import software.amazon.cloudformation.proxy.hook.HookStatus; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; import java.util.Collections; import java.util.Map; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatExceptionOfType; import static org.mockito.Mockito.mock; @ExtendWith(MockitoExtension.class) public class PreCreateHookHandlerTest { @Mock private AmazonWebServicesClientProxy proxy; @Mock private Logger logger; @BeforeEach public void setup() { proxy = mock(AmazonWebServicesClientProxy.class); logger = mock(Logger.class); } @Test public void handleRequest_awsSqsQueueSuccess() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsSqsQueue queue = buildSqsQueue("MyQueue", "KmsKey"); final HookTargetModel targetModel = createHookTargetModel(queue); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::SQS::Queue").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.SUCCESS, "Successfully invoked PreCreateHookHandler for target: AWS::SQS::Queue"); } @Test public void handleRequest_awsS3BucketSuccess() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsS3Bucket bucket = buildAwsS3Bucket("amzn-s3-demo-bucket", true, "AES256", "KmsKey"); final HookTargetModel targetModel = createHookTargetModel(bucket); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.SUCCESS, "Successfully invoked PreCreateHookHandler for target: AWS::S3::Bucket"); } @Test public void handleRequest_awsS3BucketFail_bucketKeyNotEnabled() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsS3Bucket bucket = buildAwsS3Bucket("amzn-s3-demo-bucket", false, "AES256", "KmsKey"); final HookTargetModel targetModel = createHookTargetModel(bucket); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, "Bucket key not enabled for bucket with name: amzn-s3-demo-bucket"); } @Test public void handleRequest_awsS3BucketFail_incorrectSSEEncryptionAlgorithm() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsS3Bucket bucket = buildAwsS3Bucket("amzn-s3-demo-bucket", true, "SHA512", "KmsKey"); final HookTargetModel targetModel = createHookTargetModel(bucket); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, "SSE Encryption Algorithm is incorrect for bucket with name: amzn-s3-demo-bucket"); } @Test public void handleRequest_awsS3BucketFail_kmsKeyIdNotSet() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsS3Bucket bucket = buildAwsS3Bucket("amzn-s3-demo-bucket", true, "AES256", null); final HookTargetModel targetModel = createHookTargetModel(bucket); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, "KMS Key ID not set for bucket with name: amzn-s3-demo-bucket"); } @Test public void handleRequest_awsSqsQueueFail_serverSideEncryptionOff() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final AwsSqsQueue queue = buildSqsQueue("MyQueue", null); final HookTargetModel targetModel = createHookTargetModel(queue); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::SQS::Queue").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, "Server side encryption turned off for queue with name: MyQueue"); } @Test public void handleRequest_unsupportedTarget() { final PreCreateHookHandler handler = new PreCreateHookHandler(); final Map unsupportedTarget = ImmutableMap.of("ResourceName", "MyUnsupportedTarget"); final HookTargetModel targetModel = createHookTargetModel(unsupportedTarget); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::Unsupported::Target").targetModel(targetModel).build()) .build(); assertThatExceptionOfType(UnsupportedTargetException.class) .isThrownBy(() -> handler.handleRequest(proxy, request, null, logger, typeConfiguration)) .withMessageContaining("Unsupported target") .withMessageContaining("AWS::Unsupported::Target") .satisfies(e -> assertThat(e.getErrorCode()).isEqualTo(HandlerErrorCode.InvalidRequest)); } private void assertResponse(final HookProgressEvent response, final HookStatus expectedStatus, final String expectedErrorMsg) { assertThat(response).isNotNull(); assertThat(response.getStatus()).isEqualTo(expectedStatus); assertThat(response.getCallbackContext()).isNull(); assertThat(response.getCallbackDelaySeconds()).isEqualTo(0); assertThat(response.getMessage()).isNotNull(); assertThat(response.getMessage()).isEqualTo(expectedErrorMsg); } private HookTargetModel createHookTargetModel(final Object resourceProperties) { return HookTargetModel.of(ImmutableMap.of("ResourceProperties", resourceProperties)); } @SuppressWarnings("SameParameterValue") private AwsSqsQueue buildSqsQueue(final String queueName, final String kmsKeyId) { return AwsSqsQueue.builder() .queueName(queueName) .kmsMasterKeyId(kmsKeyId) // "KmsMasterKeyId" is name of the property for an AWS::SQS::Queue .build(); } @SuppressWarnings("SameParameterValue") private AwsS3Bucket buildAwsS3Bucket( final String bucketName, final Boolean bucketKeyEnabled, final String sseAlgorithm, final String kmsKeyId ) { return AwsS3Bucket.builder() .bucketName(bucketName) .bucketEncryption( BucketEncryption.builder() .serverSideEncryptionConfiguration( Collections.singletonList( ServerSideEncryptionRule.builder() .bucketKeyEnabled(bucketKeyEnabled) .serverSideEncryptionByDefault( ServerSideEncryptionByDefault.builder() .sSEAlgorithm(sseAlgorithm) .kMSMasterKeyID(kmsKeyId) // "KMSMasterKeyID" is name of the property for an AWS::S3::Bucket .build() ).build() ) ).build() ).build(); } } ``` ### 实现处理`preUpdate`程序 实现一个`preUpdate`处理程序，该处理程序在处理程序中所有指定目标的更新操作之前启动。该`preUpdate`处理程序完成以下任务： + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过： + Amazon S3 存储桶的存储桶加密算法尚未修改。 ### 对`preUpdate`处理程序进行编码 1. 在 IDE 中，打开位于`src/main/java/software/mycompany/testing/mytesthook`文件夹中的`PreUpdateHookHandler.java`文件。 1. 用以下代码替换`PreUpdateHookHandler.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3BucketTargetModel; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionRule; import org.apache.commons.lang3.StringUtils; import software.amazon.cloudformation.exceptions.UnsupportedTargetException; import software.amazon.cloudformation.proxy.HandlerErrorCode; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.hook.HookStatus; import software.amazon.cloudformation.proxy.hook.HookProgressEvent; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.ResourceHookTargetModel; import java.util.List; public class PreUpdateHookHandler extends BaseHookHandler { @Override public HookProgressEvent handleRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final Logger logger, final TypeConfigurationModel typeConfiguration) { final String targetName = request.getHookContext().getTargetName(); if ("AWS::S3::Bucket".equals(targetName)) { final ResourceHookTargetModel targetModel = request.getHookContext().getTargetModel(AwsS3BucketTargetModel.class); final AwsS3Bucket bucketProperties = targetModel.getResourceProperties(); final AwsS3Bucket previousBucketProperties = targetModel.getPreviousResourceProperties(); return validateBucketEncryptionRulesNotUpdated(bucketProperties, previousBucketProperties); } else { throw new UnsupportedTargetException(targetName); } } private HookProgressEvent validateBucketEncryptionRulesNotUpdated(final AwsS3Bucket resourceProperties, final AwsS3Bucket previousResourceProperties) { final List bucketEncryptionConfigs = resourceProperties.getBucketEncryption().getServerSideEncryptionConfiguration(); final List previousBucketEncryptionConfigs = previousResourceProperties.getBucketEncryption().getServerSideEncryptionConfiguration(); if (bucketEncryptionConfigs.size() != previousBucketEncryptionConfigs.size()) { return HookProgressEvent.builder() .status(HookStatus.FAILED) .errorCode(HandlerErrorCode.NotUpdatable) .message( String.format( "Current number of bucket encryption configs does not match previous. Current has %d configs while previously there were %d configs", bucketEncryptionConfigs.size(), previousBucketEncryptionConfigs.size() ) ).build(); } for (int i = 0; i < bucketEncryptionConfigs.size(); ++i) { final String currentEncryptionAlgorithm = bucketEncryptionConfigs.get(i).getServerSideEncryptionByDefault().getSSEAlgorithm(); final String previousEncryptionAlgorithm = previousBucketEncryptionConfigs.get(i).getServerSideEncryptionByDefault().getSSEAlgorithm(); if (!StringUtils.equals(currentEncryptionAlgorithm, previousEncryptionAlgorithm)) { return HookProgressEvent.builder() .status(HookStatus.FAILED) .errorCode(HandlerErrorCode.NotUpdatable) .message( String.format( "Bucket Encryption algorithm can not be changed once set. The encryption algorithm was changed to '%s' from '%s'.", currentEncryptionAlgorithm, previousEncryptionAlgorithm ) ) .build(); } } return HookProgressEvent.builder() .status(HookStatus.SUCCESS) .message("Successfully invoked PreUpdateHookHandler for target: AWS::SQS::Queue") .build(); } } ``` ### 更新`preUpdate`测试 1. 在 IDE 中，打开该`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`PreUpdateHandlerTest.java`文件。 1. 用以下代码替换`PreUpdateHandlerTest.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.google.common.collect.ImmutableMap; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.BucketEncryption; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionByDefault; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.ServerSideEncryptionRule; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; import software.amazon.cloudformation.exceptions.UnsupportedTargetException; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.HandlerErrorCode; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.hook.HookContext; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.HookProgressEvent; import software.amazon.cloudformation.proxy.hook.HookStatus; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; import java.util.Arrays; import java.util.stream.Stream; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatExceptionOfType; import static org.mockito.Mockito.mock; @ExtendWith(MockitoExtension.class) public class PreUpdateHookHandlerTest { @Mock private AmazonWebServicesClientProxy proxy; @Mock private Logger logger; @BeforeEach public void setup() { proxy = mock(AmazonWebServicesClientProxy.class); logger = mock(Logger.class); } @Test public void handleRequest_awsS3BucketSuccess() { final PreUpdateHookHandler handler = new PreUpdateHookHandler(); final ServerSideEncryptionRule serverSideEncryptionRule = buildServerSideEncryptionRule("AES256"); final AwsS3Bucket resourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", serverSideEncryptionRule); final AwsS3Bucket previousResourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", serverSideEncryptionRule); final HookTargetModel targetModel = createHookTargetModel(resourceProperties, previousResourceProperties); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.SUCCESS, "Successfully invoked PreUpdateHookHandler for target: AWS::SQS::Queue"); } @Test public void handleRequest_awsS3BucketFail_bucketEncryptionConfigsDontMatch() { final PreUpdateHookHandler handler = new PreUpdateHookHandler(); final ServerSideEncryptionRule[] serverSideEncryptionRules = Stream.of("AES256", "SHA512", "AES32") .map(this::buildServerSideEncryptionRule) .toArray(ServerSideEncryptionRule[]::new); final AwsS3Bucket resourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", serverSideEncryptionRules[0]); final AwsS3Bucket previousResourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", serverSideEncryptionRules); final HookTargetModel targetModel = createHookTargetModel(resourceProperties, previousResourceProperties); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, "Current number of bucket encryption configs does not match previous. Current has 1 configs while previously there were 3 configs"); } @Test public void handleRequest_awsS3BucketFail_bucketEncryptionAlgorithmDoesNotMatch() { final PreUpdateHookHandler handler = new PreUpdateHookHandler(); final AwsS3Bucket resourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", buildServerSideEncryptionRule("SHA512")); final AwsS3Bucket previousResourceProperties = buildAwsS3Bucket("amzn-s3-demo-bucket", buildServerSideEncryptionRule("AES256")); final HookTargetModel targetModel = createHookTargetModel(resourceProperties, previousResourceProperties); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::S3::Bucket").targetModel(targetModel).build()) .build(); final HookProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); assertResponse(response, HookStatus.FAILED, String.format("Bucket Encryption algorithm can not be changed once set. The encryption algorithm was changed to '%s' from '%s'.", "SHA512", "AES256")); } @Test public void handleRequest_unsupportedTarget() { final PreUpdateHookHandler handler = new PreUpdateHookHandler(); final Object resourceProperties = ImmutableMap.of("FileSizeLimit", 256); final Object previousResourceProperties = ImmutableMap.of("FileSizeLimit", 512); final HookTargetModel targetModel = createHookTargetModel(resourceProperties, previousResourceProperties); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder().encryptionAlgorithm("AES256").build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext(HookContext.builder().targetName("AWS::Unsupported::Target").targetModel(targetModel).build()) .build(); assertThatExceptionOfType(UnsupportedTargetException.class) .isThrownBy(() -> handler.handleRequest(proxy, request, null, logger, typeConfiguration)) .withMessageContaining("Unsupported target") .withMessageContaining("AWS::Unsupported::Target") .satisfies(e -> assertThat(e.getErrorCode()).isEqualTo(HandlerErrorCode.InvalidRequest)); } private void assertResponse(final HookProgressEvent response, final HookStatus expectedStatus, final String expectedErrorMsg) { assertThat(response).isNotNull(); assertThat(response.getStatus()).isEqualTo(expectedStatus); assertThat(response.getCallbackContext()).isNull(); assertThat(response.getCallbackDelaySeconds()).isEqualTo(0); assertThat(response.getMessage()).isNotNull(); assertThat(response.getMessage()).isEqualTo(expectedErrorMsg); } private HookTargetModel createHookTargetModel(final Object resourceProperties, final Object previousResourceProperties) { return HookTargetModel.of( ImmutableMap.of( "ResourceProperties", resourceProperties, "PreviousResourceProperties", previousResourceProperties ) ); } @SuppressWarnings("SameParameterValue") private AwsS3Bucket buildAwsS3Bucket( final String bucketName, final ServerSideEncryptionRule ...serverSideEncryptionRules ) { return AwsS3Bucket.builder() .bucketName(bucketName) .bucketEncryption( BucketEncryption.builder() .serverSideEncryptionConfiguration( Arrays.asList(serverSideEncryptionRules) ).build() ).build(); } private ServerSideEncryptionRule buildServerSideEncryptionRule(final String encryptionAlgorithm) { return ServerSideEncryptionRule.builder() .bucketKeyEnabled(true) .serverSideEncryptionByDefault( ServerSideEncryptionByDefault.builder() .sSEAlgorithm(encryptionAlgorithm) .build() ).build(); } } ``` ### 实现处理`preDelete`程序 实现一个`preDelete`处理程序，该处理程序在处理程序中所有指定目标的删除操作之前启动。该`preDelete`处理程序完成以下任务： + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过： + 验证删除资源后，账户中是否存在所需的最低投诉资源。 + 所需的最低投诉资源数量在 Hook 的类型配置中设置。 ### 对`preDelete`处理程序进行编码 1. 在 IDE 中，打开该`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`PreDeleteHookHandler.java`文件。 1. 用以下代码替换`PreDeleteHookHandler.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.google.common.annotations.VisibleForTesting; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3BucketTargetModel; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueue; import com.mycompany.testing.mytesthook.model.aws.sqs.queue.AwsSqsQueueTargetModel; import org.apache.commons.lang3.StringUtils; import org.apache.commons.lang3.math.NumberUtils; import software.amazon.awssdk.services.cloudformation.CloudFormationClient; import software.amazon.awssdk.services.cloudformation.model.CloudFormationException; import software.amazon.awssdk.services.cloudformation.model.DescribeStackResourceRequest; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.Bucket; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.sqs.SqsClient; import software.amazon.awssdk.services.sqs.model.GetQueueAttributesRequest; import software.amazon.awssdk.services.sqs.model.GetQueueUrlRequest; import software.amazon.awssdk.services.sqs.model.ListQueuesRequest; import software.amazon.awssdk.services.sqs.model.ListQueuesResponse; import software.amazon.awssdk.services.sqs.model.QueueAttributeName; import software.amazon.awssdk.services.sqs.model.SqsException; import software.amazon.cloudformation.exceptions.CfnGeneralServiceException; import software.amazon.cloudformation.proxy.AmazonWebServicesClientProxy; import software.amazon.cloudformation.proxy.HandlerErrorCode; import software.amazon.cloudformation.proxy.OperationStatus; import software.amazon.cloudformation.proxy.ProgressEvent; import software.amazon.cloudformation.proxy.ProxyClient; import software.amazon.cloudformation.proxy.hook.HookContext; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; import software.amazon.cloudformation.proxy.hook.targetmodel.ResourceHookTargetModel; import java.util.ArrayList; import java.util.Collection; import java.util.HashSet; import java.util.List; import java.util.Objects; import java.util.stream.Collectors; public class PreDeleteHookHandler extends BaseHookHandlerStd { private ProxyClient s3Client; private ProxyClient sqsClient; @Override protected ProgressEvent handleS3BucketRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final ProxyClient proxyClient, final TypeConfigurationModel typeConfiguration ) { final HookContext hookContext = request.getHookContext(); final String targetName = hookContext.getTargetName(); if (!AwsS3Bucket.TYPE_NAME.equals(targetName)) { throw new RuntimeException(String.format("Request target type [%s] is not 'AWS::S3::Bucket'", targetName)); } this.s3Client = proxyClient; final String encryptionAlgorithm = typeConfiguration.getEncryptionAlgorithm(); final int minBuckets = NumberUtils.toInt(typeConfiguration.getMinBuckets()); final ResourceHookTargetModel targetModel = hookContext.getTargetModel(AwsS3BucketTargetModel.class); final List buckets = listBuckets().stream() .filter(b -> !StringUtils.equals(b, targetModel.getResourceProperties().getBucketName())) .collect(Collectors.toList()); final List compliantBuckets = new ArrayList<>(); for (final String bucket : buckets) { if (getBucketSSEAlgorithm(bucket).contains(encryptionAlgorithm)) { compliantBuckets.add(bucket); } if (compliantBuckets.size() >= minBuckets) { return ProgressEvent.builder() .status(OperationStatus.SUCCESS) .message("Successfully invoked PreDeleteHookHandler for target: AWS::S3::Bucket") .build(); } } return ProgressEvent.builder() .status(OperationStatus.FAILED) .errorCode(HandlerErrorCode.NonCompliant) .message(String.format("Failed to meet minimum of [%d] encrypted buckets.", minBuckets)) .build(); } @Override protected ProgressEvent handleSqsQueueRequest( final AmazonWebServicesClientProxy proxy, final HookHandlerRequest request, final CallbackContext callbackContext, final ProxyClient proxyClient, final TypeConfigurationModel typeConfiguration ) { final HookContext hookContext = request.getHookContext(); final String targetName = hookContext.getTargetName(); if (!AwsSqsQueue.TYPE_NAME.equals(targetName)) { throw new RuntimeException(String.format("Request target type [%s] is not 'AWS::SQS::Queue'", targetName)); } this.sqsClient = proxyClient; final int minQueues = NumberUtils.toInt(typeConfiguration.getMinQueues()); final ResourceHookTargetModel targetModel = hookContext.getTargetModel(AwsSqsQueueTargetModel.class); final String queueName = Objects.toString(targetModel.getResourceProperties().get("QueueName"), null); String targetQueueUrl = null; if (queueName != null) { try { targetQueueUrl = sqsClient.injectCredentialsAndInvokeV2( GetQueueUrlRequest.builder().queueName( queueName ).build(), sqsClient.client()::getQueueUrl ).queueUrl(); } catch (SqsException e) { log(String.format("Error while calling GetQueueUrl API for queue name [%s]: %s", queueName, e.getMessage())); } } else { log("Queue name is empty, attempting to get queue's physical ID"); try { final ProxyClient cfnClient = proxy.newProxy(ClientBuilder::createCloudFormationClient); targetQueueUrl = cfnClient.injectCredentialsAndInvokeV2( DescribeStackResourceRequest.builder() .stackName(hookContext.getTargetLogicalId()) .logicalResourceId(hookContext.getTargetLogicalId()) .build(), cfnClient.client()::describeStackResource ).stackResourceDetail().physicalResourceId(); } catch (CloudFormationException e) { log(String.format("Error while calling DescribeStackResource API for queue name: %s", e.getMessage())); } } // Creating final variable for the filter lambda final String finalTargetQueueUrl = targetQueueUrl; final List compliantQueues = new ArrayList<>(); String nextToken = null; do { final ListQueuesRequest req = Translator.createListQueuesRequest(nextToken); final ListQueuesResponse res = sqsClient.injectCredentialsAndInvokeV2(req, sqsClient.client()::listQueues); final List queueUrls = res.queueUrls().stream() .filter(q -> !StringUtils.equals(q, finalTargetQueueUrl)) .collect(Collectors.toList()); for (final String queueUrl : queueUrls) { if (isQueueEncrypted(queueUrl)) { compliantQueues.add(queueUrl); } if (compliantQueues.size() >= minQueues) { return ProgressEvent.builder() .status(OperationStatus.SUCCESS) .message("Successfully invoked PreDeleteHookHandler for target: AWS::SQS::Queue") .build(); } nextToken = res.nextToken(); } } while (nextToken != null); return ProgressEvent.builder() .status(OperationStatus.FAILED) .errorCode(HandlerErrorCode.NonCompliant) .message(String.format("Failed to meet minimum of [%d] encrypted queues.", minQueues)) .build(); } private List listBuckets() { try { return s3Client.injectCredentialsAndInvokeV2(Translator.createListBucketsRequest(), s3Client.client()::listBuckets) .buckets() .stream() .map(Bucket::name) .collect(Collectors.toList()); } catch (S3Exception e) { throw new CfnGeneralServiceException("Error while calling S3 ListBuckets API", e); } } @VisibleForTesting Collection getBucketSSEAlgorithm(final String bucket) { try { return s3Client.injectCredentialsAndInvokeV2(Translator.createGetBucketEncryptionRequest(bucket), s3Client.client()::getBucketEncryption) .serverSideEncryptionConfiguration() .rules() .stream() .filter(r -> Objects.nonNull(r.applyServerSideEncryptionByDefault())) .map(r -> r.applyServerSideEncryptionByDefault().sseAlgorithmAsString()) .collect(Collectors.toSet()); } catch (S3Exception e) { return new HashSet<>(); } } @VisibleForTesting boolean isQueueEncrypted(final String queueUrl) { try { final GetQueueAttributesRequest request = GetQueueAttributesRequest.builder() .queueUrl(queueUrl) .attributeNames(QueueAttributeName.KMS_MASTER_KEY_ID) .build(); final String kmsKeyId = sqsClient.injectCredentialsAndInvokeV2(request, sqsClient.client()::getQueueAttributes) .attributes() .get(QueueAttributeName.KMS_MASTER_KEY_ID); return StringUtils.isNotBlank(kmsKeyId); } catch (SqsException e) { throw new CfnGeneralServiceException("Error while calling SQS GetQueueAttributes API", e); } } } ``` ### 更新处理`preDelete`程序 1. 在 IDE 中，打开该`src/main/java/com/mycompany/testing/mytesthook`文件夹中的`PreDeleteHookHandler.java`文件。 1. 用以下代码替换`PreDeleteHookHandler.java`文件的全部内容。 ``` package com.mycompany.testing.mytesthook; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.mycompany.testing.mytesthook.model.aws.s3.bucket.AwsS3Bucket; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.Mock; import org.mockito.Mockito; import org.mockito.junit.jupiter.MockitoExtension; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.Bucket; import software.amazon.awssdk.services.s3.model.GetBucketEncryptionRequest; import software.amazon.awssdk.services.s3.model.GetBucketEncryptionResponse; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; import software.amazon.awssdk.services.s3.model.S3Exception; import software.amazon.awssdk.services.s3.model.ServerSideEncryptionByDefault; import software.amazon.awssdk.services.s3.model.ServerSideEncryptionConfiguration; import software.amazon.awssdk.services.s3.model.ServerSideEncryptionRule; import software.amazon.awssdk.services.sqs.SqsClient; import software.amazon.awssdk.services.sqs.model.GetQueueAttributesRequest; import software.amazon.awssdk.services.sqs.model.GetQueueAttributesResponse; import software.amazon.awssdk.services.sqs.model.GetQueueUrlRequest; import software.amazon.awssdk.services.sqs.model.GetQueueUrlResponse; import software.amazon.awssdk.services.sqs.model.ListQueuesRequest; import software.amazon.awssdk.services.sqs.model.ListQueuesResponse; import software.amazon.awssdk.services.sqs.model.QueueAttributeName; import software.amazon.cloudformation.proxy.Logger; import software.amazon.cloudformation.proxy.OperationStatus; import software.amazon.cloudformation.proxy.ProgressEvent; import software.amazon.cloudformation.proxy.hook.HookContext; import software.amazon.cloudformation.proxy.hook.HookHandlerRequest; import software.amazon.cloudformation.proxy.hook.targetmodel.HookTargetModel; import java.util.Arrays; import java.util.Collection; import java.util.HashMap; import java.util.List; import java.util.stream.Collectors; import static org.mockito.ArgumentMatchers.any; import static org.mockito.Mockito.mock; import static org.mockito.Mockito.never; import static org.mockito.Mockito.times; import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; @ExtendWith(MockitoExtension.class) public class PreDeleteHookHandlerTest extends AbstractTestBase { @Mock private S3Client s3Client; @Mock private SqsClient sqsClient; @Mock private Logger logger; @BeforeEach public void setup() { s3Client = mock(S3Client.class); sqsClient = mock(SqsClient.class); logger = mock(Logger.class); } @Test public void handleRequest_awsS3BucketSuccess() { final PreDeleteHookHandler handler = Mockito.spy(new PreDeleteHookHandler()); final List bucketList = ImmutableList.of( Bucket.builder().name("bucket1").build(), Bucket.builder().name("bucket2").build(), Bucket.builder().name("toBeDeletedBucket").build(), Bucket.builder().name("bucket3").build(), Bucket.builder().name("bucket4").build(), Bucket.builder().name("bucket5").build() ); final ListBucketsResponse mockResponse = ListBucketsResponse.builder().buckets(bucketList).build(); when(s3Client.listBuckets(any(ListBucketsRequest.class))).thenReturn(mockResponse); when(s3Client.getBucketEncryption(any(GetBucketEncryptionRequest.class))) .thenReturn(buildGetBucketEncryptionResponse("AES256")) .thenReturn(buildGetBucketEncryptionResponse("AES256", "aws:kms")) .thenThrow(S3Exception.builder().message("No Encrypt").build()) .thenReturn(buildGetBucketEncryptionResponse("aws:kms")) .thenReturn(buildGetBucketEncryptionResponse("AES256")); setServiceClient(s3Client); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder() .encryptionAlgorithm("AES256") .minBuckets("3") .build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext( HookContext.builder() .targetName("AWS::S3::Bucket") .targetModel( createHookTargetModel( AwsS3Bucket.builder() .bucketName("toBeDeletedBucket") .build() ) ) .build()) .build(); final ProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); verify(s3Client, times(5)).getBucketEncryption(any(GetBucketEncryptionRequest.class)); verify(handler, never()).getBucketSSEAlgorithm("toBeDeletedBucket"); assertResponse(response, OperationStatus.SUCCESS, "Successfully invoked PreDeleteHookHandler for target: AWS::S3::Bucket"); } @Test public void handleRequest_awsSqsQueueSuccess() { final PreDeleteHookHandler handler = Mockito.spy(new PreDeleteHookHandler()); final List queueUrls = ImmutableList.of( "https://queue1.queue", "https://queue2.queue", "https://toBeDeletedQueue.queue", "https://queue3.queue", "https://queue4.queue", "https://queue5.queue" ); when(sqsClient.getQueueUrl(any(GetQueueUrlRequest.class))) .thenReturn(GetQueueUrlResponse.builder().queueUrl("https://toBeDeletedQueue.queue").build()); when(sqsClient.listQueues(any(ListQueuesRequest.class))) .thenReturn(ListQueuesResponse.builder().queueUrls(queueUrls).build()); when(sqsClient.getQueueAttributes(any(GetQueueAttributesRequest.class))) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(new HashMap<>()).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(new HashMap<>()).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()); setServiceClient(sqsClient); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder() .minQueues("3") .build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext( HookContext.builder() .targetName("AWS::SQS::Queue") .targetModel( createHookTargetModel( ImmutableMap.of("QueueName", "toBeDeletedQueue") ) ) .build()) .build(); final ProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); verify(sqsClient, times(5)).getQueueAttributes(any(GetQueueAttributesRequest.class)); verify(handler, never()).isQueueEncrypted("toBeDeletedQueue"); assertResponse(response, OperationStatus.SUCCESS, "Successfully invoked PreDeleteHookHandler for target: AWS::SQS::Queue"); } @Test public void handleRequest_awsS3BucketFailed() { final PreDeleteHookHandler handler = Mockito.spy(new PreDeleteHookHandler()); final List bucketList = ImmutableList.of( Bucket.builder().name("bucket1").build(), Bucket.builder().name("bucket2").build(), Bucket.builder().name("toBeDeletedBucket").build(), Bucket.builder().name("bucket3").build(), Bucket.builder().name("bucket4").build(), Bucket.builder().name("bucket5").build() ); final ListBucketsResponse mockResponse = ListBucketsResponse.builder().buckets(bucketList).build(); when(s3Client.listBuckets(any(ListBucketsRequest.class))).thenReturn(mockResponse); when(s3Client.getBucketEncryption(any(GetBucketEncryptionRequest.class))) .thenReturn(buildGetBucketEncryptionResponse("AES256")) .thenReturn(buildGetBucketEncryptionResponse("AES256", "aws:kms")) .thenThrow(S3Exception.builder().message("No Encrypt").build()) .thenReturn(buildGetBucketEncryptionResponse("aws:kms")) .thenReturn(buildGetBucketEncryptionResponse("AES256")); setServiceClient(s3Client); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder() .encryptionAlgorithm("AES256") .minBuckets("10") .build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext( HookContext.builder() .targetName("AWS::S3::Bucket") .targetModel( createHookTargetModel( AwsS3Bucket.builder() .bucketName("toBeDeletedBucket") .build() ) ) .build()) .build(); final ProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); verify(s3Client, times(5)).getBucketEncryption(any(GetBucketEncryptionRequest.class)); verify(handler, never()).getBucketSSEAlgorithm("toBeDeletedBucket"); assertResponse(response, OperationStatus.FAILED, "Failed to meet minimum of [10] encrypted buckets."); } @Test public void handleRequest_awsSqsQueueFailed() { final PreDeleteHookHandler handler = Mockito.spy(new PreDeleteHookHandler()); final List queueUrls = ImmutableList.of( "https://queue1.queue", "https://queue2.queue", "https://toBeDeletedQueue.queue", "https://queue3.queue", "https://queue4.queue", "https://queue5.queue" ); when(sqsClient.getQueueUrl(any(GetQueueUrlRequest.class))) .thenReturn(GetQueueUrlResponse.builder().queueUrl("https://toBeDeletedQueue.queue").build()); when(sqsClient.listQueues(any(ListQueuesRequest.class))) .thenReturn(ListQueuesResponse.builder().queueUrls(queueUrls).build()); when(sqsClient.getQueueAttributes(any(GetQueueAttributesRequest.class))) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(new HashMap<>()).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(new HashMap<>()).build()) .thenReturn(GetQueueAttributesResponse.builder().attributes(ImmutableMap.of(QueueAttributeName.KMS_MASTER_KEY_ID, "kmsKeyId")).build()); setServiceClient(sqsClient); final TypeConfigurationModel typeConfiguration = TypeConfigurationModel.builder() .minQueues("10") .build(); final HookHandlerRequest request = HookHandlerRequest.builder() .hookContext( HookContext.builder() .targetName("AWS::SQS::Queue") .targetModel( createHookTargetModel( ImmutableMap.of("QueueName", "toBeDeletedQueue") ) ) .build()) .build(); final ProgressEvent response = handler.handleRequest(proxy, request, null, logger, typeConfiguration); verify(sqsClient, times(5)).getQueueAttributes(any(GetQueueAttributesRequest.class)); verify(handler, never()).isQueueEncrypted("toBeDeletedQueue"); assertResponse(response, OperationStatus.FAILED, "Failed to meet minimum of [10] encrypted queues."); } private GetBucketEncryptionResponse buildGetBucketEncryptionResponse(final String ...sseAlgorithm) { return buildGetBucketEncryptionResponse( Arrays.stream(sseAlgorithm) .map(a -> ServerSideEncryptionRule.builder().applyServerSideEncryptionByDefault( ServerSideEncryptionByDefault.builder() .sseAlgorithm(a) .build() ).build() ) .collect(Collectors.toList()) ); } private GetBucketEncryptionResponse buildGetBucketEncryptionResponse(final Collection rules) { return GetBucketEncryptionResponse.builder() .serverSideEncryptionConfiguration( ServerSideEncryptionConfiguration.builder().rules( rules ).build() ).build(); } } ``` # 使用 Python 对自定义 CloudFormation 挂钩进行建模 对自定义 CloudFormation Hook 进行建模涉及创建一个用于定义 Hook、其属性和属性的架构。本教程将引导你使用 Python 对自定义挂钩进行建模。 ## 步骤 1：生成 Hook 项目包 生成你的 Hook 项目包。 CloudFormation CLI 创建空的处理程序函数，这些函数对应于 Hook 规范中定义的目标生命周期中的特定 Hook 操作。 ``` cfn generate ``` 该命令将返回以下输出。 ``` Generated files for MyCompany::Testing::MyTestHook ``` **注意** 确保您的 Lambda 运行时 up-to-date避免使用已弃用的版本。有关更多信息，请参阅[更新资源类型的 Lambda 运行时和挂钩](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html)。 ## 第 2 步：添加 Hook 处理程序 将您自己的 Hook 处理程序运行时代码添加到您选择实现的处理程序中。例如，您可以添加以下用于记录的代码。 ``` LOG.setLevel(logging.INFO) LOG.info("Internal testing Hook triggered for target: " + request.hookContext.targetName); ``` C CloudFormation LI 从生成`src/models.py`文件[挂钩配置架构语法参考](hook-configuration-schema.md)。 **Example models.py** ``` import sys from dataclasses import dataclass from inspect import getmembers, isclass from typing import ( AbstractSet, Any, Generic, Mapping, MutableMapping, Optional, Sequence, Type, TypeVar, ) from cloudformation_cli_python_lib.interface import ( BaseModel, BaseHookHandlerRequest, ) from cloudformation_cli_python_lib.recast import recast_object from cloudformation_cli_python_lib.utils import deserialize_list T = TypeVar("T") def set_or_none(value: Optional[Sequence[T]]) -> Optional[AbstractSet[T]]: if value: return set(value) return None @dataclass class HookHandlerRequest(BaseHookHandlerRequest): pass @dataclass class TypeConfigurationModel(BaseModel): limitSize: Optional[str] cidr: Optional[str] encryptionAlgorithm: Optional[str] @classmethod def _deserialize( cls: Type["_TypeConfigurationModel"], json_data: Optional[Mapping[str, Any]], ) -> Optional["_TypeConfigurationModel"]: if not json_data: return None return cls( limitSize=json_data.get("limitSize"), cidr=json_data.get("cidr"), encryptionAlgorithm=json_data.get("encryptionAlgorithm"), ) _TypeConfigurationModel = TypeConfigurationModel ``` ## 第 3 步：实现挂钩处理程序 生成的 Python 数据类后，你可以编写实际实现 Hook 功能的处理程序。在此示例中，您将为处理程序实现`preCreate``preUpdate`、和`preDelete`调用点。 **Topics** + [实现预创建处理程序](#model-hook-project-code-handler-python-precreate) + [实现预更新处理程序](#model-hook-project-code-handler-python-preupdate) + [实现预删除处理程序](#model-hook-project-code-handler-python-predelete) + [实现一个 Hook 处理程序](#model-hook-project-code-handler-python-hook-handler) ### 实现预创建处理程序 `preCreate`处理程序验证`AWS::S3::Bucket `或`AWS::SQS::Queue`资源的服务器端加密设置。 + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过。 + Amazon S3 存储桶加密已设置。 + 已为该存储桶启用了 Amazon S3 存储桶密钥。 + 为 Amazon S3 存储桶设置的加密算法是所需的正确算法。 + 密 AWS Key Management Service 钥 ID 已设置。 + 对于`AWS::SQS::Queue`资源，只有在满足以下条件时，Hook 才会通过。 + 密 AWS Key Management Service 钥 ID 已设置。 ### 实现预更新处理程序 实现一个`preUpdate`处理程序，该处理程序在处理程序中所有指定目标的更新操作之前启动。该`preUpdate`处理程序完成以下任务： + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过： + Amazon S3 存储桶的存储桶加密算法尚未修改。 ### 实现预删除处理程序 实现一个`preDelete`处理程序，该处理程序在处理程序中所有指定目标的删除操作之前启动。该`preDelete`处理程序完成以下任务： + 对于`AWS::S3::Bucket`资源，只有在满足以下条件时，Hook 才会通过： + 验证删除资源后账户中是否存在所需的最低合规资源。 + 所需的最低合规资源量在 Hook 的配置中设置。 ### 实现一个 Hook 处理程序 1. 在 IDE 中，打开位于`src`文件夹中的`handlers.py`文件。 1. 用以下代码替换`handlers.py`文件的全部内容。 **Example handlers.py** ``` import logging from typing import Any, MutableMapping, Optional import botocore from cloudformation_cli_python_lib import ( BaseHookHandlerRequest, HandlerErrorCode, Hook, HookInvocationPoint, OperationStatus, ProgressEvent, SessionProxy, exceptions, ) from .models import HookHandlerRequest, TypeConfigurationModel # Use this logger to forward log messages to CloudWatch Logs. LOG = logging.getLogger(__name__) TYPE_NAME = "MyCompany::Testing::MyTestHook" LOG.setLevel(logging.INFO) hook = Hook(TYPE_NAME, TypeConfigurationModel) test_entrypoint = hook.test_entrypoint def _validate_s3_bucket_encryption( bucket: MutableMapping[str, Any], required_encryption_algorithm: str ) -> ProgressEvent: status = None message = "" error_code = None if bucket: bucket_name = bucket.get("BucketName") bucket_encryption = bucket.get("BucketEncryption") if bucket_encryption: server_side_encryption_rules = bucket_encryption.get( "ServerSideEncryptionConfiguration" ) if server_side_encryption_rules: for rule in server_side_encryption_rules: bucket_key_enabled = rule.get("BucketKeyEnabled") if bucket_key_enabled: server_side_encryption_by_default = rule.get( "ServerSideEncryptionByDefault" ) encryption_algorithm = server_side_encryption_by_default.get( "SSEAlgorithm" ) kms_key_id = server_side_encryption_by_default.get( "KMSMasterKeyID" ) # "KMSMasterKeyID" is name of the property for an AWS::S3::Bucket if encryption_algorithm == required_encryption_algorithm: if encryption_algorithm == "aws:kms" and not kms_key_id: status = OperationStatus.FAILED message = f"KMS Key ID not set for bucket with name: f{bucket_name}" else: status = OperationStatus.SUCCESS message = f"Successfully invoked PreCreateHookHandler for AWS::S3::Bucket with name: {bucket_name}" else: status = OperationStatus.FAILED message = f"SSE Encryption Algorithm is incorrect for bucket with name: {bucket_name}" else: status = OperationStatus.FAILED message = f"Bucket key not enabled for bucket with name: {bucket_name}" if status == OperationStatus.FAILED: break else: status = OperationStatus.FAILED message = f"No SSE Encryption configurations for bucket with name: {bucket_name}" else: status = OperationStatus.FAILED message = ( f"Bucket Encryption not enabled for bucket with name: {bucket_name}" ) else: status = OperationStatus.FAILED message = "Resource properties for S3 Bucket target model are empty" if status == OperationStatus.FAILED: error_code = HandlerErrorCode.NonCompliant return ProgressEvent(status=status, message=message, errorCode=error_code) def _validate_sqs_queue_encryption(queue: MutableMapping[str, Any]) -> ProgressEvent: if not queue: return ProgressEvent( status=OperationStatus.FAILED, message="Resource properties for SQS Queue target model are empty", errorCode=HandlerErrorCode.NonCompliant, ) queue_name = queue.get("QueueName") kms_key_id = queue.get( "KmsMasterKeyId" ) # "KmsMasterKeyId" is name of the property for an AWS::SQS::Queue if not kms_key_id: return ProgressEvent( status=OperationStatus.FAILED, message=f"Server side encryption turned off for queue with name: {queue_name}", errorCode=HandlerErrorCode.NonCompliant, ) return ProgressEvent( status=OperationStatus.SUCCESS, message=f"Successfully invoked PreCreateHookHandler for targetAWS::SQS::Queue with name: {queue_name}", ) @hook.handler(HookInvocationPoint.CREATE_PRE_PROVISION) def pre_create_handler( session: Optional[SessionProxy], request: HookHandlerRequest, callback_context: MutableMapping[str, Any], type_configuration: TypeConfigurationModel, ) -> ProgressEvent: target_name = request.hookContext.targetName if "AWS::S3::Bucket" == target_name: return _validate_s3_bucket_encryption( request.hookContext.targetModel.get("resourceProperties"), type_configuration.encryptionAlgorithm, ) elif "AWS::SQS::Queue" == target_name: return _validate_sqs_queue_encryption( request.hookContext.targetModel.get("resourceProperties") ) else: raise exceptions.InvalidRequest(f"Unknown target type: {target_name}") def _validate_bucket_encryption_rules_not_updated( resource_properties, previous_resource_properties ) -> ProgressEvent: bucket_encryption_configs = resource_properties.get("BucketEncryption", {}).get( "ServerSideEncryptionConfiguration", [] ) previous_bucket_encryption_configs = previous_resource_properties.get( "BucketEncryption", {} ).get("ServerSideEncryptionConfiguration", []) if len(bucket_encryption_configs) != len(previous_bucket_encryption_configs): return ProgressEvent( status=OperationStatus.FAILED, message=f"Current number of bucket encryption configs does not match previous. Current has {str(len(bucket_encryption_configs))} configs while previously there were {str(len(previous_bucket_encryption_configs))} configs", errorCode=HandlerErrorCode.NonCompliant, ) for i in range(len(bucket_encryption_configs)): current_encryption_algorithm = ( bucket_encryption_configs[i] .get("ServerSideEncryptionByDefault", {}) .get("SSEAlgorithm") ) previous_encryption_algorithm = ( previous_bucket_encryption_configs[i] .get("ServerSideEncryptionByDefault", {}) .get("SSEAlgorithm") ) if current_encryption_algorithm != previous_encryption_algorithm: return ProgressEvent( status=OperationStatus.FAILED, message=f"Bucket Encryption algorithm can not be changed once set. The encryption algorithm was changed to {current_encryption_algorithm} from {previous_encryption_algorithm}.", errorCode=HandlerErrorCode.NonCompliant, ) return ProgressEvent( status=OperationStatus.SUCCESS, message="Successfully invoked PreUpdateHookHandler for target: AWS::SQS::Queue", ) def _validate_queue_encryption_not_disabled( resource_properties, previous_resource_properties ) -> ProgressEvent: if previous_resource_properties.get( "KmsMasterKeyId" ) and not resource_properties.get("KmsMasterKeyId"): return ProgressEvent( status=OperationStatus.FAILED, errorCode=HandlerErrorCode.NonCompliant, message="Queue encryption can not be disable", ) else: return ProgressEvent(status=OperationStatus.SUCCESS) @hook.handler(HookInvocationPoint.UPDATE_PRE_PROVISION) def pre_update_handler( session: Optional[SessionProxy], request: BaseHookHandlerRequest, callback_context: MutableMapping[str, Any], type_configuration: MutableMapping[str, Any], ) -> ProgressEvent: target_name = request.hookContext.targetName if "AWS::S3::Bucket" == target_name: resource_properties = request.hookContext.targetModel.get("resourceProperties") previous_resource_properties = request.hookContext.targetModel.get( "previousResourceProperties" ) return _validate_bucket_encryption_rules_not_updated( resource_properties, previous_resource_properties ) elif "AWS::SQS::Queue" == target_name: resource_properties = request.hookContext.targetModel.get("resourceProperties") previous_resource_properties = request.hookContext.targetModel.get( "previousResourceProperties" ) return _validate_queue_encryption_not_disabled( resource_properties, previous_resource_properties ) else: raise exceptions.InvalidRequest(f"Unknown target type: {target_name}") ``` 继续进入下一个主题 [向注册自定义 Hook CloudFormation](registering-hooks.md)。 # 向注册自定义 Hook CloudFormation 创建自定义 Hook 后，需要向其注册 CloudFormation 才能使用它。在本节中，你将学习如何打包和注册你的Hook，以便在你的 AWS 账户。 ## Package a Hook (Java) 如果你是用 Java 开发的 Hook，请使用 Maven 对其进行打包。 在 Hook 项目的目录中，运行以下命令来构建 Hook，运行单元测试，并将项目打包为可用于将 Hook 提交到 CloudFormation 注册表`JAR`的文件中。 ``` mvn clean package ``` ## 注册一个自定义 Hook **注册挂钩** 1. （可选）通过提交[https://docs.aws.amazon.com/cli/latest/reference/configure/](https://docs.aws.amazon.com/cli/latest/reference/configure/)操作`us-west-2`，将您的默认 AWS 区域 名称配置为。 ``` $ aws configure AWS Access Key ID [None]: AWS Secret Access Key [None]: Default region name [None]: us-west-2 Default output format [None]: json ``` 1. （可选）以下命令无需注册即可构建和打包您的 Hook 项目。 ``` $ cfn submit --dry-run ``` 1. 使用 CloudFormation CLI [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)操作注册您的挂钩。 ``` $ cfn submit --set-default ``` 该命令将返回以下命令。 ``` {‘ProgressStatus’: ‘COMPLETE’} ``` *结果*：您已成功注册您的 Hook。 ## 验证您的账户中是否可以访问 Hook 确认您的 Hook 在您 AWS 账户 和您提交该挂钩的区域中可用。 1. 要验证您的 Hook，请使用[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)命令列出您新注册的 Hook 并返回其摘要描述。 ``` $ aws cloudformation list-types ``` 该命令返回以下输出，还将向您显示可在 AWS 账户 和区域中激活的公开可用的 Hook。 ``` { "TypeSummaries": [ { "Type": "HOOK", "TypeName": "MyCompany::Testing::MyTestHook", "DefaultVersionId": "00000001", "TypeArn": "arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook", "LastUpdated": "2021-08-04T23:00:03.058000+00:00", "Description": "Verifies S3 bucket and SQS queues properties before creating or updating" } ] } ``` 1. `TypeArn`从 Hook 的`list-type`输出中检索并保存。 ``` export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook ``` 要了解如何发布 Hook 供公众使用，请参阅[发布 Hook 供公众使用](hooks-publishing.md)。 ### 配置挂钩 开发并注册了 Hook 后，您可以 AWS 账户 通过将其发布到注册表来配置您的 Hook。 + 要在您的账户中配置 Hook，请使用[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html)操作。此操作启用挂钩架构 `properties` 部分中定义的挂钩属性。在以下示例中，该`minBuckets`属性在配置`1`中设置为。 **注意** 通过在您的账户中启用 Hook，即授权 Hook 使用您的 AWS 账户已定义权限。 CloudFormation 在将您的权限传递给 Hook 之前，会移除不需要的权限。 CloudFormation 建议客户或 Hook 用户在账户中启用 Hook 之前，先查看 Hook 权限并了解允许 Hook 拥有哪些权限。 在同一个账户中为你注册的 Hook 扩展指定配置数据，然后 AWS 区域。 ``` $ aws cloudformation set-type-configuration --region us-west-2 --configuration '{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus":"ENABLED","FailureMode":"FAIL","Properties":{"minBuckets": "1","minQueues": "1", "encryptionAlgorithm": "aws:kms"}}}}' --type-arn $HOOK_TYPE_ARN ``` **重要** 要使您的 Hook 能够主动检查堆栈的配置，您必须在账户`ENABLED`中注册并激活 Hook 之后，在该`HookConfiguration`部分中将设置为。`HookInvocationStatus` ## AWS APIs 在处理程序中访问 如果您的 Hook 在其任何处理程序中使用 AWS API，则 CFN-CLI 会自动创建 IAM 执行角色模板。`hook-role.yaml`该`hook-role.yaml`模板基于在 Hook 架构的处理程序部分中为每个处理程序指定的权限。如果在[https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-generate.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-generate.html)操作期间未使用该`--role-arn`标志，则将配置此堆栈中的角色并将其用作 Hook 的执行角色。 有关更多信息，请参阅[AWS APIs 从资源类型访问。](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole) ### hook-role.yaml 模板 **注意** 如果您选择创建自己的执行角色，我们强烈建议您遵循最低权限原则，即仅允许上架`hooks.cloudformation.amazonaws.com`和`resources.cloudformation.amazonaws.com`。 以下模板使用 IAM、Amazon S3 和亚马逊 SQS 权限。 ``` AWSTemplateFormatVersion: 2010-09-09 Description: > This CloudFormation template creates a role assumed by CloudFormation during Hook operations on behalf of the customer. Resources: ExecutionRole: Type: 'AWS::IAM::Role' Properties: MaxSessionDuration: 8400 AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Principal: Service: - resources.cloudformation.amazonaws.com - hooks.cloudformation.amazonaws.com Action: 'sts:AssumeRole' Condition: StringEquals: aws:SourceAccount: !Ref AWS::AccountId StringLike: aws:SourceArn: !Sub arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:type/hook/MyCompany-Testing-MyTestHook/* Path: / Policies: - PolicyName: HookTypePolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 's3:GetEncryptionConfiguration' - 's3:ListBucket' - 's3:ListAllMyBuckets' - 'sqs:GetQueueAttributes' - 'sqs:GetQueueUrl' - 'sqs:ListQueues' Resource: '*' Outputs: ExecutionRoleArn: Value: !GetAtt - ExecutionRole - Arn ``` # 在你的 Hook 中测试自定义 Hook AWS 账户 既然你已经编码了与调用点对应的处理函数，那么是时候在 CloudFormation 堆栈上测试你的自定义 Hook 了。 `FAIL`如果 CloudFormation 模板未使用以下内容配置 S3 存储桶，则挂钩失败模式将设置为： + Amazon S3 存储桶加密已设置。 + 已为该存储桶启用了 Amazon S3 存储桶密钥。 + 为 Amazon S3 存储桶设置的加密算法是所需的正确算法。 + 密 AWS Key Management Service 钥 ID 已设置。 在以下示例中，创建一个名为的模板，其堆栈`my-failed-bucket-stack.yml`名称为`my-hook-stack`，该模板无法配置堆栈并在资源配置之前停止。 ## 通过配置堆栈来测试 Hook ### 示例 1：配置堆栈 **配置不合规的堆栈** 1. 创作一个指定 S3 存储桶的模板。例如 `my-failed-bucket-stack.yml`。 ``` AWSTemplateFormatVersion: 2010-09-09 Resources: S3Bucket: Type: AWS::S3::Bucket Properties: {} ``` 1. 创建堆栈，然后在 AWS Command Line Interface (AWS CLI) 中指定您的模板。在以下示例中，将堆栈名称指定为`my-hook-stack`，将模板名称指定为`my-failed-bucket-stack.yml`。 ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://my-failed-bucket-stack.yml ``` 1. （可选）通过指定堆栈名称来查看堆栈进度。在以下示例中，指定堆栈名称`my-hook-stack`。 ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` 创建存储桶时，使用`describe-stack-events`操作查看挂钩失败。以下是 命令的示例输出。 ``` { "StackEvents": [ ... { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-hook-stack/2c693970-f57e-11eb-a0fb-061a2a83f0b9", "EventId": "S3Bucket-CREATE_FAILED-2021-08-04T23:47:03.305Z", "StackName": "my-hook-stack", "LogicalResourceId": "S3Bucket", "PhysicalResourceId": "", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:47:03.305000+00:00", "ResourceStatus": "CREATE_FAILED", "ResourceStatusReason": "The following hook(s) failed: [MyCompany::Testing::MyTestHook]", "ResourceProperties": "{}", "ClientRequestToken": "Console-CreateStack-abe71ac2-ade4-a762-0499-8d34d91d6a92" }, ... ] } ``` *结果*：Hook 调用使堆栈配置失败，并停止了资源置备。 **使用 CloudFormation 模板通过 Hook 验证** 1. 要创建堆栈并通过 Hook 验证，请更新模板，使您的资源使用加密的 S3 存储桶。此示例使用 `my-encrypted-bucket-stack.yml` 模板。 ``` AWSTemplateFormatVersion: 2010-09-09 Description: | This CloudFormation template provisions an encrypted S3 Bucket Resources: EncryptedS3Bucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub encryptedbucket-${AWS::Region}-${AWS::AccountId} BucketEncryption: ServerSideEncryptionConfiguration: - ServerSideEncryptionByDefault: SSEAlgorithm: 'aws:kms' KMSMasterKeyID: !Ref EncryptionKey BucketKeyEnabled: true EncryptionKey: Type: AWS::KMS::Key DeletionPolicy: Retain Properties: Description: KMS key used to encrypt the resource type artifacts EnableKeyRotation: true KeyPolicy: Version: 2012-10-17 Statement: - Sid: Enable full access for owning account Effect: Allow Principal: AWS: !Ref AWS::AccountId Action: 'kms:*' Resource: '*' Outputs: EncryptedBucketName: Value: !Ref EncryptedS3Bucket ``` **注意** 不会为跳过的资源调用 Hook。 1. 创建堆栈并指定您的模板。在此示例中，堆栈名称为`my-encrypted-bucket-stack`。 ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://my-encrypted-bucket-stack.yml \ ``` 1. （可选）通过指定堆栈名称来查看堆栈进度。 ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` 使用`describe-stack-events`命令查看响应。以下是 `describe-stack-events` 命令的示例。 ``` { "StackEvents": [ ... { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-CREATE_COMPLETE-2021-08-04T23:23:20.973Z", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "encryptedbucket-us-west-2-123456789012", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:23:20.973000+00:00", "ResourceStatus": "CREATE_COMPLETE", "ResourceProperties": "{\"BucketName\":\"encryptedbucket-us-west-2-123456789012\",\"BucketEncryption\":{\"ServerSideEncryptionConfiguration\":[{\"BucketKeyEnabled\":\"true\",\"ServerSideEncryptionByDefault\":{\"SSEAlgorithm\":\"aws:kms\",\"KMSMasterKeyID\":\"ENCRYPTION_KEY_ARN\"}}]}}", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-CREATE_IN_PROGRESS-2021-08-04T23:22:59.410Z", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "encryptedbucket-us-west-2-123456789012", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:22:59.410000+00:00", "ResourceStatus": "CREATE_IN_PROGRESS", "ResourceStatusReason": "Resource creation Initiated", "ResourceProperties": "{\"BucketName\":\"encryptedbucket-us-west-2-123456789012\",\"BucketEncryption\":{\"ServerSideEncryptionConfiguration\":[{\"BucketKeyEnabled\":\"true\",\"ServerSideEncryptionByDefault\":{\"SSEAlgorithm\":\"aws:kms\",\"KMSMasterKeyID\":\"ENCRYPTION_KEY_ARN\"}}]}}", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-6516081f-c1f2-4bfe-a0f0-cefa28679994", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:22:58.349000+00:00", "ResourceStatus": "CREATE_IN_PROGRESS", "ResourceStatusReason": "Hook invocations complete. Resource creation initiated", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, ... ] } ``` *结果*： CloudFormation 成功创建堆栈。在配置资源之前，Hook 的逻辑验证了`AWS::S3::Bucket`资源是否包含服务器端加密。 ### 示例 2：配置堆栈 **配置不合规的堆栈** 1. 创作一个指定 S3 存储桶的模板。例如 `aes256-bucket.yml`。 ``` AWSTemplateFormatVersion: 2010-09-09 Description: | This CloudFormation template provisions an encrypted S3 Bucket Resources: EncryptedS3Bucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub encryptedbucket-${AWS::Region}-${AWS::AccountId} BucketEncryption: ServerSideEncryptionConfiguration: - ServerSideEncryptionByDefault: SSEAlgorithm: AES256 BucketKeyEnabled: true Outputs: EncryptedBucketName: Value: !Ref EncryptedS3Bucket ``` 1. 创建堆栈，并在中指定您的模板 AWS CLI。在以下示例中，将堆栈名称指定为`my-hook-stack`，将模板名称指定为`aes256-bucket.yml`。 ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://aes256-bucket.yml ``` 1. （可选）通过指定堆栈名称来查看堆栈进度。在以下示例中，指定堆栈名称`my-hook-stack`。 ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` 创建存储桶时，使用`describe-stack-events`操作查看挂钩失败。以下是 命令的示例输出。 ``` { "StackEvents": [ ... { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-hook-stack/2c693970-f57e-11eb-a0fb-061a2a83f0b9", "EventId": "S3Bucket-CREATE_FAILED-2021-08-04T23:47:03.305Z", "StackName": "my-hook-stack", "LogicalResourceId": "S3Bucket", "PhysicalResourceId": "", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:47:03.305000+00:00", "ResourceStatus": "CREATE_FAILED", "ResourceStatusReason": "The following hook(s) failed: [MyCompany::Testing::MyTestHook]", "ResourceProperties": "{}", "ClientRequestToken": "Console-CreateStack-abe71ac2-ade4-a762-0499-8d34d91d6a92" }, ... ] } ``` *结果*：Hook 调用使堆栈配置失败，并停止了资源置备。由于 S3 存储桶加密配置不正确，堆栈失败。挂钩类型配置需要在此存储桶使用`aws:kms`时使用`AES256`。 **使用 CloudFormation 模板通过 Hook 验证** 1. 要创建堆栈并通过 Hook 验证，请更新模板，使您的资源使用加密的 S3 存储桶。此示例使用 `kms-bucket-and-queue.yml` 模板。 ``` AWSTemplateFormatVersion: 2010-09-09 Description: | This CloudFormation template provisions an encrypted S3 Bucket Resources: EncryptedS3Bucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub encryptedbucket-${AWS::Region}-${AWS::AccountId} BucketEncryption: ServerSideEncryptionConfiguration: - ServerSideEncryptionByDefault: SSEAlgorithm: 'aws:kms' KMSMasterKeyID: !Ref EncryptionKey BucketKeyEnabled: true EncryptedQueue: Type: AWS::SQS::Queue Properties: QueueName: !Sub encryptedqueue-${AWS::Region}-${AWS::AccountId} KmsMasterKeyId: !Ref EncryptionKey EncryptionKey: Type: AWS::KMS::Key DeletionPolicy: Retain Properties: Description: KMS key used to encrypt the resource type artifacts EnableKeyRotation: true KeyPolicy: Version: 2012-10-17 Statement: - Sid: Enable full access for owning account Effect: Allow Principal: AWS: !Ref AWS::AccountId Action: 'kms:*' Resource: '*' Outputs: EncryptedBucketName: Value: !Ref EncryptedS3Bucket EncryptedQueueName: Value: !Ref EncryptedQueue ``` **注意** 不会为跳过的资源调用 Hook。 1. 创建堆栈并指定您的模板。在此示例中，堆栈名称为`my-encrypted-bucket-stack`。 ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://kms-bucket-and-queue.yml ``` 1. （可选）通过指定堆栈名称来查看堆栈进度。 ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` 使用`describe-stack-events`命令查看响应。以下是 `describe-stack-events` 命令的示例。 ``` { "StackEvents": [ ... { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-CREATE_COMPLETE-2021-08-04T23:23:20.973Z", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "encryptedbucket-us-west-2-123456789012", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:23:20.973000+00:00", "ResourceStatus": "CREATE_COMPLETE", "ResourceProperties": "{\"BucketName\":\"encryptedbucket-us-west-2-123456789012\",\"BucketEncryption\":{\"ServerSideEncryptionConfiguration\":[{\"BucketKeyEnabled\":\"true\",\"ServerSideEncryptionByDefault\":{\"SSEAlgorithm\":\"aws:kms\",\"KMSMasterKeyID\":\"ENCRYPTION_KEY_ARN\"}}]}}", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-CREATE_IN_PROGRESS-2021-08-04T23:22:59.410Z", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "encryptedbucket-us-west-2-123456789012", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:22:59.410000+00:00", "ResourceStatus": "CREATE_IN_PROGRESS", "ResourceStatusReason": "Resource creation Initiated", "ResourceProperties": "{\"BucketName\":\"encryptedbucket-us-west-2-123456789012\",\"BucketEncryption\":{\"ServerSideEncryptionConfiguration\":[{\"BucketKeyEnabled\":\"true\",\"ServerSideEncryptionByDefault\":{\"SSEAlgorithm\":\"aws:kms\",\"KMSMasterKeyID\":\"ENCRYPTION_KEY_ARN\"}}]}}", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, { "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-encrypted-bucket-stack/82a97150-f57a-11eb-8eb2-06a6bdcc7779", "EventId": "EncryptedS3Bucket-6516081f-c1f2-4bfe-a0f0-cefa28679994", "StackName": "my-encrypted-bucket-stack", "LogicalResourceId": "EncryptedS3Bucket", "PhysicalResourceId": "", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2021-08-04T23:22:58.349000+00:00", "ResourceStatus": "CREATE_IN_PROGRESS", "ResourceStatusReason": "Hook invocations complete. Resource creation initiated", "ClientRequestToken": "Console-CreateStack-39df35ac-ca00-b7f6-5661-4e917478d075" }, ... ] } ``` *结果*： CloudFormation 成功创建堆栈。在配置资源之前，Hook 的逻辑验证了`AWS::S3::Bucket`资源是否包含服务器端加密。 # 更新自定义 Hook 更新自定义 Hook 允许在 CloudFormation注册表中提供 Hook 中的修订版本。 要更新自定义 Hook，请通过 CloudFormation CLI [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)操作将您的修订提交到 CloudFormation 注册表。 ``` $ cfn submit ``` 要在您的账户中指定挂钩的默认版本，请使用[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)命令并指定类型、类型名称和版本 ID。 ``` $ aws cloudformation set-type-default-version \ --type HOOK \ --type-name MyCompany::Testing::MyTestHook \ --version-id 00000003 ``` 要检索有关 Hook 版本的信息，请使用[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-type-versions.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-type-versions.html)。 ``` $ aws cloudformation list-type-versions \ --type HOOK \ --type-name "MyCompany::Testing::MyTestHook" ``` # 从注册表中取消注册自定义 Hook CloudFormation 取消注册自定义 Hook 会将扩展或扩展版本标记为 CloudFormation 注册表`DEPRECATED`中的版本，这会将其从活动使用中删除。自定义 Hook 一旦被弃用，就无法在 CloudFormation 操作中使用。 **注意** 在取消注册 Hook 之前，必须单独取消注册该扩展的所有先前活动版本。有关更多信息，请参阅 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html)。 要取消注册挂钩，请使用[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html)操作并指定您的挂钩 ARN。 ``` $ aws cloudformation deregister-type \ --arn HOOK_TYPE_ARN ``` 此命令不产生输出。 # 发布 Hook 供公众使用 要开发公共的第三方 Hook，请将您的 Hook 开发为私有扩展。然后， AWS 区域 在每个你想公开扩展程序的内容中： 1. 在注册表中将您的 Hook CloudFormation 注册为私有扩展。 1. 测试您的 Hook，确保它满足在 CloudFormation 注册表中发布的所有必要要求。 1. 将您的 Hook 发布到 CloudFormation 注册表。 **注意** 在给定区域发布任何扩展之前，必须先在该地区注册为扩展发布者。要同时在多个区域执行此操作，请参阅 * CloudFormation CLI 用户指南 StackSets*中的[使用在多个区域发布扩展程序](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension-stacksets.html)。 开发并注册了 Hook 后，您可以将其作为第三方公共扩展*发布*到 CloudFormation 注册表，使其向普通 CloudFormation 用户公开。 公共第三方 Hook 使您能够让 CloudFormation 用户在配置之前主动检查 AWS 资源配置。与私有 Hook 一样，公共 Hook 的处理方式与 within 发布的 AWS 任何 Hook 相同 CloudFormation。 发布到注册表的挂钩对发布到注册表 AWS 区域 的所有 CloudFormation 用户都可见。然后，用户可以在其帐户中*激活*您的扩展程序，从而使其可在模板中使用。有关更多信息，请参阅《*CloudFormation 用户指南》*[中的使用 CloudFormation 注册表中的第三方公共扩展](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html)。 # 测试供公众使用的自定义 Hook 要发布您注册的自定义 Hook，它必须通过为其定义的所有测试要求。以下是将您的自定义 Hook 发布为第三方扩展之前所需的要求列表。 每个处理程序和目标都要经过两次测试。一次为`SUCCESS`，一次为`FAILED`。 + 对于`SUCCESS`响应案例： + 状态必须是`SUCCESS`。 + 不得返回错误代码。 + 如果已指定，则应将回调延迟设置为`0`秒。 + 对于`FAILED`响应案例： + 状态必须是`FAILED`。 + 必须返回错误代码。 + 必须有消息作为回应。 + 如果已指定，则应将回调延迟设置为`0`秒。 + 对于`IN_PROGRESS`响应案例： + 不得返回错误代码。 + `Result`不得在响应时设置字段。 # 指定用于合约测试的输入数据 默认情况下，使用根据您在 Hook 架构中定义的模式生成的输入属性来 CloudFormation 执行合约测试。但是，大多数 Hook 都非常复杂，以至于用于预创建或预更新配置堆栈的输入属性需要了解所配置的资源。为了解决这个问题，你可以指定在执行合约测试时 CloudFormation 使用的输入。 CloudFormation 提供了两种方法供您指定在执行合约测试时使用的输入数据： + 覆盖文件 使用`overrides`文件提供了一种轻量级的方法来指定某些特定属性的输入数据`preCreate`， CloudFormation 以便在操作测试`preUpdate`和`preDelete`操作测试期间使用。 + 输入文件 在以下情况下，您也可以使用多个`input`文件来指定合约测试输入数据： + 您想要或需要为创建、更新和删除操作指定不同的输入数据，或者为测试指定无效数据。 + 您想要指定多个不同的输入数据集。 ## 使用替代文件指定输入数据 以下是 Amazon S3 Hook 使用该`overrides`文件输入数据的示例。 ``` { "CREATE_PRE_PROVISION": { "AWS::S3::Bucket": { "resourceProperties": { "/BucketName": "encryptedbucket-us-west-2-contractor", "/BucketEncryption/ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] } }, "AWS::SQS::Queue": { "resourceProperties": { "/QueueName": "MyQueueContract", "/KmsMasterKeyId": "hellocontract" } } }, "UPDATE_PRE_PROVISION": { "AWS::S3::Bucket": { "resourceProperties": { "/BucketName": "encryptedbucket-us-west-2-contractor", "/BucketEncryption/ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] }, "previousResourceProperties": { "/BucketName": "encryptedbucket-us-west-2-contractor", "/BucketEncryption/ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] } } }, "INVALID_UPDATE_PRE_PROVISION": { "AWS::S3::Bucket": { "resourceProperties": { "/BucketName": "encryptedbucket-us-west-2-contractor", "/BucketEncryption/ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "AES256" } } ] }, "previousResourceProperties": { "/BucketName": "encryptedbucket-us-west-2-contractor", "/BucketEncryption/ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] } } }, "INVALID": { "AWS::SQS::Queue": { "resourceProperties": { "/QueueName": "MyQueueContract", "/KmsMasterKeyId": "KMS-KEY-ARN" } } } } ``` ## 使用输入文件指定输入数据 使用`input`文件来指定要使用的不同类型的输入数据：`preCreate`输入、`preUpdate`输入和无效输入。 CloudFormation 每种数据都在单独的文件中指定。您还可以为合约测试指定多组输入数据。 要指定要在合约测试中使用的`input`文件，请在 Hooks 项目的根目录中添加一个`inputs`文件夹。 CloudFormation 然后添加您的输入文件。 使用以下命名约定指定文件包含哪种输入数据，其中**n**为整数： + `inputs_n_pre_create.json`：使用带有`preCreate`处理程序的文件来指定用于创建资源的输入。 + `inputs_n_pre_update.json`：使用带有`preUpdate`处理程序的文件来指定用于更新资源的输入。 + `inputs_n_pre_delete.json`：使用带有`preDelete`处理程序的文件来指定删除资源的输入。 + `inputs_n_invalid.json`: 用于指定要测试的无效输入。 要为合约测试指定多组输入数据，请增加文件名中的整数以对输入数据集进行排序。例如，您的第一组输入文件应命名为`inputs_1_pre_create.json``inputs_1_pre_update.json`、和`inputs_1_pre_invalid.json`。您的下一组将命名为`inputs_2_pre_create.json`、`inputs_2_pre_update.json``inputs_2_pre_invalid.json`、和，依此类推。 每个输入文件都是一个 JSON 文件，仅包含用于测试的资源属性。 以下是使用输入文件`inputs` Amazon S3 指定输入数据的示例目录。 `inputs_1_pre_create.json` 以下是`inputs_1_pre_create.json`合同测试的示例。 ``` { "AWS::S3::Bucket": { "resourceProperties": { "AccessControl": "BucketOwnerFullControl", "AnalyticsConfigurations": [], "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] }, "BucketName": "encryptedbucket-us-west-2" } }, "AWS::SQS::Queue": { "resourceProperties": { "QueueName": "MyQueue", "KmsMasterKeyId": "KMS-KEY-ARN" } } } ``` `inputs_1_pre_update.json` 以下是`inputs_1_pre_update.json`合同测试的示例。 ``` { "AWS::S3::Bucket": { "resourceProperties": { "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] }, "BucketName": "encryptedbucket-us-west-2" }, "previousResourceProperties": { "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] }, "BucketName": "encryptedbucket-us-west-2" } } } ``` `inputs_1_invalid.json` 以下是`inputs_1_invalid.json`合同测试的示例。 ``` { "AWS::S3::Bucket": { "resourceProperties": { "AccessControl": "BucketOwnerFullControl", "AnalyticsConfigurations": [], "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "ServerSideEncryptionByDefault": { "SSEAlgorithm": "AES256" } } ] }, "BucketName": "encryptedbucket-us-west-2" } }, "AWS::SQS::Queue": { "resourceProperties": { "NotValid": "The property of this resource is not valid." } } } ``` `inputs_1_invalid_pre_update.json` 以下是`inputs_1_invalid_pre_update.json`合同测试的示例。 ``` { "AWS::S3::Bucket": { "resourceProperties": { "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "AES256" } } ] }, "BucketName": "encryptedbucket-us-west-2" }, "previousResourceProperties": { "BucketEncryption": { "ServerSideEncryptionConfiguration": [ { "BucketKeyEnabled": true, "ServerSideEncryptionByDefault": { "KMSMasterKeyID": "KMS-KEY-ARN", "SSEAlgorithm": "aws:kms" } } ] }, "BucketName": "encryptedbucket-us-west-2" } } } ``` 有关更多信息，请参阅《 CloudFormation CLI 用户指南》中的[发布扩展以使其可供公共使用](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension.html)。 # H CloudFormation ooks 的架构语法参考 本节介绍用于开发 CloudFormation Hook 的架构的语法。 Hook 包括由 JSON 架构和 Hook 处理程序表示的 Hook 规范。创建自定义 Hook 的第一步是对定义挂钩及其属性的架构进行建模。使用 CloudFormation CLI [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html)命令初始化自定义 Hook 项目时，将为您创建一个 Hook 架构文件。使用此架构文件作为定义自定义 Hook 的形状和语义的起点。 ## 架构语法 以下架构是 Hook 的结构。 ``` { "typeName": "string", "description": "string", "sourceUrl": "string", "documentationUrl": "string", "definitions": { "definitionName": { . . . } }, "typeConfiguration": { "properties": { "propertyName": { "description": "string", "type": "string", . . . }, }, "required": [ "propertyName" . . . ], "additionalProperties": false }, "handlers": { "preCreate": { "targetNames": [ ], "permissions": [ ] }, "preUpdate": { "targetNames": [ ], "permissions": [ ] }, "preDelete": { "targetNames": [ ], "permissions": [ ] } }, "additionalProperties": false } ``` `typeName` 您的 Hook 的唯一名称。为 Hook 指定由三部分组成的命名空间，推荐的`Organization::Service::Hook`模式为。 以下组织命名空间已预留，不能用于您的 Hook 类型名称： + `Alexa` + `AMZN` + `Amazon` + `ASK` + `AWS` + `Custom` + `Dev` *是否必需*：是 *图案*：`^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *最小值*：`10` *最大值*：`196` `description` CloudFormation 控制台中显示的 Hook 的简短描述。 *是否必需*：是 `sourceUrl` Hook 源代码的网址（如果是公开的）。 *必需*：否 *最大值*：`4096` `documentationUrl` 提供 Hook 详细文档的页面的 URL。 *是否必需*：是 *图案*：`^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$` *最大值*：`4096` 尽管 Hook 架构应包含完整而准确的属性描述，但您可以使用该`documentationURL`属性为用户提供更多详细信息，包括示例、用例和其他详细信息。 `definitions` 使用该`definitions`块提供共享的 Hook 属性架构。 使用该`definitions`部分来定义可在您的 Hook 类型架构中的多个位置使用的架构元素被认为是一种最佳实践。然后，您可以使用 JSON 指针在 Hook 类型架构中的相应位置引用该元素。 *必需*：否 `typeConfiguration` Hook 配置数据的定义。 *是否必需*：是 `properties` 挂钩的属性。Hook 的所有属性都必须在架构中表达。将 Hook 架构属性与挂钩类型配置属性对齐。 不允许使用嵌套属性。相反，在`definitions`元素中定义任何嵌套属性，然后使用`$ref`指针在所需的属性中引用它们。 目前支持以下属性： + `default`-属性的默认值。 + `description`-对属性的描述。 + `pattern`— 用于验证输入的正则表达式模式。 + `type`— 可接受的属性类型。 `additionalProperties` `additionalProperties` 必须设置为 `false`。Hook 的所有属性都必须在架构中表达：不允许任意输入。 *是否必需*：是 *有效值*：`false` `handlers` 处理程序指定可以启动架构中定义的 Hook 的操作，例如 Hook 调用点。例如，`preUpdate`处理程序是在处理程序中所有指定目标的更新操作之前调用的。 *有效值*：`preCreate` \$1 `preUpdate` \$1 `preDelete` 必须为处理程序指定至少一个值。 导致状态为的堆栈操作`UpdateCleanup`不会调用 Hook。例如，在以下两个场景中，不会调用 Hook 的`preDelete`处理程序： + 从模板中移除一个资源后，堆栈即会更新。 + 更新类型为[替换](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)的资源被删除。 `targetNames` Hook 瞄准的类型名称的字符串数组。例如，如果`preCreate`处理程序有`AWS::S3::Bucket`目标，则挂钩将在预配置阶段为 Amazon S3 存储桶运行。 + `TargetName` 为每个已实现的处理程序指定至少一个目标名称。 *图案*：`^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *最小值*：`1` *是否必需*：是 **警告** SSM SecureString 和 Secrets Manager 动态引用在传递给 Hooks 之前无法解析。 `permissions` 一个字符串数组，它指定调用处理程序所需的 AWS 权限。 *是否必需*：是 `additionalProperties` `additionalProperties` 必须设置为 `false`。Hook 的所有属性都必须在架构中表达：不允许任意输入。 *是否必需*：是 *有效值*：`false` ## Hooks 架构示例 **示例 1** Java 和 Python 演练使用以下代码示例。以下是名为的 Hook 的示例结构`mycompany-testing-mytesthook.json`。 ``` { "typeName":"MyCompany::Testing::MyTestHook", "description":"Verifies S3 bucket and SQS queues properties before create and update", "sourceUrl":"https://mycorp.com/my-repo.git", "documentationUrl":"https://mycorp.com/documentation", "typeConfiguration":{ "properties":{ "minBuckets":{ "description":"Minimum number of compliant buckets", "type":"string" }, "minQueues":{ "description":"Minimum number of compliant queues", "type":"string" }, "encryptionAlgorithm":{ "description":"Encryption algorithm for SSE", "default":"AES256", "type":"string", "pattern": "[a-zA-Z]*[1-9]" } }, "required":[ ], "additionalProperties":false }, "handlers":{ "preCreate":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ ] }, "preUpdate":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ ] }, "preDelete":{ "targetNames":[ "AWS::S3::Bucket", "AWS::SQS::Queue" ], "permissions":[ "s3:ListBucket", "s3:ListAllMyBuckets", "s3:GetEncryptionConfiguration", "sqs:ListQueues", "sqs:GetQueueAttributes", "sqs:GetQueueUrl" ] } }, "additionalProperties":false } ``` **示例 2** 以下示例是一个使用`STACK`和 `CHANGE_SET` for `targetNames` 来定位堆栈模板和更改集操作的架构。 ``` { "typeName":"MyCompany::Testing::MyTestHook", "description":"Verifies Stack and Change Set properties before create and update", "sourceUrl":"https://mycorp.com/my-repo.git", "documentationUrl":"https://mycorp.com/documentation", "typeConfiguration":{ "properties":{ "minBuckets":{ "description":"Minimum number of compliant buckets", "type":"string" }, "minQueues":{ "description":"Minimum number of compliant queues", "type":"string" }, "encryptionAlgorithm":{ "description":"Encryption algorithm for SSE", "default":"AES256", "type":"string", "pattern": "[a-zA-Z]*[1-9]" } }, "required":[ ], "additionalProperties":false }, "handlers":{ "preCreate":{ "targetNames":[ "STACK", "CHANGE_SET" ], "permissions":[ ] }, "preUpdate":{ "targetNames":[ "STACK" ], "permissions":[ ] }, "preDelete":{ "targetNames":[ "STACK" ], "permissions":[ ] } }, "additionalProperties":false } ```