翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudFormation CLI を使用したカスタムフックの開発 このセクションは、カスタムフックを開発して CloudFormation レジストリに登録したいお客様を対象としています。 CloudFormation フックの構造の概要と、Python または Java で独自のフックを開発、登録、テスト、管理、公開するためのガイドを提供します。 カスタムフックの開発には、主に 3 つのステップがあります。 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) コマンドを使用して、フックを作成することを指定します。詳細については、「[カスタム CloudFormation フックプロジェクトの開始](hooks-init.md)」を参照してください。 1. **[Model]** (モデル) フックスキーマをモデル化、作成、検証するには、フック、そのプロパティ、および属性を定義します。 CloudFormation CLI は、特定のフック呼び出しポイントに対応する空のハンドラー関数を作成します。これらのハンドラーに独自のロジックを追加して、ターゲットライフサイクルの各段階でフック呼び出し中に何が起こるかを制御します。詳細については、「[カスタム 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. *Publish* – フックはレジストリに発行されます。 1. *Configure* – フックは、タイプ設定がスタックに対して呼び出されたときに設定されます。 **注記** フックは 30 秒後にタイムアウトし、最大 3 回再試行します。詳細については、「[タイムアウトと再試行の制限](hooks-concepts.md#hook-timeout-and-retry-limits)」を参照してください。 **Topics** + [前提条件](hooks-prerequisites.md) + [Hooks プロジェクトの開始](hooks-init.md) + [モデリングフック](hooks-model.md) + [フックの登録](registering-hooks.md) + [フックのテスト](testing-hooks.md) + [フックの更新](updating-registered-hook.md) + [フックの登録解除](deregistering-hooks.md) + [フックの発行](hooks-publishing.md) + [スキーマ構文](hooks-schema.md) # カスタム CloudFormation フックを開発するための前提条件 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 プロジェクトにフックハンドラーを実装するには、[Java Hook ハンドラーのサンプルファイルを](samples/java-handlers.zip)ダウンロードできます。 **Python の前提条件** + [Python バージョン 3.8](https://www.python.org/downloads/) 以降。 Python Hooks プロジェクトのフックハンドラーを実装するには、[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 フックの IAM アクセス許可を付与する](grant-iam-permissions-for-hooks.md)」を参照してください。 ## Hooks の開発環境を設定する 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 フックプロジェクトの開始 カスタムフックプロジェクトを作成する最初のステップは、プロジェクトを開始することです。CloudFormation CLI `init` コマンドを使用して、カスタムフックプロジェクトを開始できます。 `init` コマンドは、フックスキーマファイルを含むプロジェクトの設定を順を追って説明するウィザードを起動します。このスキーマファイルをフックのシェイプとセマンティクスを定義するための開始点として使用します。詳細については、「[スキーマ構文](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. 言語プラグインが 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` ディレクトリ内のファイルは、言語の選択に基づいて作成されます。生成されたファイルには、役立つコメントと例がいくつかあります。などの一部のファイルは`models.py`、後のステップで `generate` コマンドを実行してハンドラーのランタイムコードを追加するときに自動的に更新されます。 # カスタム CloudFormation フックのモデリング カスタム CloudFormation フックのモデリングには、フック、そのプロパティ、および属性を定義するスキーマの作成が含まれます。`cfn init` コマンドを使用してカスタムフックプロジェクトを作成すると、サンプルフックスキーマが 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 プロジェクトパッケージを生成する Hook プロジェクトパッケージを生成します。CloudFormation CLI は、フック仕様で定義されているように、ターゲットライフサイクル内の特定のフックアクションに対応する空のハンドラー関数を作成します。 ``` 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: フックハンドラーを追加する 実装するハンドラーに独自のフックハンドラーランタイムコードを追加します。たとえば、ログ記録に次のコードを追加できます。 ``` logger.log("Internal testing Hook triggered for target: " + request.getHookContext().getTargetName()); ``` CloudFormation CLI は Plain Old Java Objects (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 が生成されると、フックの機能を実際に実装するハンドラーを記述できるようになりました。この例では、ハンドラーの `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 の場合にのみ渡されます。 + リソースを削除した後、最低限必要な苦情リソースがアカウントに存在することを確認します。 + 必要な苦情リソースの最小量は、フックのタイプ設定で設定されます。 ### `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 プロジェクトパッケージを生成する Hook プロジェクトパッケージを生成します。CloudFormation CLI は、フック仕様で定義されているように、ターゲットライフサイクル内の特定のフックアクションに対応する空のハンドラー関数を作成します。 ``` 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: フックハンドラーを追加する 実装するハンドラーに独自のフックハンドラーランタイムコードを追加します。たとえば、ログ記録に次のコードを追加できます。 ``` 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 データクラスを生成すると、実際にフックの機能を実装するハンドラーを記述できます。この例では、ハンドラーの `preCreate`、`preUpdate`、および `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 の場合にのみ渡されます。 + リソースを削除した後、最低限必要な準拠リソースがアカウントに存在することを確認します。 + 最低限必要な準拠リソースの量は、フックの設定で設定されます。 ### フックハンドラーの実装 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) Hook with Java を開発している場合は、Maven を使用してパッケージ化します。 Hook プロジェクトの ディレクトリで、次のコマンドを実行してフックを構築し、ユニットテストを実行し、プロジェクトを`JAR`ファイルとしてパッケージ化し、これを使用してフックを 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. (オプション) 次のコマンドは、フックプロジェクトを登録せずにビルドしてパッケージ化します。 ``` $ 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. フックの`list-type`出力`TypeArn`から を取得し、保存します。 ``` export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook ``` 公開用にフックを発行する方法については、「」を参照してください[公開用フックの公開](hooks-publishing.md)。 ### フックの設定 フックを開発して登録したら、 レジストリに公開 AWS アカウント することで、 でフックを設定できます。 + アカウントでフックを設定するには、 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html)オペレーションを使用します。このオペレーションにより、フックのスキーマ `properties` セクションで定義されているフックのプロパティが有効になります。次の例では、設定`1`で `minBuckets`プロパティが に設定されています。 **注記** アカウントでフックを有効にすると、 から定義されたアクセス許可を使用するフックを承認します 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 ``` **重要** フックがスタックの設定をプロアクティブに検査できるようにするには、フックがアカウントに登録されてアクティブ化された後、 `HookConfiguration`セクション`HookInvocationStatus``ENABLED`で を に設定する必要があります。 ## ハンドラーでの AWS APIs へのアクセス Hooks がいずれかのハンドラーで AWS API を使用する場合、CFN-CLI は IAM 実行ロールテンプレート を自動的に作成します`hook-role.yaml`。`hook-role.yaml` テンプレートは、フックスキーマのハンドラーの セクションで各ハンドラーに指定されたアクセス許可に基づいています。[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 スタックでカスタムフックをテストします。 CloudFormation テンプレート`FAIL`が以下を使用して 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" }, ... ] } ``` *結果*: フック呼び出しはスタック設定に失敗し、リソースのプロビジョニングを停止しました。 **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" }, ... ] } ``` *結果*: フック呼び出しはスタック設定に失敗し、リソースのプロビジョニングを停止しました。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 ``` アカウントでフックのデフォルトバージョンを指定するには、 [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 内で によって発行されたフックと同じように扱われます。 レジストリに公開されたフックは、公開されている AWS リージョン のすべての CloudFormation ユーザーに表示されます。その後、ユーザーはアカウントで拡張機能を*アクティブ化*して、テンプレートで使用できるようにします。詳細については、[「 ユーザーガイド」のCloudFormation レジストリからサードパーティーのパブリック拡張機能](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html)を使用する」を参照してください。 *CloudFormation * # パブリック使用のためのカスタムフックのテスト 登録されたカスタムフックを公開するには、そのフックに定義されているすべてのテスト要件に合格する必要があります。以下は、カスタムフックをサードパーティー拡張機能として公開する前に必要な要件のリストです。 各ハンドラーとターゲットは 2 回テストされます。の場合は 1 回`SUCCESS`、 の場合は 1 回`FAILED`。 + `SUCCESS` レスポンスケースの場合: + ステータスは である必要があります`SUCCESS`。 + エラーコードを返さないでください。 + コールバック遅延は、指定されている場合は`0`秒に設定する必要があります。 + `FAILED` レスポンスケースの場合: + ステータスは である必要があります`FAILED`。 + エラーコードを返す必要があります。 + レスポンスにメッセージが必要です。 + コールバック遅延は、指定されている場合は`0`秒に設定する必要があります。 + `IN_PROGRESS` レスポンスケースの場合: + エラーコードを返さないでください。 + `Result` レスポンスで フィールドを設定することはできません。 # 契約テストで使用する入力データの指定 デフォルトでは、 はフックスキーマで定義したパターンから生成された入力プロパティを使用して契約テスト CloudFormation を実行します。ただし、ほとんどのフックは複雑であるため、プロビジョニングスタックを事前作成または事前更新するための入力プロパティには、プロビジョニングされるリソースの理解が必要です。これに対処するには、 が契約テストを実行するときに CloudFormation 使用する入力を指定できます。 CloudFormation には、契約テストを実行するときに使用する入力データを指定する 2 つの方法があります。 + ファイルを上書きする `overrides` ファイルを使用すると、 の特定のプロパティの入力データを軽量に指定 CloudFormation し`preCreate`、 `preUpdate`および `preDelete`オペレーションテストで使用できます。 + 入力ファイル 以下の場合は、複数の`input`ファイルを使用して契約テスト入力データを指定することもできます。 + 作成、更新、削除オペレーションに異なる入力データを指定するか、テストする無効なデータを指定する必要があります。 + 複数の異なる入力データセットを指定します。 ## オーバーライドファイルを使用した入力データの指定 以下は、 `overrides` ファイルを使用した Amazon S3 フックの入力データの例です。 ``` { "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`ファイルを指定するには、Hooks プロジェクトのルートディレクトリに `inputs`フォルダを追加します。次に、入力ファイルを追加します。 次の命名規則を使用して、ファイルに含まれる入力データの種類を指定します。**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 ファイルです。 以下は、入力ファイルを使用して入力データ Amazon S3 を指定`inputs`するための ディレクトリの例です。 `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 ユーザーガイドの [Publishing extensions to make them available for public use](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension.html) を参照してください。** # CloudFormation フックのスキーマ構文リファレンス このセクションでは、 CloudFormation フックの開発に使用するスキーマの構文について説明します。 フックには、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) コマンドを使用してカスタムフックプロジェクトを初期化すると、フックスキーマファイルが作成されます。このスキーマファイルを、カスタムフックのシェイプとセマンティクスを定義するための開始点として使用します。 ## スキーマ構文 次のスキーマはフックの構造です。 ``` { "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` フックの一意の名前。フックの 3 つの部分からなる名前空間を指定し、推奨パターンは です`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` パブリックの場合、フックのソースコードの URL。 *必須:* いいえ *最大*: `4096` `documentationUrl` フックの詳細なドキュメントを提供するページの URL。 *必須:* はい *パターン*: `^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$` *最大*: `4096` フックスキーマには完全で正確なプロパティの説明を含める必要がありますが、 `documentationURL`プロパティを使用して、例、ユースケース、その他の詳細情報などの詳細をユーザーに提供できます。 `definitions` `definitions` ブロックを使用して、共有フックプロパティスキーマを提供します。 ベストプラクティスとして、 `definitions`セクションを使用して、フックタイプスキーマの複数のポイントで使用できるスキーマ要素を定義します。その後、JSON ポインタを使用して、フックタイプスキーマの適切な場所でその要素を参照できます。 *必須:* いいえ `typeConfiguration` フックの設定データの定義。 *必須:* はい `properties` フックのプロパティ。フックのすべてのプロパティは、スキーマで表現する必要があります。フックスキーマプロパティをフックタイプの設定プロパティに合わせます。 ネストされたプロパティは許可されません。代わりに、 `definitions`要素でネストされたプロパティを定義し、`$ref`ポインタを使用して目的のプロパティでそれらを参照します。 現在、次のプロパティがサポートされています。 + `default` – プロパティのデフォルト値。 + `description` – プロパティの説明。 + `pattern` – 入力の検証に使用される正規表現パターン。 + `type` – プロパティの受け入れられたタイプ。 `additionalProperties` `additionalProperties` を `false` に設定する必要があります。フックのすべてのプロパティはスキーマで表現する必要があります。任意の入力は許可されません。 *必須:* はい *有効な値:* `false` `handlers` ハンドラーは、フック呼び出しポイントなど、スキーマで定義されたフックを開始できるオペレーションを指定します。たとえば、`preUpdate`ハンドラー内のすべての指定されたターゲットの更新オペレーションの前にハンドラーが呼び出されます。 有効な値: `preCreate` \$1 `preUpdate` \$1 `preDelete` ハンドラーには少なくとも 1 つの値を指定する必要があります。 ステータスが になるスタックオペレーションでは、フックは呼び出`UpdateCleanup`されません。たとえば、次の 2 つのシナリオでは、フックの`preDelete`ハンドラーは呼び出されません。 + スタックは、テンプレートから 1 つのリソースを削除した後に更新されます。 + 更新タイプの[置換](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)のリソースが削除されます。 `targetNames` Hook がターゲットとする型名の文字列配列。たとえば、`preCreate`ハンドラーに `AWS::S3::Bucket`ターゲットがある場合、フックは事前プロビジョニングフェーズ中に Amazon S3 バケットに対して実行されます。 + `TargetName` 実装されたハンドラーごとに少なくとも 1 つのターゲット名を指定します。 *パターン*: `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *最小*: `1` *必須:* はい **警告** SSM SecureString および Secrets Manager の動的参照は、フックに渡される前に解決されません。 `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 } ```