本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 CloudFormation CLI 開發自訂勾點 本節適用於想要開發自訂勾點並在 CloudFormation 登錄檔中註冊的客戶。它提供 CloudFormation 勾點結構的概觀，以及使用 Python 或 Java 開發、註冊、測試、管理和發佈您自己的勾點的指南。 開發自訂勾點有三個主要步驟： 1. **啟動** 若要開發自訂勾點，您必須設定和使用 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)命令並指定您要建立 Hook。如需詳細資訊，請參閱[啟動自訂 CloudFormation 勾點專案](hooks-init.md)。 1. **模型** 若要建立、撰寫和驗證您的勾點結構描述，請定義勾點、其屬性及其屬性。 CloudFormation CLI 會建立對應至特定勾點的空處理常式函數。將您自己的邏輯新增至這些處理常式，以控制 Hook 調用期間在其目標生命週期的每個階段發生的情況。如需詳細資訊，請參閱[建立自訂 CloudFormation 勾點的模型](hooks-model.md)。 1. **註冊** 若要註冊勾點，請提交您的勾點以註冊為私有或公有第三方延伸模組。向 `[submit](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html)`操作註冊您的勾點。如需詳細資訊，請參閱[向 註冊自訂勾點 CloudFormation](registering-hooks.md)。 下列任務與註冊您的勾點相關聯： 1. *發佈* – 勾點會發佈至登錄檔。 1. *設定* – 當類型組態調用堆疊時，會設定勾點。 **注意** 勾點會在 30 秒後逾時，並重試最多 3 次。如需詳細資訊，請參閱[逾時和重試限制](hooks-concepts.md#hook-timeout-and-retry-limits)。 **Topics** + [先決條件](hooks-prerequisites.md) + [啟動勾點專案](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 勾點的先決條件 您可以使用 Java 或 Python 開發自訂勾點。以下是開發自訂勾點的先決條件： **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 專案實作 Hook 處理常式，您可以下載 [Python Hook 處理常式範例檔案](samples/python-handlers.zip)。 ## 開發勾點的許可 除了 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 Hooks 的 IAM 許可](grant-iam-permissions-for-hooks.md)。 ## 設定 Hooks 的開發環境 若要開發勾點，您應該熟悉 [CloudFormation 範本](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)，以及 Python 或 Java。 **若要安裝 CloudFormation CLI 和相關聯的外掛程式：** 1. 使用 Python 套件管理員 `pip`，安裝 CloudFormation CLI。 ``` 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 專案的第一步是啟動專案。您可以使用 CloudFormation CLI `init`命令來啟動自訂 Hooks 專案。 `init` 命令會啟動精靈，引導您設定專案，包括 Hooks 結構描述檔案。使用此結構描述檔案作為定義勾點形狀和語意的起點。如需詳細資訊，請參閱[結構描述語法](hooks-schema.md)。 **若要初始化 Hook 專案：** 1. 建立專案的目錄。 ``` mkdir ~/mycompany-testing-mytesthook ``` 1. 導覽至新目錄。 ``` cd ~/mycompany-testing-mytesthook ``` 1. 使用 CloudFormation CLI `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 套件名稱，然後選擇 codegen 模型。您可以使用預設套件名稱，或建立新的套件名稱。 ``` Enter a package name (empty for default 'com.mycompany.testing.mytesthook'): ``` ``` Choose codegen model - 1 (default) or 2 (guided-aws): ``` ------ *結果*：您已成功啟動專案，並產生開發勾點所需的檔案。以下是構成 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 勾點的模型需要建立定義勾點、其屬性及其屬性的結構描述。當您使用 `cfn init`命令建立自訂 Hook 專案時，Hook 結構描述範例會建立為 JSON 格式的文字檔案 `hook-name.json`。 目標調用點和目標動作會指定叫用勾點的確切點。*勾點處理常式*託管這些點的可執行自訂邏輯。例如，`CREATE`操作的目標動作會使用`preCreate`處理常式。當 Hook 目標和服務執行相符動作時，您在處理常式中寫入的程式碼將會叫用 。*勾點目標*是調用勾點的目的地。您可以指定目標，例如 CloudFormation 公有資源、私有資源或自訂資源。勾點支援無限數量的勾點目標。 結構描述包含勾點所需的許可。編寫勾點需要您為每個勾點處理常式指定許可。CloudFormation 鼓勵作者撰寫遵循授予*最低權限*或僅授予執行任務所需許可之標準安全建議的政策。決定使用者 （和角色） 需要執行的動作，然後制定政策，允許他們*僅*執行勾點操作的任務。CloudFormation 使用這些許可來縮小範圍勾點使用者提供的許可。這些許可會傳遞至 勾點。勾點處理常式使用這些許可來存取 AWS 資源。 您可以使用下列結構描述檔案做為定義勾點的起點。使用勾點結構描述來指定您要實作的處理常式。如果您選擇不實作特定處理常式，請從勾點結構描述的處理常式區段中移除它。如需結構描述的詳細資訊，請參閱 [結構描述語法](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 勾點的模型需要建立定義勾點、其屬性及其屬性的結構描述。本教學課程會逐步引導您使用 Java 建立自訂勾點的模型。 ## 步驟 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 專案套件。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 處理常式執行時間程式碼新增至您選擇實作的處理常式。例如，您可以新增下列程式碼進行記錄。 ``` logger.log("Internal testing Hook triggered for target: " + request.getHookContext().getTargetName()); ``` CloudFormation CLI 會產生純舊 Java 物件 (Java POJO)。以下是從 產生的輸出範例`AWS::S3::Bucket`。 **Example AwsS3BucketTargetModel.java** ``` 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：實作勾點處理常式 **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` 資源，只有在下列情況為 true 時，勾點才會傳遞： + Amazon S3 儲存貯體加密已設定。 + 已啟用儲存貯體的 Amazon S3 儲存貯體金鑰。 + Amazon S3 儲存貯體的加密演算法集是所需的正確演算法。 + AWS Key Management Service 金鑰 ID 已設定。 + 對於 `AWS::SQS::Queue` 資源，只有在下列情況為 true 時，勾點才會傳遞： + 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` 資源，只有在下列情況為 true 時，勾點才會傳遞： + 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` 資源，只有在下列情況為 true 時，勾點才會傳遞： + 驗證刪除資源後，帳戶是否將存在最低必要投訴資源。 + 最低必要投訴資源數量是在 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 勾點的模型需要建立定義勾點、其屬性及其屬性的結構描述。本教學課程會逐步引導您使用 Python 建立自訂勾點的模型。 ## 步驟 1：產生勾點專案套件 產生您的 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 處理常式執行時間程式碼新增至您選擇實作的處理常式。例如，您可以新增下列程式碼進行記錄。 ``` LOG.setLevel(logging.INFO) LOG.info("Internal testing Hook triggered for target: " + request.hookContext.targetName); ``` CloudFormation CLI 會從 產生 `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 功能的處理常式。在此範例中，您將實作處理常式的 `preUpdate`、 `preCreate`和 `preDelete` 叫用點。 **Topics** + [實作 preCreate 處理常式](#model-hook-project-code-handler-python-precreate) + [實作 preUpdate 處理常式](#model-hook-project-code-handler-python-preupdate) + [實作 preDelete 處理常式](#model-hook-project-code-handler-python-predelete) + [實作勾點處理常式](#model-hook-project-code-handler-python-hook-handler) ### 實作 preCreate 處理常式 `preCreate` 處理常式會驗證 `AWS::S3::Bucket `或 `AWS::SQS::Queue` 資源的伺服器端加密設定。 + 對於 `AWS::S3::Bucket` 資源，只有在下列情況為 true 時，勾點才會傳遞。 + Amazon S3 儲存貯體加密已設定。 + 已啟用儲存貯體的 Amazon S3 儲存貯體金鑰。 + Amazon S3 儲存貯體的加密演算法集是所需的正確演算法。 + AWS Key Management Service 金鑰 ID 已設定。 + 對於 `AWS::SQS::Queue` 資源，只有在下列情況為 true 時，勾點才會傳遞。 + AWS Key Management Service 金鑰 ID 已設定。 ### 實作 preUpdate 處理常式 實作`preUpdate`處理常式，其會在處理常式中所有指定目標的更新操作之前啟動。`preUpdate` 處理常式會完成下列項目： + 對於 `AWS::S3::Bucket` 資源，只有在下列情況為 true 時，勾點才會傳遞： + Amazon S3 儲存貯體的儲存貯體加密演算法尚未修改。 ### 實作 preDelete 處理常式 實作`preDelete`處理常式，其會在處理常式中所有指定目標的刪除操作之前啟動。`preDelete` 處理常式會完成下列項目： + 對於 `AWS::S3::Bucket` 資源，只有在下列情況為 true 時，勾點才會傳遞： + 驗證刪除資源後，帳戶是否將存在最低必要合規資源。 + 最低合規資源數量是在 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}") ``` 繼續進行下一個主題[向 註冊自訂勾點 CloudFormation](registering-hooks.md)。 # 向 註冊自訂勾點 CloudFormation 建立自訂勾點後，您需要向 註冊它 CloudFormation ，才能使用它。在本節中，您將學習如何封裝和註冊您的勾點，以便在 中使用 AWS 帳戶。 ## 封裝勾點 (Java) 如果您已使用 Java 開發 Hook，請使用 Maven 來封裝它。 在 Hook 專案的 目錄中，執行下列命令來建置您的 Hook、執行單元測試，並將您的專案封裝為檔案`JAR`，可用來將 Hook 提交至 CloudFormation 登錄檔。 ``` mvn clean package ``` ## 註冊自訂勾點 **註冊勾點** 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’} ``` *結果*：您已成功註冊您的勾點。 ## 驗證勾點可在您的帳戶中存取 確認您的勾點在您提交勾點的 AWS 帳戶 和 區域中可用。 1. 若要驗證您的勾點，請使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)命令列出新註冊的勾點，並傳回其摘要說明。 ``` $ aws cloudformation list-types ``` 命令會傳回下列輸出，也會顯示您可以在 AWS 帳戶 和 區域中啟用的公開可用勾點。 ``` { "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` 從勾點的`list-type`輸出擷取 並儲存它。 ``` export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook ``` 若要了解如何發佈勾點以供公開使用，請參閱 [發佈勾點以供公開使用](hooks-publishing.md)。 ### 設定勾點 開發並註冊 Hook 之後，您可以透過將 Hook 發佈到登錄檔 AWS 帳戶 ，在 中設定您的 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`中設定為 。 **注意** 在帳戶中啟用勾點，即表示您授權勾點使用您 定義的許可 AWS 帳戶。CloudFormation 會在將您的許可傳遞給勾點之前，移除非必要的許可。CloudFormation 建議客戶或勾點使用者檢閱勾點許可，並注意在您的帳戶中啟用勾點之前允許勾點的許可。 在相同的 帳戶和 中，指定已註冊的 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 主動檢查堆疊的組態，您必須在帳戶中註冊和啟用 Hook 之後，在 `HookConfiguration`區段`HookInvocationStatus``ENABLED`中將 設定為 。 ## 在處理常式中存取 AWS APIs 如果您的 Hooks 在其任何處理常式中使用 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`旗標，則會佈建此堆疊中的角色，並用作勾點的執行角色。 如需詳細資訊，請參閱[從資源類型存取 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 和 Amazon 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 ``` # 在 中測試自訂勾點 AWS 帳戶 現在您已將對應至調用點的處理常式函數編碼，是時候在 CloudFormation 堆疊上測試自訂掛接了。 `FAIL` 如果 CloudFormation 範本未佈建具有下列項目的 S3 儲存貯體，則勾點失敗模式會設為 ： + Amazon S3 儲存貯體加密已設定。 + 已啟用儲存貯體的 Amazon S3 儲存貯體金鑰。 + Amazon S3 儲存貯體的加密演算法集是所需的正確演算法。 + AWS Key Management Service 金鑰 ID 已設定。 在下列範例中，建立名為 `my-failed-bucket-stack.yml` 且堆疊名稱為 的範本`my-hook-stack`，該範本會讓堆疊組態失敗，並在資源佈建之前停止。 ## 透過佈建堆疊來測試勾點 ### 範例 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 範本傳遞勾點驗證** 1. 若要建立堆疊並通過勾點驗證，請更新範本，讓您的資源使用加密的 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 ``` **注意** 不會針對略過的資源叫用勾點。 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 範本傳遞勾點驗證** 1. 若要建立堆疊並通過勾點驗證，請更新範本，讓您的資源使用加密的 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 ``` **注意** 不會針對略過的資源叫用勾點。 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`資源在佈建資源之前包含伺服器端加密。 # 更新自訂勾點 更新自訂勾點允許在 CloudFormation 登錄檔中提供勾點中的修訂。 若要更新自訂勾點，請透過 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 ``` 若要在帳戶中指定 Hook 的預設版本，請使用 [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 ``` 若要擷取有關勾點版本的資訊，請使用 [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" ``` # 從 CloudFormation 登錄檔取消註冊自訂掛鉤 取消註冊自訂勾點會將擴充功能或擴充功能版本標記為 CloudFormation 登錄`DEPRECATED`檔中的 ，這會將其從作用中使用中移除。一旦棄用，自訂勾點就無法在 CloudFormation 操作中使用。 **注意** 取消註冊勾點之前，您必須個別取消註冊該延伸模組的所有先前作用中版本。如需詳細資訊，請參閱[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 ``` 此命令不會產生輸出。 # 發佈勾點以供公開使用 若要開發公有第三方勾點，請將您的勾點開發為私有延伸模組。然後，在您要公開提供延伸項目的每個 AWS 區域 中： 1. 在 CloudFormation 登錄檔中將勾點註冊為私有延伸。 1. 測試您的勾點，以確保它符合在 CloudFormation 登錄檔中發佈的所有必要要求。 1. 將您的勾點發佈至 CloudFormation 登錄檔。 **注意** 在指定區域中發佈任何擴充功能之前，您必須先註冊為該區域中的擴充功能發佈者。若要同時在多個區域中執行此操作，請參閱《* CloudFormation CLI 使用者指南*》中的[使用 StackSets 在多個區域中發佈擴充](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension-stacksets.html)功能。 開發並註冊 Hook 之後，您可以將它*發佈*到 CloudFormation 登錄檔做為第三方公有延伸，讓一般 CloudFormation 使用者公開使用它。 公有第三方勾點可讓您提供 CloudFormation 使用者在佈建之前主動檢查 AWS 資源的組態。如同私有勾點，公有勾點與 CloudFormation AWS 內發佈的任何勾點視為相同。 發佈到登錄檔的勾點可供所有 CloudFormation 使用者在發佈它們 AWS 區域 的 中看見。然後，使用者可以在其帳戶中*啟用*您的擴充功能，以便在其範本中使用。如需詳細資訊，請參閱*CloudFormation 《 使用者指南*》中的[從 CloudFormation 登錄檔使用第三方公有擴充](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html)功能。 # 測試自訂勾點以供公開使用 若要發佈已註冊的自訂勾點，它必須通過為其定義的所有測試要求。以下是將自訂勾點發佈為第三方延伸模組之前所需的需求清單。 每個處理常式和目標都會經過兩次測試。一次用於 `SUCCESS`，一次用於 `FAILED`。 + 對於`SUCCESS`回應案例： + 狀態必須為 `SUCCESS`。 + 不得傳回錯誤碼。 + 如果指定，回呼延遲應設定為`0`秒。 + 對於`FAILED`回應案例： + 狀態必須為 `FAILED`。 + 必須傳回錯誤代碼。 + 必須有訊息作為回應。 + 如果指定，回呼延遲應設定為`0`秒。 + 對於`IN_PROGRESS`回應案例： + 不得傳回錯誤碼。 + `Result` 欄位不得在回應中設定。 # 指定用於合約測試的輸入資料 根據預設， 會使用您在 Hook 結構描述中定義的模式所產生的輸入屬性 CloudFormation 來執行合約測試。不過，大多數勾點都夠複雜，因此預先建立或預先更新佈建堆疊的輸入屬性需要了解佈建的資源。若要解決此問題，您可以指定 執行其合約測試 CloudFormation 時使用的輸入。 CloudFormation 提供兩種方式，可讓您指定輸入資料，以便在執行合約測試時使用： + 覆寫檔案 使用 `overrides` 檔案提供輕量方式，可指定特定屬性的輸入資料 CloudFormation ，以便在 `preCreate`、 `preUpdate`和 `preDelete`操作測試期間使用。 + 輸入檔案 在以下情況下，您也可以使用多個`input`檔案來指定合約測試輸入資料： + 您想要或需要為建立、更新和刪除操作指定不同的輸入資料，或測試的無效資料。 + 您想要指定多個不同的輸入資料集。 ## 使用覆寫檔案指定輸入資料 以下是使用 `overrides` 檔案的 Amazon S3 Hook 輸入資料範例。 ``` { "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` 檔案來指定不同類型的輸入資料 CloudFormation ，以供 使用：`preCreate`輸入、`preUpdate`輸入和無效的輸入。每種類型的資料都會在個別的檔案中指定。您也可以為合約測試指定多組輸入資料。 若要指定 CloudFormation 要在合約測試中使用的`input`檔案，請將 `inputs` 資料夾新增至 Hooks 專案的根目錄。然後新增您的輸入檔案。 使用以下命名慣例指定檔案包含的輸入資料類型，其中 **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)。 # CloudFormation 勾點的結構描述語法參考 本節說明您用來開發 CloudFormation Hooks 的結構描述語法。 勾點包含由 JSON 結構描述和勾點處理常式表示的勾點規格。建立自訂勾點的第一步是建立定義勾點、其屬性及其屬性的結構描述模型。當您使用 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 結構描述檔案。使用此結構描述檔案做為定義自訂勾點形狀和語意的起點。 ## 結構描述語法 下列結構描述是勾點的結構。 ``` { "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` 勾點的唯一名稱。為您的勾點指定三個部分的命名空間，建議模式為 `Organization::Service::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 主控台中顯示的勾點簡短描述。 *必要*：是 `sourceUrl` 如果為公有，Hook 的來源碼 URL。 *必要*：否 *上限*：`4096` `documentationUrl` 為 勾點提供詳細文件的頁面 URL。 *必要*：是 *模式*：`^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$` *上限*：`4096` 雖然勾點結構描述應包含完整且準確的屬性描述，但您可以使用 `documentationURL` 屬性為使用者提供更多詳細資訊，包括範例、使用案例和其他詳細資訊。 `definitions` 使用 `definitions`區塊提供共用的 Hook 屬性結構描述。 最佳實務是使用 `definitions`區段來定義結構描述元素，可用於勾點類型結構描述中的多個點。然後，您可以使用 JSON 指標在勾點類型結構描述中的適當位置參考該元素。 *必要*：否 `typeConfiguration` Hook 組態資料的定義。 *必要*：是 `properties` 勾點的屬性。勾點的所有屬性都必須在結構描述中表示。將勾點結構描述屬性與勾點類型組態屬性對齊。 不允許巢狀屬性。反之，請在 `definitions`元素中定義任何巢狀屬性，並使用`$ref`指標在所需的屬性中參考它們。 目前支援下列屬性： + `default` – 屬性的預設值。 + `description` – 屬性的描述。 + `pattern` – 用於驗證輸入的 regex 模式。 + `type` – 屬性的已接受類型。 `additionalProperties` `additionalProperties` 必須設定為 `false`。勾點的所有屬性都必須以結構描述表示：不允許任意輸入。 *必要*：是 *有效值*：`false` `handlers` 處理常式指定可啟動結構描述中定義的勾點的操作，例如勾點叫用點。例如，`preUpdate`在處理常式中所有指定目標的更新操作之前，會叫用處理常式。 *有效值*：`preCreate` \$1 `preUpdate` \$1 `preDelete` 必須為處理常式指定至少一個值。 導致 狀態的堆疊操作`UpdateCleanup`不會叫用勾點。例如，在以下兩個案例中，不會叫用 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`目標，則 Hook 會在預先佈建階段執行 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`。勾點的所有屬性都必須以結構描述表示：不允許任意輸入。 *必要*：是 *有效值*：`false` ## 勾點結構描述範例 **範例 1** Java 和 Python 演練使用以下程式碼範例。以下是名為 的勾點的範例結構`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` 的結構描述`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 } ```