Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Développement de Hooks personnalisés à l'aide de la CloudFormation CLI Cette section est destinée aux clients qui souhaitent développer des Hooks personnalisés et les enregistrer dans le CloudFormation registre. Il fournit une vue d'ensemble de la structure des CloudFormation Hooks et des guides pour développer, enregistrer, tester, gérer et publier vos propres Hooks avec Python ou Java. Le développement d'un Hook personnalisé comporte trois étapes principales : 1. **Initier** Pour développer des Hooks personnalisés, vous devez configurer et utiliser la CloudFormation CLI. Pour lancer le projet d'un Hook et ses fichiers requis, utilisez la [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)commande CloudFormation CLI et spécifiez que vous souhaitez créer un Hook. Pour de plus amples informations, veuillez consulter [Lancer un projet CloudFormation Hooks personnalisé](hooks-init.md). 1. **Modèle** Pour modéliser, créer et valider votre schéma Hook, définissez le Hook, ses propriétés et ses attributs. La CloudFormation CLI crée des fonctions de gestion vides qui correspondent à un point d'invocation Hook spécifique. Ajoutez votre propre logique à ces gestionnaires pour contrôler ce qui se passe lors de votre invocation de Hook à chaque étape du cycle de vie cible. Pour de plus amples informations, veuillez consulter [Modélisation de CloudFormation crochets personnalisés](hooks-model.md). 1. **S'inscrire** Pour enregistrer un Hook, soumettez votre Hook pour qu'il soit enregistré en tant qu'extension tierce privée ou publique. Enregistrez votre Hook lors de l'`[submit](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html)`opération. Pour de plus amples informations, veuillez consulter [Enregistrer un Hook personnalisé avec CloudFormation](registering-hooks.md). Les tâches suivantes sont associées à l'enregistrement de votre Hook : 1. *Publier* — Les hooks sont publiés dans le registre. 1. *Configurer* — Les hooks sont configurés lorsque la configuration de type est invoquée contre des piles. **Note** Les Hooks expireront au bout de 30 secondes et réessayeront jusqu'à 3 fois. Pour de plus amples informations, veuillez consulter [Limites de délai et de nouvelles tentatives](hooks-concepts.md#hook-timeout-and-retry-limits). **Topics** + [Conditions préalables](hooks-prerequisites.md) + [Lancer un projet Hooks](hooks-init.md) + [Crochets de modélisation](hooks-model.md) + [Enregistrement des Hooks](registering-hooks.md) + [Crochets de test](testing-hooks.md) + [Mettre à jour les hooks](updating-registered-hook.md) + [Annulation de l'enregistrement de Hooks](deregistering-hooks.md) + [Hooks de publication](hooks-publishing.md) + [Syntaxe du schéma](hooks-schema.md) # Conditions préalables au développement de Hooks personnalisés CloudFormation Vous pouvez développer un Hook personnalisé avec Java ou Python. Les conditions requises pour développer des Hooks personnalisés sont les suivantes : **Prérequis pour Java** + [Apache Maven](https://maven.apache.org/install.html) + [JDK 17](https://www.oracle.com/java/technologies/downloads/#java17) **Note** Si vous avez l'intention d'utiliser l'[interface de ligne de CloudFormation commande (CLI)](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) pour lancer un projet Hooks pour Java, vous devez également installer Python 3.8 ou version ultérieure. Le plugin Java pour la CloudFormation CLI peut être installé via `pip` (le gestionnaire de paquets de Python), qui est distribué avec Python. Pour implémenter des gestionnaires Hook pour votre projet Java Hooks, vous pouvez télécharger les fichiers d'[exemple des gestionnaires Java Hook](samples/java-handlers.zip). **Prérequis pour Python** + [Python version 3.8](https://www.python.org/downloads/) ou ultérieure. Pour implémenter des gestionnaires Hook pour votre projet Python Hooks, vous pouvez télécharger les fichiers d'[exemple des gestionnaires Python Hook](samples/python-handlers.zip). ## Autorisations pour développer des Hooks Outre les autorisations CloudFormation `Create`,`Update`, et `Delete` stack, vous devez avoir accès aux AWS CloudFormation opérations suivantes. L'accès à ces opérations est géré par le biais de la CloudFormation politique de votre rôle IAM. + [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) Pour de plus amples informations, veuillez consulter [Accorder des autorisations IAM pour les Hooks CloudFormation](grant-iam-permissions-for-hooks.md). ## Configurer un environnement de développement pour les Hooks Pour développer des Hooks, vous devez être familiarisé avec les [CloudFormation modèles](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html), qu'il s'agisse de Python ou de Java. **Pour installer la CloudFormation CLI et les plugins associés :** 1. Installez la CloudFormation CLI avec `pip` le gestionnaire de packages Python. ``` pip3 install cloudformation-cli ``` 1. Installez le plugin Python ou Java pour la CloudFormation CLI. ------ #### [ Python ] ``` pip3 install cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install cloudformation-cli-java-plugin ``` ------ Pour mettre à niveau la CloudFormation CLI et le plugin, vous pouvez utiliser l'option de mise à niveau. ------ #### [ Python ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-java-plugin ``` ------ # Lancer un projet CloudFormation Hooks personnalisé La première étape de la création de votre projet Hooks personnalisé consiste à lancer le projet. Vous pouvez utiliser la `init` commande CloudFormation CLI pour lancer votre projet Hooks personnalisé. La `init` commande lance un assistant qui vous guide tout au long de la configuration du projet, y compris un fichier de schéma Hooks. Utilisez ce fichier de schéma comme point de départ pour définir la forme et la sémantique de vos Hooks. Pour de plus amples informations, veuillez consulter [Syntaxe du schéma](hooks-schema.md). **Pour lancer un projet Hook :** 1. Créez un répertoire pour le projet. ``` mkdir ~/mycompany-testing-mytesthook ``` 1. Accédez au nouveau répertoire. ``` cd ~/mycompany-testing-mytesthook ``` 1. Utilisez la `init` commande CloudFormation CLI pour lancer le projet. ``` cfn init ``` La commande renvoie le résultat suivant. ``` Initializing new project ``` 1. La `init` commande lance un assistant qui vous guide tout au long de la configuration du projet. Lorsque vous y êtes invité, entrez `h` pour spécifier un projet Hooks. ``` Do you want to develop a new resource(r) a module(m) or a hook(h)? ``` ``` h ``` 1. Entrez un nom pour votre type de Hook. ``` What's the name of your hook type? (Organization::Service::Hook) ``` ``` MyCompany::Testing::MyTestHook ``` 1. Si un seul plugin de langue est installé, il est sélectionné par défaut. Si plusieurs plug-ins linguistiques sont installés, vous pouvez choisir la langue de votre choix. Entrez une sélection de numéros pour la langue de votre choix. ``` Select a language for code generation: [1] java [2] python38 [3] python39 (enter an integer): ``` 1. Configurez le packaging en fonction du langage de développement choisi. ------ #### [ Python ] (*Facultatif*) Choisissez Docker pour un emballage indépendant de la plate-forme. Bien que Docker ne soit pas obligatoire, il est fortement recommandé pour faciliter l'emballage. ``` Use docker for platform-independent packaging (Y/n)? This is highly recommended unless you are experienced with cross-platform Python packaging. ``` ------ #### [ Java ] Définissez le nom du package Java et choisissez un modèle de codegen. Vous pouvez utiliser le nom du package par défaut ou en créer un nouveau. ``` Enter a package name (empty for default 'com.mycompany.testing.mytesthook'): ``` ``` Choose codegen model - 1 (default) or 2 (guided-aws): ``` ------ *Résultats* : Vous avez lancé le projet avec succès et avez généré les fichiers nécessaires au développement d'un Hook. Voici un exemple des répertoires et des fichiers qui constituent un projet Hooks pour Python 3.8. ``` 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 ``` **Note** Les fichiers du `src` répertoire sont créés en fonction de la langue que vous avez sélectionnée. Les fichiers générés contiennent des commentaires et des exemples utiles. Certains fichiers, tels que`models.py`, sont automatiquement mis à jour ultérieurement lorsque vous exécutez la `generate` commande pour ajouter du code d'exécution pour vos gestionnaires. # Modélisation de CloudFormation crochets personnalisés La modélisation de CloudFormation Hooks personnalisés implique la création d'un schéma qui définit le Hook, ses propriétés et ses attributs. Lorsque vous créez votre projet Hook personnalisé à l'aide de la `cfn init` commande, un exemple de schéma Hook est créé sous forme de fichier texte au format JSON,. `hook-name.json` Les points d'invocation cibles et les actions cibles spécifient le point exact où le Hook est invoqué. *Les gestionnaires de crochets hébergent* une logique personnalisée exécutable pour ces points. Par exemple, une action cible de l'`CREATE`opération utilise un `preCreate` gestionnaire. Votre code écrit dans le gestionnaire sera invoqué lorsque les cibles et les services Hook exécuteront une action correspondante. Les *cibles des crochets* sont la destination où les crochets sont invoqués. Vous pouvez spécifier des cibles telles que des ressources CloudFormation publiques, des ressources privées ou des ressources personnalisées. Les Hooks supportent un nombre illimité de cibles Hook. Le schéma contient les autorisations requises pour le Hook. Pour créer le Hook, vous devez spécifier des autorisations pour chaque gestionnaire Hook. CloudFormation encourage les auteurs à rédiger des politiques qui suivent les conseils de sécurité standard consistant à accorder le *moindre privilège* ou à n'accorder que les autorisations requises pour effectuer une tâche. Déterminez ce que les utilisateurs (et les rôles) doivent faire, puis élaborez des politiques qui leur permettent d'effectuer *uniquement* ces tâches pour les opérations Hook. CloudFormation utilise ces autorisations pour réduire les autorisations fournies par les utilisateurs de Hook. Ces autorisations sont transmises au Hook. Les gestionnaires de Hook utilisent ces autorisations pour accéder aux AWS ressources. Vous pouvez utiliser le fichier de schéma suivant comme point de départ pour définir votre Hook. Utilisez le schéma Hook pour spécifier les gestionnaires que vous souhaitez implémenter. Si vous choisissez de ne pas implémenter un gestionnaire spécifique, supprimez-le de la section des gestionnaires du schéma Hook. Pour plus de détails sur le schéma, consultez[Syntaxe du schéma](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** + [Modélisation de CloudFormation Hooks personnalisés en utilisant Java](hooks-model-java.md) + [Modélisation de CloudFormation Hooks personnalisés à l'aide de Python](hooks-model-python.md) # Modélisation de CloudFormation Hooks personnalisés en utilisant Java La modélisation de CloudFormation Hooks personnalisés implique la création d'un schéma qui définit le Hook, ses propriétés et ses attributs. Ce didacticiel vous explique comment modéliser des Hooks personnalisés à l'aide de Java. ## Étape 1 : Ajouter les dépendances du projet Les projets Hooks basés sur Java s'appuient sur le `pom.xml` fichier de Maven comme dépendance. Développez la section suivante et copiez le code source dans le `pom.xml` fichier situé à la racine du projet. ### Dépendances du projet Hook (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 ``` ## Étape 2 : Générer le package du projet Hook Générez votre package de projet Hook. La CloudFormation CLI crée des fonctions de gestion vides qui correspondent à des actions Hook spécifiques dans le cycle de vie cible, telles que définies dans la spécification Hook. ``` cfn generate ``` La commande renvoie le résultat suivant. ``` Generated files for MyCompany::Testing::MyTestHook ``` **Note** Assurez-vous que vos environnements d'exécution Lambda doivent éviter up-to-date d'utiliser une version obsolète. Pour plus d'informations, consultez la section [Mise à jour des environnements d'exécution Lambda pour les types de ressources](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html) et les Hooks. ## Étape 3 : Ajouter des gestionnaires Hook Ajoutez votre propre code d'exécution du gestionnaire Hook aux gestionnaires que vous choisissez d'implémenter. Par exemple, vous pouvez ajouter le code suivant pour la journalisation. ``` logger.log("Internal testing Hook triggered for target: " + request.getHookContext().getTargetName()); ``` La CloudFormation CLI génère un Plain Old Java Objects (Java POJO). Voici des exemples de sortie générés à partir de`AWS::S3::Bucket`. **Example WASS3 .java BucketTargetModel** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import... @Data @NoArgsConstructor @EqualsAndHashCode(callSuper = true) @ToString(callSuper = true) @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class AwsS3BucketTargetModel extends ResourceHookTargetModel { @JsonIgnore private static final TypeReference TARGET_REFERENCE = new TypeReference() {}; @JsonIgnore private static final TypeReference MODEL_REFERENCE = new TypeReference() {}; @JsonIgnore public static final String TARGET_TYPE_NAME = "AWS::S3::Bucket"; @JsonIgnore public TypeReference getHookTargetTypeReference() { return TARGET_REFERENCE; } @JsonIgnore public TypeReference getTargetModelTypeReference() { return MODEL_REFERENCE; } } ``` **Example AwsS3Bucket.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @EqualsAndHashCode(callSuper = true) @ToString(callSuper = true) @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class AwsS3Bucket extends ResourceHookTarget { @JsonIgnore public static final String TYPE_NAME = "AWS::S3::Bucket"; @JsonIgnore public static final String IDENTIFIER_KEY_ID = "/properties/Id"; @JsonProperty("InventoryConfigurations") private List inventoryConfigurations; @JsonProperty("WebsiteConfiguration") private WebsiteConfiguration websiteConfiguration; @JsonProperty("DualStackDomainName") private String dualStackDomainName; @JsonProperty("AccessControl") private String accessControl; @JsonProperty("AnalyticsConfigurations") private List analyticsConfigurations; @JsonProperty("AccelerateConfiguration") private AccelerateConfiguration accelerateConfiguration; @JsonProperty("PublicAccessBlockConfiguration") private PublicAccessBlockConfiguration publicAccessBlockConfiguration; @JsonProperty("BucketName") private String bucketName; @JsonProperty("RegionalDomainName") private String regionalDomainName; @JsonProperty("OwnershipControls") private OwnershipControls ownershipControls; @JsonProperty("ObjectLockConfiguration") private ObjectLockConfiguration objectLockConfiguration; @JsonProperty("ObjectLockEnabled") private Boolean objectLockEnabled; @JsonProperty("LoggingConfiguration") private LoggingConfiguration loggingConfiguration; @JsonProperty("ReplicationConfiguration") private ReplicationConfiguration replicationConfiguration; @JsonProperty("Tags") private List tags; @JsonProperty("DomainName") private String domainName; @JsonProperty("BucketEncryption") private BucketEncryption bucketEncryption; @JsonProperty("WebsiteURL") private String websiteURL; @JsonProperty("NotificationConfiguration") private NotificationConfiguration notificationConfiguration; @JsonProperty("LifecycleConfiguration") private LifecycleConfiguration lifecycleConfiguration; @JsonProperty("VersioningConfiguration") private VersioningConfiguration versioningConfiguration; @JsonProperty("MetricsConfigurations") private List metricsConfigurations; @JsonProperty("IntelligentTieringConfigurations") private List intelligentTieringConfigurations; @JsonProperty("CorsConfiguration") private CorsConfiguration corsConfiguration; @JsonProperty("Id") private String id; @JsonProperty("Arn") private String arn; @JsonIgnore public JSONObject getPrimaryIdentifier() { final JSONObject identifier = new JSONObject(); if (this.getId() != null) { identifier.put(IDENTIFIER_KEY_ID, this.getId()); } // only return the identifier if it can be used, i.e. if all components are present return identifier.length() == 1 ? identifier : null; } @JsonIgnore public List getAdditionalIdentifiers() { final List identifiers = new ArrayList(); // only return the identifiers if any can be used return identifiers.isEmpty() ? null : identifiers; } } ``` **Example BucketEncryption.java** ``` package software.amazon.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class BucketEncryption { @JsonProperty("ServerSideEncryptionConfiguration") private List serverSideEncryptionConfiguration; } ``` **Example ServerSideEncryptionRule.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class ServerSideEncryptionRule { @JsonProperty("BucketKeyEnabled") private Boolean bucketKeyEnabled; @JsonProperty("ServerSideEncryptionByDefault") private ServerSideEncryptionByDefault serverSideEncryptionByDefault; } ``` **Example ServerSideEncryptionByDefault.java** ``` package com.mycompany.testing.mytesthook.model.aws.s3.bucket; import ... @Data @Builder @AllArgsConstructor @NoArgsConstructor @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE) public class ServerSideEncryptionByDefault { @JsonProperty("SSEAlgorithm") private String sSEAlgorithm; @JsonProperty("KMSMasterKeyID") private String kMSMasterKeyID; } ``` Avec le POJOs fichier généré, vous pouvez désormais écrire les gestionnaires qui implémentent réellement les fonctionnalités du Hook. Pour cet exemple, implémentez le point `preUpdate` d'invocation `preCreate` and pour les gestionnaires. ## Étape 4 : Implémenter les gestionnaires Hook **Topics** + [Codage du générateur de clients API](#java-code-api-client-builder) + [Codage du générateur de demandes d'API](#code-the-api-request-maker) + [Implémentation du code d'assistance](#implement-helper-code) + [Implémentation du gestionnaire de base](#implement-base-hook-handler) + [Implémentation du `preCreate` gestionnaire](#implementing-precreate-handler) + [Codage du `preCreate` gestionnaire](#coding-the-precreate-handler) + [Mettre à jour le `preCreate` test](#updating-the-precreate-handler) + [Implémentation du `preUpdate` gestionnaire](#implementing-preupdate-handler) + [Codage du `preUpdate` gestionnaire](#coding-preupdate-handler) + [Mettre à jour le `preUpdate` test](#update-the-preupdate-handler) + [Implémentation du `preDelete` gestionnaire](#implement-the-predelete-hander) + [Codage du `preDelete` gestionnaire](#code-the-predelete-handler) + [Mettre à jour le `preDelete` gestionnaire](#update-the-predelete-handler) ### Codage du générateur de clients API 1. Dans votre IDE, ouvrez le `ClientBuilder.java` fichier situé dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `ClientBuilder.java` fichier par le code suivant. **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(); } } ``` ### Codage du générateur de demandes d'API 1. Dans votre IDE, ouvrez le `Translator.java` fichier situé dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `Translator.java` fichier par le code suivant. **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(); } } ``` ### Implémentation du code d'assistance 1. Dans votre IDE, ouvrez le `AbstractTestBase.java` fichier situé dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `AbstractTestBase.java` fichier par le code suivant. **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 ) ); } } ``` ### Implémentation du gestionnaire de base 1. Dans votre IDE, ouvrez le `BaseHookHandlerStd.java` fichier situé dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `BaseHookHandlerStd.java` fichier par le code suivant. **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); } } } ``` ### Implémentation du `preCreate` gestionnaire Le `preCreate` gestionnaire vérifie les paramètres de chiffrement côté serveur pour une ressource ou. `AWS::S3::Bucket` `AWS::SQS::Queue` + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + Le chiffrement du compartiment Amazon S3 est défini. + La clé du compartiment Amazon S3 est activée pour le compartiment. + L'algorithme de chiffrement défini pour le compartiment Amazon S3 est le bon algorithme requis. + L'identifiant de la AWS Key Management Service clé est défini. + Pour une `AWS::SQS::Queue` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + L'identifiant de la AWS Key Management Service clé est défini. ### Codage du `preCreate` gestionnaire 1. Dans votre IDE, ouvrez le `PreCreateHookHandler.java` fichier situé dans le `src/main/java/software/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreCreateHookHandler.java` fichier par le code suivant. ``` 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(); } } ``` ### Mettre à jour le `preCreate` test 1. Dans votre IDE, ouvrez le `PreCreateHandlerTest.java` fichier situé dans le `src/test/java/software/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreCreateHandlerTest.java` fichier par le code suivant. ``` 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(); } } ``` ### Implémentation du `preUpdate` gestionnaire Implémentez un `preUpdate` gestionnaire, qui démarre avant les opérations de mise à jour pour toutes les cibles spécifiées dans le gestionnaire. Le `preUpdate` gestionnaire effectue les opérations suivantes : + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + L'algorithme de chiffrement des compartiments pour un compartiment Amazon S3 n'a pas été modifié. ### Codage du `preUpdate` gestionnaire 1. Dans votre IDE, ouvrez le `PreUpdateHookHandler.java` fichier situé dans le `src/main/java/software/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreUpdateHookHandler.java` fichier par le code suivant. ``` 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(); } } ``` ### Mettre à jour le `preUpdate` test 1. Dans votre IDE, ouvrez le `PreUpdateHandlerTest.java` fichier dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreUpdateHandlerTest.java` fichier par le code suivant. ``` 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(); } } ``` ### Implémentation du `preDelete` gestionnaire Implémentez un `preDelete` gestionnaire, qui démarre avant les opérations de suppression pour toutes les cibles spécifiées dans le gestionnaire. Le `preDelete` gestionnaire effectue les opérations suivantes : + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + Vérifie que les ressources minimales requises pour les plaintes existeront dans le compte après la suppression de la ressource. + Le montant minimum de ressources requises pour les réclamations est défini dans la configuration de type du Hook. ### Codage du `preDelete` gestionnaire 1. Dans votre IDE, ouvrez le `PreDeleteHookHandler.java` fichier dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreDeleteHookHandler.java` fichier par le code suivant. ``` 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); } } } ``` ### Mettre à jour le `preDelete` gestionnaire 1. Dans votre IDE, ouvrez le `PreDeleteHookHandler.java` fichier dans le `src/main/java/com/mycompany/testing/mytesthook` dossier. 1. Remplacez l'intégralité du contenu du `PreDeleteHookHandler.java` fichier par le code suivant. ``` 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(); } } ``` # Modélisation de CloudFormation Hooks personnalisés à l'aide de Python La modélisation de CloudFormation Hooks personnalisés implique la création d'un schéma qui définit le Hook, ses propriétés et ses attributs. Ce didacticiel vous explique comment modéliser des Hooks personnalisés à l'aide de Python. ## Étape 1 : Générer le package du projet Hook Générez votre package de projet Hook. La CloudFormation CLI crée des fonctions de gestion vides qui correspondent à des actions Hook spécifiques dans le cycle de vie cible, telles que définies dans la spécification Hook. ``` cfn generate ``` La commande renvoie le résultat suivant. ``` Generated files for MyCompany::Testing::MyTestHook ``` **Note** Assurez-vous que vos environnements d'exécution Lambda doivent éviter up-to-date d'utiliser une version obsolète. Pour plus d'informations, consultez la section [Mise à jour des environnements d'exécution Lambda pour les types de ressources](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html) et les Hooks. ## Étape 2 : Ajouter des gestionnaires Hook Ajoutez votre propre code d'exécution du gestionnaire Hook aux gestionnaires que vous choisissez d'implémenter. Par exemple, vous pouvez ajouter le code suivant pour la journalisation. ``` LOG.setLevel(logging.INFO) LOG.info("Internal testing Hook triggered for target: " + request.hookContext.targetName); ``` La CloudFormation CLI génère le `src/models.py` fichier à partir du[Référence syntaxique du schéma de configuration Hook](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 ``` ## Étape 3 : Implémenter les gestionnaires Hook Avec les classes de données Python générées, vous pouvez écrire les gestionnaires qui implémentent réellement les fonctionnalités du Hook. Dans cet exemple, vous allez implémenter les points `preCreate``preUpdate`, et `preDelete` d'invocation pour les gestionnaires. **Topics** + [Implémenter le gestionnaire PreCreate](#model-hook-project-code-handler-python-precreate) + [Implémenter le gestionnaire PreUpdate](#model-hook-project-code-handler-python-preupdate) + [Implémenter le gestionnaire PreDelete](#model-hook-project-code-handler-python-predelete) + [Implémenter un gestionnaire Hook](#model-hook-project-code-handler-python-hook-handler) ### Implémenter le gestionnaire PreCreate Le `preCreate` gestionnaire vérifie les paramètres de chiffrement côté serveur pour une ressource ou. `AWS::S3::Bucket ` `AWS::SQS::Queue` + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies. + Le chiffrement du compartiment Amazon S3 est défini. + La clé du compartiment Amazon S3 est activée pour le compartiment. + L'algorithme de chiffrement défini pour le compartiment Amazon S3 est le bon algorithme requis. + L'identifiant de la AWS Key Management Service clé est défini. + Pour une `AWS::SQS::Queue` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies. + L'identifiant de la AWS Key Management Service clé est défini. ### Implémenter le gestionnaire PreUpdate Implémentez un `preUpdate` gestionnaire, qui démarre avant les opérations de mise à jour pour toutes les cibles spécifiées dans le gestionnaire. Le `preUpdate` gestionnaire effectue les opérations suivantes : + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + L'algorithme de chiffrement des compartiments pour un compartiment Amazon S3 n'a pas été modifié. ### Implémenter le gestionnaire PreDelete Implémentez un `preDelete` gestionnaire, qui démarre avant les opérations de suppression pour toutes les cibles spécifiées dans le gestionnaire. Le `preDelete` gestionnaire effectue les opérations suivantes : + Pour une `AWS::S3::Bucket` ressource, le Hook ne sera accepté que si les conditions suivantes sont vraies : + Vérifie que les ressources conformes minimales requises existeront dans le compte après la suppression de la ressource. + Le montant minimum de ressources conformes requis est défini dans la configuration du Hook. ### Implémenter un gestionnaire Hook 1. Dans votre IDE, ouvrez le `handlers.py` fichier situé dans le `src` dossier. 1. Remplacez l'intégralité du contenu du `handlers.py` fichier par le code suivant. **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}") ``` Passez à la rubrique suivante [Enregistrer un Hook personnalisé avec CloudFormation](registering-hooks.md). # Enregistrer un Hook personnalisé avec CloudFormation Une fois que vous avez créé un Hook personnalisé, vous devez l' CloudFormation enregistrer pour pouvoir l'utiliser. Dans cette section, vous allez apprendre à empaqueter et à enregistrer votre Hook pour l'utiliser dans votre Compte AWS. ## Package d'un Hook (Java) Si vous avez développé votre Hook avec Java, utilisez Maven pour le packager. Dans le répertoire de votre projet Hook, exécutez la commande suivante pour créer votre Hook, exécuter des tests unitaires et empaqueter votre projet sous forme de `JAR` fichier que vous pouvez utiliser pour soumettre votre Hook au CloudFormation registre. ``` mvn clean package ``` ## Enregistrer un Hook personnalisé **Pour enregistrer un Hook** 1. (Facultatif) Configurez votre Région AWS nom par défaut sur`us-west-2`, en soumettant l'[https://docs.aws.amazon.com/cli/latest/reference/configure/](https://docs.aws.amazon.com/cli/latest/reference/configure/)opération. ``` $ 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. (Facultatif) La commande suivante crée et empaquette votre projet Hook sans l'enregistrer. ``` $ cfn submit --dry-run ``` 1. Enregistrez votre Hook en utilisant l'[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)opération CloudFormation CLI. ``` $ cfn submit --set-default ``` Cette commande renvoie la commande suivante. ``` {‘ProgressStatus’: ‘COMPLETE’} ``` *Résultats* : Vous avez enregistré votre Hook avec succès. ## Vérifier que les Hooks sont accessibles dans votre compte Vérifiez que votre Hook est disponible dans votre région Compte AWS et dans les régions auxquelles vous l'avez envoyé. 1. Pour vérifier votre Hook, utilisez la [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)commande pour répertorier le Hook que vous venez d'enregistrer et renvoyer une description sommaire de celui-ci. ``` $ aws cloudformation list-types ``` La commande renvoie le résultat suivant et vous montrera également les Hooks accessibles au public que vous pouvez activer dans votre région Compte AWS et dans votre région. ``` { "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. Récupérez le contenu `TypeArn` de la `list-type` sortie de votre Hook et enregistrez-le. ``` export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook ``` Pour savoir comment publier des Hooks destinés à un usage public, consultez[Hooks de publication destinés à un usage public](hooks-publishing.md). ### Configurer les Hooks Après avoir développé et enregistré votre Hook, vous pouvez le configurer dans votre Hook en le Compte AWS publiant dans le registre. + Pour configurer un Hook dans votre compte, utilisez l'[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html)opération. Cette opération active les propriétés du hook définies dans la section `properties` de schéma du hook. Dans l'exemple suivant, la `minBuckets` propriété est définie sur `1` dans la configuration. **Note** En activant les Hooks dans votre compte, vous autorisez un Hook à utiliser les autorisations définies par votre Compte AWS. CloudFormation supprime les autorisations non requises avant de transmettre vos autorisations au Hook. CloudFormation recommande aux clients ou aux utilisateurs de Hook de consulter les autorisations Hook et de connaître les autorisations auxquelles les Hooks sont autorisés avant d'activer Hooks dans votre compte. Spécifiez les données de configuration de votre extension Hook enregistrée dans le même compte et Région 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 ``` **Important** Pour permettre à votre Hook d'inspecter de manière proactive la configuration de votre stack, vous devez définir le `HookInvocationStatus` to `ENABLED` dans la `HookConfiguration` section, une fois que le Hook a été enregistré et activé dans votre compte. ## Accès AWS APIs dans les gestionnaires Si votre Hooks utilise une AWS API dans l'un de ses gestionnaires, le CFN-CLI crée automatiquement un modèle de rôle d'exécution IAM,. `hook-role.yaml` Le `hook-role.yaml` modèle est basé sur les autorisations spécifiées pour chaque gestionnaire dans la section du gestionnaire du schéma Hook. Si l'`--role-arn`indicateur n'est pas utilisé pendant l'[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)opération, le rôle de cette pile sera provisionné et utilisé comme rôle d'exécution du Hook. Pour plus d'informations, consultez la section [Accès à AWS APIs partir d'un type de ressource.](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole) ### modèle hook-role.yaml **Note** Si vous choisissez de créer votre propre rôle d'exécution, nous vous recommandons vivement de suivre le principe du moindre privilège en autorisant uniquement le listage `hooks.cloudformation.amazonaws.com` et`resources.cloudformation.amazonaws.com`. Le modèle suivant utilise les autorisations IAM, Amazon S3 et 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 ``` # Tester un Hook personnalisé dans votre Compte AWS Maintenant que vous avez codé les fonctions de votre gestionnaire correspondant à un point d'invocation, il est temps de tester votre Hook personnalisé sur une CloudFormation pile. Le mode d'échec du Hook est défini sur `FAIL` si le CloudFormation modèle n'a pas approvisionné un compartiment S3 avec les éléments suivants : + Le chiffrement du compartiment Amazon S3 est défini. + La clé du compartiment Amazon S3 est activée pour le compartiment. + L'algorithme de chiffrement défini pour le compartiment Amazon S3 est le bon algorithme requis. + L'identifiant de la AWS Key Management Service clé est défini. Dans l'exemple suivant, créez un modèle appelé `my-failed-bucket-stack.yml` avec le nom de pile `my-hook-stack` qui échoue à la configuration de la pile et s'arrête avant la mise à disposition des ressources. ## Tester les Hooks en provisionnant une pile ### Exemple 1 : pour provisionner une pile **Provisionner une pile non conforme** 1. Créez un modèle qui spécifie un compartiment S3. Par exemple, `my-failed-bucket-stack.yml`. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: S3Bucket: Type: AWS::S3::Bucket Properties: {} ``` 1. Créez une pile et spécifiez votre modèle dans le AWS Command Line Interface (AWS CLI). Dans l'exemple suivant, spécifiez le nom de la pile comme `my-hook-stack` et le nom du modèle comme`my-failed-bucket-stack.yml`. ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://my-failed-bucket-stack.yml ``` 1. (Facultatif) Consultez la progression de votre pile en spécifiant le nom de votre pile. Dans l'exemple suivant, spécifiez le nom de la pile`my-hook-stack`. ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` Utilisez cette `describe-stack-events` opération pour voir l'échec du Hook lors de la création du bucket. Voici un exemple de sortie de la commande. ``` { "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" }, ... ] } ``` *Résultats* : L'invocation de Hook a échoué dans la configuration de la pile et a empêché le provisionnement de la ressource. **Utiliser un CloudFormation modèle pour réussir la validation Hook** 1. Pour créer une pile et passer la validation Hook, mettez à jour le modèle afin que votre ressource utilise un compartiment S3 chiffré. Cet exemple utilise le modèle`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 ``` **Note** Les hooks ne seront pas invoqués pour les ressources ignorées. 1. Créez une pile et spécifiez votre modèle. Dans cet exemple, le nom de la pile est`my-encrypted-bucket-stack`. ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://my-encrypted-bucket-stack.yml \ ``` 1. (Facultatif) Consultez la progression de votre pile en spécifiant le nom de la pile. ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` Utilisez la `describe-stack-events` commande pour afficher la réponse. Voici un exemple de la commande `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" }, ... ] } ``` *Résultats : la* pile a été créée CloudFormation avec succès. La logique du Hook a vérifié que la `AWS::S3::Bucket` ressource contenait un chiffrement côté serveur avant de la provisionner. ### Exemple 2 : pour provisionner une pile **Provisionner une pile non conforme** 1. Créez un modèle qui spécifie un compartiment S3. Par exemple `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. Créez une pile et spécifiez votre modèle dans le AWS CLI. Dans l'exemple suivant, spécifiez le nom de la pile comme `my-hook-stack` et le nom du modèle comme`aes256-bucket.yml`. ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://aes256-bucket.yml ``` 1. (Facultatif) Consultez la progression de votre pile en spécifiant le nom de votre pile. Dans l'exemple suivant, spécifiez le nom de la pile`my-hook-stack`. ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` Utilisez cette `describe-stack-events` opération pour voir l'échec du Hook lors de la création du bucket. Voici un exemple de sortie de la commande. ``` { "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" }, ... ] } ``` *Résultats* : L'invocation de Hook a échoué dans la configuration de la pile et a empêché le provisionnement de la ressource. La pile a échoué en raison d'une configuration incorrecte du chiffrement du compartiment S3. La configuration de type Hook est requise `aws:kms` lors de l'utilisation de ce bucket`AES256`. **Utiliser un CloudFormation modèle pour réussir la validation Hook** 1. Pour créer une pile et passer la validation Hook, mettez à jour le modèle afin que votre ressource utilise un compartiment S3 chiffré. Cet exemple utilise le modèle`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 ``` **Note** Les hooks ne seront pas invoqués pour les ressources ignorées. 1. Créez une pile et spécifiez votre modèle. Dans cet exemple, le nom de la pile est`my-encrypted-bucket-stack`. ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://kms-bucket-and-queue.yml ``` 1. (Facultatif) Consultez la progression de votre pile en spécifiant le nom de la pile. ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` Utilisez la `describe-stack-events` commande pour afficher la réponse. Voici un exemple de la commande `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" }, ... ] } ``` *Résultats : la* pile a été créée CloudFormation avec succès. La logique du Hook a vérifié que la `AWS::S3::Bucket` ressource contenait un chiffrement côté serveur avant de la provisionner. # Mettre à jour un Hook personnalisé La mise à jour d'un Hook personnalisé permet de rendre les révisions du Hook disponibles dans le CloudFormation registre. Pour mettre à jour un Hook personnalisé, soumettez vos révisions au CloudFormation registre via l'[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)opération CloudFormation CLI. ``` $ cfn submit ``` Pour spécifier la version par défaut de votre Hook dans votre compte, utilisez la [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)commande et spécifiez le type, le nom du type et l'ID de version. ``` $ aws cloudformation set-type-default-version \ --type HOOK \ --type-name MyCompany::Testing::MyTestHook \ --version-id 00000003 ``` Pour récupérer des informations sur les versions d'un Hook, utilisez [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" ``` # Désenregistrer un Hook personnalisé du registre CloudFormation Le désenregistrement d'un Hook personnalisé marque l'extension ou la version de l'extension comme étant `DEPRECATED` dans le CloudFormation registre, ce qui la met hors service. Une fois obsolète, le Hook personnalisé ne peut pas être utilisé dans une CloudFormation opération. **Note** Avant de désenregistrer le Hook, vous devez désenregistrer individuellement toutes les versions actives précédentes de cette extension. Pour de plus amples informations, veuillez consulter [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html). Pour désenregistrer un Hook, utilisez l'[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html)opération et spécifiez l'ARN de votre Hook. ``` $ aws cloudformation deregister-type \ --arn HOOK_TYPE_ARN ``` Cette commande ne produit pas de sortie. # Hooks de publication destinés à un usage public Pour développer un Hook tiers public, développez votre Hook en tant qu'extension privée. Ensuite, Région AWS dans chaque cas où vous souhaitez rendre l'extension accessible au public : 1. Enregistrez votre Hook en tant qu'extension privée dans le CloudFormation registre. 1. Testez votre Hook pour vous assurer qu'il répond à toutes les exigences nécessaires pour être publié dans le CloudFormation registre. 1. Publiez votre Hook dans le CloudFormation registre. **Note** Avant de publier une extension dans une région donnée, vous devez d'abord vous enregistrer en tant qu'éditeur d'extensions dans cette région. Pour ce faire simultanément dans plusieurs régions, reportez-vous à la section [Publication d'extensions dans plusieurs régions à l'aide StackSets](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension-stacksets.html) du *guide de l'utilisateur de la CloudFormation CLI*. Une fois que vous avez développé et enregistré votre Hook, vous pouvez le rendre accessible au public en CloudFormation le *publiant* CloudFormation dans le registre, sous la forme d'une extension publique tierce. Les Hooks tiers publics vous permettent de proposer aux CloudFormation utilisateurs d'inspecter de manière proactive la configuration des AWS ressources avant le provisionnement. Comme pour les Hooks privés, les Hooks publics sont traités de la même manière que tout Hook publié par AWS within CloudFormation. Les hooks publiés dans le registre sont visibles par tous les CloudFormation utilisateurs dans le registre Régions AWS dans lequel ils sont publiés. Les utilisateurs peuvent ensuite *activer* votre extension dans leur compte, ce qui la rend disponible pour utilisation dans leurs modèles. Pour plus d'informations, consultez la section [Utiliser des extensions publiques tierces depuis le CloudFormation registre](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html) dans le *Guide de CloudFormation l'utilisateur*. # Tester un Hook personnalisé pour un usage public Afin de publier votre Hook personnalisé enregistré, il doit satisfaire à toutes les exigences de test définies pour celui-ci. Voici une liste des exigences requises avant de publier votre Hook personnalisé en tant qu'extension tierce. Chaque gestionnaire et chaque cible sont testés deux fois. Une fois pour `SUCCESS` et une fois pour`FAILED`. + Pour le cas de `SUCCESS` réponse : + Le statut doit être`SUCCESS`. + Ne doit pas renvoyer de code d'erreur. + Le délai de rappel doit être fixé à `0` quelques secondes, s'il est spécifié. + Pour le cas de `FAILED` réponse : + Le statut doit être`FAILED`. + Doit renvoyer un code d'erreur. + Il doit y avoir un message en réponse. + Le délai de rappel doit être fixé à `0` quelques secondes, s'il est spécifié. + Pour le cas de `IN_PROGRESS` réponse : + Ne doit pas renvoyer de code d'erreur. + `Result`le champ ne doit pas être défini en réponse. # Spécification des données d'entrée à utiliser dans les tests de contrats Par défaut, il CloudFormation effectue des tests de contrat en utilisant les propriétés d'entrée générées à partir des modèles que vous définissez dans votre schéma Hook. Cependant, la plupart des Hooks sont suffisamment complexes pour que les propriétés d'entrée permettant de précréer ou de prémettre à jour les piles de provisionnement nécessitent une compréhension de la ressource provisionnée. Pour résoudre ce problème, vous pouvez spécifier l'entrée qu'il CloudFormation utilise lors de ses tests de contrat. CloudFormation vous propose deux méthodes pour spécifier les données d'entrée à utiliser lors de tests contractuels : + Remplace le fichier L'utilisation d'un `overrides` fichier permet de spécifier des données d'entrée pour certaines propriétés spécifiques CloudFormation à utiliser pendant les tests `preUpdate` et `preCreate` les tests `preDelete` opérationnels. + Fichiers d'entrée Vous pouvez également utiliser plusieurs `input` fichiers pour spécifier les données d'entrée des tests de contrat si : + Vous souhaitez ou devez spécifier des données d'entrée différentes pour les opérations de création, de mise à jour et de suppression, ou des données non valides pour les tests. + Vous souhaitez spécifier plusieurs ensembles de données d'entrée différents. ## Spécification des données d'entrée à l'aide d'un fichier de remplacement Voici un exemple de données d'entrée de Amazon S3 Hook utilisant le `overrides` fichier. ``` { "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" } } } } ``` ## Spécification des données d'entrée à l'aide de fichiers d'entrée Utilisez `input` des fichiers pour spécifier les différents types de données d'entrée CloudFormation à utiliser : `preCreate` entrée, `preUpdate` entrée et entrée non valide. Chaque type de données est spécifié dans un fichier distinct. Vous pouvez également spécifier plusieurs ensembles de données d'entrée pour les tests de contrat. Pour spécifier `input` les fichiers CloudFormation à utiliser dans les tests de contrats, ajoutez un `inputs` dossier dans le répertoire racine de votre projet Hooks. Ajoutez ensuite vos fichiers d'entrée. Spécifiez le type de données d'entrée qu'un fichier contient en utilisant les conventions de dénomination suivantes, où **n**est un entier : + `inputs_n_pre_create.json`: utilisez des fichiers dotés de `preCreate` gestionnaires pour spécifier les entrées nécessaires à la création de la ressource. + `inputs_n_pre_update.json`: utilisez des fichiers dotés de `preUpdate` gestionnaires pour spécifier les entrées nécessaires à la mise à jour de la ressource. + `inputs_n_pre_delete.json`: utilisez des fichiers dotés de `preDelete` gestionnaires pour spécifier les entrées permettant de supprimer la ressource. + `inputs_n_invalid.json`: pour spécifier des entrées non valides à tester. Pour spécifier plusieurs ensembles de données d'entrée pour les tests de contrat, incrémentez le nombre entier dans les noms de fichiers afin de classer vos ensembles de données d'entrée. Par exemple, votre premier ensemble de fichiers d'entrée doit être nommé `inputs_1_pre_create.json``inputs_1_pre_update.json`, et`inputs_1_pre_invalid.json`. Votre prochain ensemble serait nommé`inputs_2_pre_create.json`, et `inputs_2_pre_update.json``inputs_2_pre_invalid.json`, et ainsi de suite. Chaque fichier d'entrée est un fichier JSON contenant uniquement les propriétés des ressources à utiliser lors des tests. Voici un exemple de répertoire permettant de Amazon S3 spécifier des `inputs` données d'entrée à l'aide de fichiers d'entrée. `inputs_1_pre_create.json` Voici un exemple de test `inputs_1_pre_create.json` contractuel. ``` { "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` Voici un exemple de test `inputs_1_pre_update.json` contractuel. ``` { "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` Voici un exemple de test `inputs_1_invalid.json` contractuel. ``` { "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` Voici un exemple de test `inputs_1_invalid_pre_update.json` contractuel. ``` { "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" } } } ``` Pour plus d'informations, veuillez consulter la rubrique [Publier des extensions pour les rendre accessibles au public](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension.html) dans le *Guide de l'utilisateur de la CLI CloudFormation *. # Référence syntaxique du schéma pour les CloudFormation Hooks Cette section décrit la syntaxe du schéma que vous utilisez pour développer des CloudFormation Hooks. Un Hook inclut une spécification Hook représentée par un schéma JSON et des gestionnaires Hook. La première étape de la création d'un Hook personnalisé consiste à modéliser un schéma qui définit le Hook, ses propriétés et ses attributs. Lorsque vous initialisez un projet Hook personnalisé à l'aide de la [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)commande CloudFormation CLI, un fichier de schéma Hook est créé pour vous. Utilisez ce fichier de schéma comme point de départ pour définir la forme et la sémantique de votre Hook personnalisé. ## Syntaxe du schéma Le schéma suivant représente la structure d'un Hook. ``` { "typeName": "string", "description": "string", "sourceUrl": "string", "documentationUrl": "string", "definitions": { "definitionName": { . . . } }, "typeConfiguration": { "properties": { "propertyName": { "description": "string", "type": "string", . . . }, }, "required": [ "propertyName" . . . ], "additionalProperties": false }, "handlers": { "preCreate": { "targetNames": [ ], "permissions": [ ] }, "preUpdate": { "targetNames": [ ], "permissions": [ ] }, "preDelete": { "targetNames": [ ], "permissions": [ ] } }, "additionalProperties": false } ``` `typeName` Le nom unique de votre Hook. Spécifie un espace de noms en trois parties pour votre Hook, avec un modèle recommandé de. `Organization::Service::Hook` Les espaces de noms d'organisation suivants sont réservés et ne peuvent pas être utilisés dans les noms de vos types de Hook : + `Alexa` + `AMZN` + `Amazon` + `ASK` + `AWS` + `Custom` + `Dev` *Obligatoire* : oui *Modèle* : `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *Minimum *: `10` *Maximum *: `196` `description` Brève description du Hook affiché dans la CloudFormation console. *Obligatoire* : oui `sourceUrl` L'URL du code source du Hook, s'il est public. *Obligatoire* : non *Maximum *: `4096` `documentationUrl` URL d'une page fournissant une documentation détaillée pour le Hook. *Obligatoire* : oui *Modèle* : `^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$` *Maximum *: `4096` Bien que le schéma Hook doive inclure des descriptions de propriétés complètes et précises, vous pouvez utiliser la `documentationURL` propriété pour fournir aux utilisateurs plus de détails, notamment des exemples, des cas d'utilisation et d'autres informations détaillées. `definitions` Utilisez le `definitions` bloc pour fournir des schémas de propriétés Hook partagés. Il est considéré comme une bonne pratique d'utiliser cette `definitions` section pour définir des éléments de schéma qui peuvent être utilisés à plusieurs points de votre schéma de type Hook. Vous pouvez ensuite utiliser un pointeur JSON pour référencer cet élément aux endroits appropriés dans votre schéma de type Hook. *Obligatoire* : non `typeConfiguration` Définition des données de configuration d'un Hook. *Obligatoire* : oui `properties` Les propriétés du Hook. Toutes les propriétés d'un Hook doivent être exprimées dans le schéma. Alignez les propriétés du schéma Hook avec les propriétés de configuration du type Hook. Les propriétés imbriquées ne sont pas autorisées. Définissez plutôt les propriétés imbriquées de l'`definitions`élément et utilisez un `$ref` pointeur pour les référencer dans la propriété souhaitée. Les propriétés suivantes sont actuellement prises en charge : + `default`— La valeur par défaut de la propriété. + `description`— Une description de la propriété. + `pattern`— Un modèle regex utilisé pour valider l'entrée. + `type`— Le type de propriété accepté. `additionalProperties` `additionalProperties` doit être défini sur `false`. Toutes les propriétés d'un Hook doivent être exprimées dans le schéma : les entrées arbitraires ne sont pas autorisées. *Obligatoire* : oui *Valeurs valides* : `false` `handlers` Les gestionnaires spécifient les opérations qui peuvent initier le Hook défini dans le schéma, telles que les points d'invocation du Hook. Par exemple, un `preUpdate` gestionnaire est invoqué avant les opérations de mise à jour pour toutes les cibles spécifiées dans le gestionnaire. *Valeurs valides* : `preCreate` \$1 `preUpdate` \$1 `preDelete` Au moins une valeur doit être spécifiée pour le gestionnaire. Les opérations de pile qui se traduisent par le statut de `UpdateCleanup` n'invoquent pas de Hook. Par exemple, dans les deux scénarios suivants, le `preDelete` gestionnaire du Hook n'est pas invoqué : + la pile est mise à jour après la suppression d'une ressource du modèle. + une ressource dont le type de mise à jour est [remplacé](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement) est supprimée. `targetNames` Un tableau de chaînes de noms de types que Hook cible. Par exemple, si un `preCreate` gestionnaire a une `AWS::S3::Bucket` cible, le Hook s'exécute pour les compartiments Amazon S3 pendant la phase de préapprovisionnement. + `TargetName` Spécifiez au moins un nom de cible pour chaque gestionnaire implémenté. *Modèle* : `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *Minimum *: `1` *Obligatoire* : oui **Avertissement** Les références dynamiques SSM SecureString et Secrets Manager ne sont pas résolues avant d'être transmises à Hooks. `permissions` Un tableau de chaînes qui spécifie les AWS autorisations nécessaires pour appeler le gestionnaire. *Obligatoire* : oui `additionalProperties` `additionalProperties` doit être défini sur `false`. Toutes les propriétés d'un Hook doivent être exprimées dans le schéma : les entrées arbitraires ne sont pas autorisées. *Obligatoire* : oui *Valeurs valides* : `false` ## Exemples de schémas Hooks **Exemple 1** Les procédures pas à pas pour Java et Python utilisent l'exemple de code suivant. Voici un exemple de structure pour un Hook appelé`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 } ``` **Exemple 2** L'exemple suivant est un schéma qui utilise le `STACK` et `CHANGE_SET` pour `targetNames` pour cibler un modèle de pile et une opération d'ensemble de modifications. ``` { "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 } ```