Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Desarrollo de Hooks personalizados mediante la CloudFormation CLI Esta sección es para los clientes que desean desarrollar Hooks personalizados y registrarlos en el CloudFormation registro. Proporciona una descripción general de la estructura de CloudFormation Hooks y guías para desarrollar, registrar, probar, administrar y publicar tus propios Hooks con Python o Java. Hay tres pasos principales para desarrollar un Hook personalizado: 1. **Iniciar** Para desarrollar Hooks personalizados, debe configurar y usar la CloudFormation CLI. Para iniciar un proyecto de Hook y sus archivos necesarios, utilice el [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)comando CloudFormation CLI y especifique que desea crear un Hook. Para obtener más información, consulte [Iniciar un proyecto CloudFormation Hooks personalizado](hooks-init.md). 1. **Model** Para modelar, crear y validar tu esquema de Hook, define el Hook, sus propiedades y sus atributos. La CloudFormation CLI crea funciones de controlador vacías que corresponden a un punto de invocación de Hook específico. Agrega tu propia lógica a estos controladores para controlar lo que ocurre durante la invocación de Hook en cada etapa del ciclo de vida objetivo. Para obtener más información, consulte [Modelado de CloudFormation ganchos personalizados](hooks-model.md). 1. **Regístrese** Para registrar un Hook, envía tu Hook para que se registre como una extensión privada o pública de terceros. Registra tu Hook con la `[submit](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html)` operación. Para obtener más información, consulte [Registrar un Hook personalizado con CloudFormation](registering-hooks.md). Las siguientes tareas están asociadas al registro de tu Hook: 1. *Publicar*: los Hooks se publican en el registro. 1. *Configurar*: los ganchos se configuran cuando la configuración de tipos se invoca contra las pilas. **nota** Los ganchos se agotarán después de 30 segundos y se volverán a intentar hasta 3 veces. Para obtener más información, consulte [Límites de tiempo de espera y reintentos](hooks-concepts.md#hook-timeout-and-retry-limits). **Topics** + [Requisitos previos](hooks-prerequisites.md) + [Iniciar un proyecto de Hooks](hooks-init.md) + [Ganchos de modelado](hooks-model.md) + [Registrar ganchos](registering-hooks.md) + [Probando ganchos](testing-hooks.md) + [Actualización de Hooks](updating-registered-hook.md) + [Anular el registro de Hooks](deregistering-hooks.md) + [Ganchos de publicación](hooks-publishing.md) + [Sintaxis del esquema](hooks-schema.md) # Requisitos previos para desarrollar Hooks personalizados CloudFormation Puedes desarrollar un Hook personalizado con Java o Python. Los siguientes son los requisitos previos para desarrollar Hooks personalizados: **Requisitos previos de Java** + [Apache Maven](https://maven.apache.org/install.html) + [JDK 17](https://www.oracle.com/java/technologies/downloads/#java17) **nota** Si pretende utilizar la [interfaz de línea de CloudFormation comandos (CLI)](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) para iniciar un proyecto de Hooks para Java, también debe instalar Python 3.8 o una versión posterior. El complemento de Java para la CloudFormation CLI se puede instalar a través `pip` del administrador de paquetes de Python, que está distribuido con Python. Para implementar los controladores de Hook en su proyecto de Java Hooks, puede descargar los archivos de ejemplo del controlador de [Java Hook](samples/java-handlers.zip). **Requisitos previos de Python** + [Python versión 3.8](https://www.python.org/downloads/) o posterior. Para implementar los controladores de Hook para tu proyecto de Python Hooks, puedes descargar los archivos de [ejemplo del controlador de Python Hook](samples/python-handlers.zip). ## Permisos para desarrollar Hooks Además de los permisos CloudFormation `Create``Update`, y `Delete` stack, necesitarás acceder a las siguientes AWS CloudFormation operaciones. El acceso a estas operaciones se gestiona mediante la CloudFormation política de su función de 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) Para obtener más información, consulte [Otorgue permisos de IAM para Hooks CloudFormation](grant-iam-permissions-for-hooks.md). ## Configura un entorno de desarrollo para Hooks Para desarrollar Hooks, debes estar familiarizado con [CloudFormation las plantillas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html) y con Python o Java. **Para instalar la CloudFormation CLI y los complementos asociados:** 1. Instale la CloudFormation CLI con `pip` el administrador de paquetes de Python. ``` pip3 install cloudformation-cli ``` 1. Instale el complemento Python o Java para la CloudFormation CLI. ------ #### [ Python ] ``` pip3 install cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install cloudformation-cli-java-plugin ``` ------ Para actualizar la CloudFormation CLI y el complemento, puede usar la opción de actualización. ------ #### [ Python ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-python-plugin ``` ------ #### [ Java ] ``` pip3 install --upgrade cloudformation-cli cloudformation-cli-java-plugin ``` ------ # Iniciar un proyecto CloudFormation Hooks personalizado El primer paso para crear tu proyecto Hooks personalizado es iniciar el proyecto. Puede usar el `init` comando CloudFormation CLI para iniciar su proyecto Hooks personalizado. El `init` comando lanza un asistente que le guía a través de la configuración del proyecto, incluido un archivo de esquema de Hooks. Usa este archivo de esquema como punto de partida para definir la forma y la semántica de tus Hooks. Para obtener más información, consulte [Sintaxis del esquema](hooks-schema.md). **Para iniciar un proyecto de Hook:** 1. Crea un directorio para el proyecto. ``` mkdir ~/mycompany-testing-mytesthook ``` 1. Vaya al nuevo directorio. ``` cd ~/mycompany-testing-mytesthook ``` 1. Utilice el `init` comando CloudFormation CLI para iniciar el proyecto. ``` cfn init ``` El comando devuelve el resultado siguiente. ``` Initializing new project ``` 1. El `init` comando lanza un asistente que le guía a través de la configuración del proyecto. Cuando se le solicite, introduzca `h` para especificar un proyecto de Hooks. ``` Do you want to develop a new resource(r) a module(m) or a hook(h)? ``` ``` h ``` 1. Introduzca un nombre para el tipo de Hook. ``` What's the name of your hook type? (Organization::Service::Hook) ``` ``` MyCompany::Testing::MyTestHook ``` 1. Si solo hay un complemento de idioma instalado, se selecciona de forma predeterminada. Si hay más de un complemento de idioma instalado, puede elegir el idioma que desee. Introduce una selección numérica para el idioma de tu elección. ``` Select a language for code generation: [1] java [2] python38 [3] python39 (enter an integer): ``` 1. Configure el empaquetado en función del idioma de desarrollo elegido. ------ #### [ Python ] (*Opcional*) Elija Docker para el empaquetado independiente de la plataforma. Si bien Docker no es obligatorio, es muy recomendable para facilitar el empaquetado. ``` Use docker for platform-independent packaging (Y/n)? This is highly recommended unless you are experienced with cross-platform Python packaging. ``` ------ #### [ Java ] Establezca el nombre del paquete de Java y elija un modelo de generación de código. Puede usar el nombre de paquete predeterminado o crear uno nuevo. ``` Enter a package name (empty for default 'com.mycompany.testing.mytesthook'): ``` ``` Choose codegen model - 1 (default) or 2 (guided-aws): ``` ------ *Resultados*: Has iniciado correctamente el proyecto y has generado los archivos necesarios para desarrollar un Hook. El siguiente es un ejemplo de los directorios y archivos que componen un proyecto de Hooks para 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 ``` **nota** Los archivos del `src` directorio se crean en función de la selección de idioma. Hay algunos comentarios y ejemplos útiles en los archivos generados. Algunos archivos, por ejemplo`models.py`, se actualizan automáticamente en un paso posterior al ejecutar el `generate` comando para añadir código de tiempo de ejecución a los controladores. # Modelado de CloudFormation ganchos personalizados Modelar CloudFormation Hooks personalizados implica crear un esquema que defina el Hook, sus propiedades y sus atributos. Al crear un proyecto Hook personalizado con el `cfn init` comando, se crea un ejemplo de esquema de Hook como un archivo de texto con formato JSON,. `hook-name.json` Los puntos de invocación y las acciones objetivo especifican el punto exacto en el que se invoca el Hook. *Los controladores de ganchos alojan* una lógica personalizada ejecutable para estos puntos. Por ejemplo, una acción objetivo de la `CREATE` operación utiliza un `preCreate` controlador. El código escrito en el controlador se invocará cuando los objetivos y servicios de Hook realicen una acción coincidente. Los *objetivos de los ganchos* son el destino en el que se invocan los ganchos. Puede especificar objetivos como recursos CloudFormation públicos, recursos privados o recursos personalizados. Los Hooks admiten un número ilimitado de objetivos de Hook. El esquema contiene los permisos necesarios para el Hook. La creación del Hook requiere que especifiques los permisos para cada controlador de Hook. CloudFormation anima a los autores a redactar políticas que sigan el consejo de seguridad estándar de conceder el *mínimo de privilegios* o conceder solo los permisos necesarios para realizar una tarea. Determine lo que deben hacer los usuarios (y las funciones) y, a continuación, elabore políticas que les permitan realizar *únicamente* esas tareas para las operaciones de Hook. CloudFormation usa estos permisos para analizar los permisos proporcionados por los usuarios de Hook. Estos permisos se transfieren a Hook. Los controladores de Hook utilizan estos permisos para acceder a AWS los recursos. Puedes usar el siguiente archivo de esquema como punto de partida para definir tu Hook. Usa el esquema Hook para especificar qué controladores deseas implementar. Si decides no implementar un controlador específico, elimínalo de la sección de controladores del esquema de Hook. Para obtener más información sobre el esquema, consulte. [Sintaxis del esquema](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** + [Modelado de CloudFormation Hooks personalizados con Java](hooks-model-java.md) + [Modelado de CloudFormation Hooks personalizados con Python](hooks-model-python.md) # Modelado de CloudFormation Hooks personalizados con Java Modelar CloudFormation Hooks personalizados implica crear un esquema que defina el Hook, sus propiedades y sus atributos. En este tutorial, se explica cómo modelar Hooks personalizados con Java. ## Paso 1: Añadir las dependencias del proyecto Los proyectos de Hooks basados en Java se basan en el `pom.xml` archivo de Maven como dependencia. Expanda la siguiente sección y copie el código fuente en el `pom.xml` archivo que se encuentra en la raíz del proyecto. ### Enganche las dependencias del proyecto (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 ``` ## Paso 2: Genera el paquete del proyecto Hook Genera tu paquete de proyectos Hook. La CloudFormation CLI crea funciones de controlador vacías que corresponden a acciones de Hook específicas en el ciclo de vida objetivo, tal como se define en la especificación de Hook. ``` cfn generate ``` El comando devuelve el resultado siguiente. ``` Generated files for MyCompany::Testing::MyTestHook ``` **nota** Asegúrese de que sus tiempos de ejecución de Lambda eviten el uso up-to-date de una versión obsoleta. Para obtener más información, consulte [Actualización de los tiempos de ejecución de Lambda para tipos de recursos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html) y Hooks. ## Paso 3: Añadir controladores de Hook Agrega tu propio código de tiempo de ejecución del controlador Hook a los controladores que decidas implementar. Por ejemplo, puedes añadir el siguiente código para el registro. ``` logger.log("Internal testing Hook triggered for target: " + request.getHookContext().getTargetName()); ``` La CloudFormation CLI genera objetos Java simples y antiguos (Java POJO). Los siguientes son ejemplos de resultados generados a 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; } ``` Con lo POJOs generado, ahora puedes escribir los controladores que realmente implementan la funcionalidad del Hook. Para este ejemplo, implementa el punto de `preUpdate` invocación `preCreate` y para los controladores. ## Paso 4: Implementa los controladores Hook **Topics** + [Codificación del creador de clientes de API](#java-code-api-client-builder) + [Codificando el creador de solicitudes de API](#code-the-api-request-maker) + [Implementación del código auxiliar](#implement-helper-code) + [Implementación del controlador base](#implement-base-hook-handler) + [Implementación del `preCreate` controlador](#implementing-precreate-handler) + [Codificación del `preCreate` controlador](#coding-the-precreate-handler) + [Actualización de la `preCreate` prueba](#updating-the-precreate-handler) + [Implementación del `preUpdate` controlador](#implementing-preupdate-handler) + [Codificando el `preUpdate` controlador](#coding-preupdate-handler) + [Actualización de la `preUpdate` prueba](#update-the-preupdate-handler) + [Implementación del `preDelete` controlador](#implement-the-predelete-hander) + [Codificación del `preDelete` controlador](#code-the-predelete-handler) + [Actualización del `preDelete` controlador](#update-the-predelete-handler) ### Codificación del creador de clientes de API 1. En su IDE, abra el `ClientBuilder.java` archivo que se encuentra en la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `ClientBuilder.java` archivo por el siguiente código. **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(); } } ``` ### Codificando el creador de solicitudes de API 1. En su IDE, abra el `Translator.java` archivo que se encuentra en la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `Translator.java` archivo por el siguiente código. **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(); } } ``` ### Implementación del código auxiliar 1. En su IDE, abra el `AbstractTestBase.java` archivo, ubicado en la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `AbstractTestBase.java` archivo por el siguiente código. **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 ) ); } } ``` ### Implementación del controlador base 1. En su IDE, abra el `BaseHookHandlerStd.java` archivo, ubicado en la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `BaseHookHandlerStd.java` archivo por el siguiente código. **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); } } } ``` ### Implementación del `preCreate` controlador El `preCreate` controlador verifica la configuración de cifrado del lado del servidor para un recurso o. `AWS::S3::Bucket` `AWS::SQS::Queue` + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente: + Se ha establecido el cifrado del bucket de Amazon S3. + La clave de bucket de Amazon S3 está habilitada para el bucket. + El algoritmo de cifrado establecido para el bucket de Amazon S3 es el algoritmo correcto que se requiere. + El ID de AWS Key Management Service clave está establecido. + En el caso `AWS::SQS::Queue` de un recurso, el Hook solo pasará si se cumple lo siguiente: + El ID de la AWS Key Management Service clave está establecido. ### Codificación del `preCreate` controlador 1. En su IDE, abra el `PreCreateHookHandler.java` archivo, ubicado en la `src/main/java/software/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreCreateHookHandler.java` archivo por el siguiente código. ``` 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(); } } ``` ### Actualización de la `preCreate` prueba 1. En su IDE, abra el `PreCreateHandlerTest.java` archivo que se encuentra en la `src/test/java/software/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreCreateHandlerTest.java` archivo por el siguiente código. ``` 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(); } } ``` ### Implementación del `preUpdate` controlador Implemente un `preUpdate` controlador, que se inicie antes de las operaciones de actualización para todos los objetivos especificados en el controlador. El `preUpdate` controlador logra lo siguiente: + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente: + El algoritmo de cifrado de buckets de un bucket de Amazon S3 no se ha modificado. ### Codificando el `preUpdate` controlador 1. En su IDE, abra el `PreUpdateHookHandler.java` archivo, ubicado en la `src/main/java/software/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreUpdateHookHandler.java` archivo por el siguiente código. ``` 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(); } } ``` ### Actualización de la `preUpdate` prueba 1. En su IDE, abra el `PreUpdateHandlerTest.java` archivo de la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreUpdateHandlerTest.java` archivo por el siguiente código. ``` 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(); } } ``` ### Implementación del `preDelete` controlador Implemente un `preDelete` controlador, que se inicie antes de las operaciones de eliminación para todos los objetivos especificados en el controlador. El `preDelete` controlador logra lo siguiente: + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente: + Verifica que los recursos de quejas mínimos requeridos existan en la cuenta después de eliminar el recurso. + La cantidad mínima requerida de recursos para quejas se establece en la configuración de tipos de Hook. ### Codificación del `preDelete` controlador 1. En su IDE, abra el `PreDeleteHookHandler.java` archivo de la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreDeleteHookHandler.java` archivo por el siguiente código. ``` 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); } } } ``` ### Actualización del `preDelete` controlador 1. En su IDE, abra el `PreDeleteHookHandler.java` archivo de la `src/main/java/com/mycompany/testing/mytesthook` carpeta. 1. Sustituya todo el contenido del `PreDeleteHookHandler.java` archivo por el siguiente código. ``` 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(); } } ``` # Modelado de CloudFormation Hooks personalizados con Python Modelar CloudFormation Hooks personalizados implica crear un esquema que defina el Hook, sus propiedades y sus atributos. Este tutorial te guía a través del modelado de Hooks personalizados con Python. ## Paso 1: Genera el paquete del proyecto Hook Genera tu paquete de proyectos Hook. La CloudFormation CLI crea funciones de controlador vacías que corresponden a acciones de Hook específicas en el ciclo de vida objetivo, tal como se define en la especificación de Hook. ``` cfn generate ``` El comando devuelve el resultado siguiente. ``` Generated files for MyCompany::Testing::MyTestHook ``` **nota** Asegúrese de que sus tiempos de ejecución de Lambda eviten el uso up-to-date de una versión obsoleta. Para obtener más información, consulte [Actualización de los tiempos de ejecución de Lambda para tipos de recursos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/runtime-update.html) y Hooks. ## Paso 2: Añadir controladores de Hook Agrega tu propio código de tiempo de ejecución del controlador Hook a los controladores que decidas implementar. Por ejemplo, puedes añadir el siguiente código para el registro. ``` LOG.setLevel(logging.INFO) LOG.info("Internal testing Hook triggered for target: " + request.hookContext.targetName); ``` La CloudFormation CLI genera el `src/models.py` archivo a partir de[Referencia a la sintaxis del esquema de la configuración del enlace](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 ``` ## Paso 3: Implementa los controladores de Hook Con las clases de datos de Python generadas, puedes escribir los controladores que realmente implementan la funcionalidad del Hook. En este ejemplo, implementarás los puntos de `preDelete` invocación y `preCreate``preUpdate`, para los controladores. **Topics** + [Implemente el controlador PreCreate](#model-hook-project-code-handler-python-precreate) + [Implemente el controlador PreUpdate](#model-hook-project-code-handler-python-preupdate) + [Implemente el controlador PreDelete](#model-hook-project-code-handler-python-predelete) + [Implementa un controlador de Hook](#model-hook-project-code-handler-python-hook-handler) ### Implemente el controlador PreCreate El `preCreate` controlador verifica la configuración de cifrado del lado del servidor para un recurso o. `AWS::S3::Bucket ` `AWS::SQS::Queue` + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente. + Se ha establecido el cifrado del bucket de Amazon S3. + La clave de bucket de Amazon S3 está habilitada para el bucket. + El algoritmo de cifrado establecido para el bucket de Amazon S3 es el algoritmo correcto que se requiere. + El ID de AWS Key Management Service clave está establecido. + En el caso `AWS::SQS::Queue` de un recurso, el Hook solo pasará si se cumple lo siguiente. + El ID de AWS Key Management Service clave está establecido. ### Implemente el controlador PreUpdate Implemente un `preUpdate` controlador, que se inicie antes de las operaciones de actualización para todos los objetivos especificados en el controlador. El `preUpdate` controlador logra lo siguiente: + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente: + El algoritmo de cifrado de buckets de un bucket de Amazon S3 no se ha modificado. ### Implemente el controlador PreDelete Implemente un `preDelete` controlador, que se inicie antes de las operaciones de eliminación para todos los objetivos especificados en el controlador. El `preDelete` controlador logra lo siguiente: + En el caso `AWS::S3::Bucket` de un recurso, el Hook solo pasará si se cumple lo siguiente: + Verifica que existan en la cuenta los recursos conformes mínimos requeridos después de eliminar el recurso. + La cantidad mínima de recursos compatibles requerida se establece en la configuración del Hook. ### Implementa un controlador de Hook 1. En su IDE, abra el `handlers.py` archivo, ubicado en la `src` carpeta. 1. Sustituya todo el contenido del `handlers.py` archivo por el siguiente código. **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}") ``` Continúe con el tema siguiente [Registrar un Hook personalizado con CloudFormation](registering-hooks.md). # Registrar un Hook personalizado con CloudFormation Una vez que hayas creado un Hook personalizado, tendrás que registrarlo CloudFormation para poder usarlo. En esta sección, aprenderás a empaquetar y registrar tu Hook para usarlo en tu Cuenta de AWS. ## Package a Hook (Java) Si has desarrollado tu Hook con Java, usa Maven para empaquetarlo. En el directorio de tu proyecto Hook, ejecuta el siguiente comando para compilar tu Hook, ejecuta pruebas unitarias y empaqueta tu proyecto como un `JAR` archivo que puedas usar para enviar tu Hook al CloudFormation registro. ``` mvn clean package ``` ## Registra un Hook personalizado **Para registrar un Hook** 1. (Opcional) Configure su Región de AWS nombre predeterminado como`us-west-2`, enviando la [https://docs.aws.amazon.com/cli/latest/reference/configure/](https://docs.aws.amazon.com/cli/latest/reference/configure/)operación. ``` $ 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. (Opcional) El siguiente comando compila y empaqueta tu proyecto de Hook sin registrarlo. ``` $ cfn submit --dry-run ``` 1. Registre su Hook mediante la [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)operación CloudFormation CLI. ``` $ cfn submit --set-default ``` El comando devuelve el siguiente comando: ``` {‘ProgressStatus’: ‘COMPLETE’} ``` *Resultados*: Has registrado correctamente tu Hook. ## Verificación de que los Hooks estén accesibles en tu cuenta Comprueba que tu Hook esté disponible en tu región Cuenta de AWS y en las regiones a las que lo has enviado. 1. Para verificar tu Hook, usa el [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)comando para enumerar tu Hook recién registrado y obtener una descripción resumida del mismo. ``` $ aws cloudformation list-types ``` El comando devuelve el siguiente resultado y también te mostrará los Hooks disponibles públicamente que puedes activar en tu región Cuenta de AWS y en tu región. ``` { "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. Recupera el `TypeArn` archivo de `list-type` salida de tu Hook y guárdalo. ``` export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook ``` Para obtener información sobre cómo publicar Hooks para uso público, consulte[Publicar ganchos para uso público](hooks-publishing.md). ### Configurar Hooks Una vez que hayas desarrollado y registrado tu Hook, puedes configurarlo en tu Hook Cuenta de AWS publicándolo en el registro. + Para configurar un Hook en tu cuenta, usa la [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html)operación. Esta operación habilita las propiedades del enlace que se definen en la sección `properties` del esquema del enlace. En el siguiente ejemplo, la `minBuckets` propiedad se establece `1` en la configuración. **nota** Al habilitar Hooks en tu cuenta, autorizas a un Hook a usar los permisos definidos por ti Cuenta de AWS. CloudFormation elimina los permisos no necesarios antes de pasarlos al Hook. CloudFormation recomienda a los clientes o usuarios de Hook que revisen los permisos de Hook y sepan qué permisos tienen los Hooks antes de habilitar los Hooks en su cuenta. Especifica los datos de configuración de tu extensión Hook registrada en la misma cuenta y Región de 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 ``` **importante** Para que tu Hook pueda inspeccionar de forma proactiva la configuración de tu pila, debes `HookInvocationStatus` establecer el valor `ENABLED` en la `HookConfiguration` sección una vez que el Hook se haya registrado y activado en tu cuenta. ## Acceder a AWS APIs los controladores Si sus Hooks utilizan una AWS API en alguno de sus controladores, la CFN-CLI crea automáticamente una plantilla de funciones de ejecución de IAM,. `hook-role.yaml` La `hook-role.yaml` plantilla se basa en los permisos especificados para cada controlador en la sección correspondiente al controlador del esquema Hook. Si el `--role-arn` indicador no se utiliza durante la [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)operación, la función de esta pila se aprovisionará y se utilizará como función de ejecución del Hook. Para obtener más información, consulta [Acceder AWS APIs desde un tipo de recurso](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole). ### plantilla hook-role.yaml **nota** Si decide crear su propio rol de ejecución, le recomendamos encarecidamente que practique el principio del mínimo privilegio y permita publicar solo y. `hooks.cloudformation.amazonaws.com` `resources.cloudformation.amazonaws.com` La siguiente plantilla utiliza los permisos de IAM, Amazon S3 y 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 ``` # Probando un Hook personalizado en tu Cuenta de AWS Ahora que has codificado las funciones de tu controlador que corresponden a un punto de invocación, es hora de probar tu Hook personalizado en una CloudFormation pila. El modo de fallo de Hook se establece `FAIL` si la CloudFormation plantilla no aprovisionó un bucket de S3 con lo siguiente: + Se ha establecido el cifrado del bucket de Amazon S3. + La clave de bucket de Amazon S3 está habilitada para el bucket. + El algoritmo de cifrado establecido para el bucket de Amazon S3 es el algoritmo correcto que se requiere. + El ID de AWS Key Management Service clave está establecido. En el siguiente ejemplo, cree una plantilla llamada `my-failed-bucket-stack.yml` con un nombre de pila `my-hook-stack` que no supere la configuración de la pila y se detenga antes de aprovisionar los recursos. ## Probar Hooks mediante el aprovisionamiento de una pila ### Ejemplo 1: Para aprovisionar una pila **Aprovisione una pila que no cumpla con las normas** 1. Cree una plantilla que especifique un bucket de S3. Por ejemplo, `my-failed-bucket-stack.yml`. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: S3Bucket: Type: AWS::S3::Bucket Properties: {} ``` 1. Cree una pila y especifique la plantilla en AWS Command Line Interface (AWS CLI). En el siguiente ejemplo, especifique el nombre de la pila como `my-hook-stack` y el nombre de la plantilla como`my-failed-bucket-stack.yml`. ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://my-failed-bucket-stack.yml ``` 1. (Opcional) Para ver el progreso de la pila, especifique el nombre de la pila. En el siguiente ejemplo, especifique el nombre de la pila`my-hook-stack`. ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` Utilice la `describe-stack-events` operación para ver el error de Hook al crear el depósito. A continuación, se muestra un ejemplo de la salida del comando . ``` { "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" }, ... ] } ``` *Resultados*: la invocación de Hook falló en la configuración de la pila e impidió el aprovisionamiento del recurso. **Usa una CloudFormation plantilla para pasar la validación de Hook** 1. Para crear una pila y pasar la validación de Hook, actualiza la plantilla para que tu recurso utilice un bucket de S3 cifrado. En este ejemplo, se utiliza la plantilla `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 ``` **nota** Los ganchos no se invocarán para los recursos omitidos. 1. Crea una pila y especifica tu plantilla. En este ejemplo, el nombre de la pila es`my-encrypted-bucket-stack`. ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://my-encrypted-bucket-stack.yml \ ``` 1. (Opcional) Para ver el progreso de la pila, especifique el nombre de la pila. ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` Usa el `describe-stack-events` comando para ver la respuesta. A continuación, se muestra un ejemplo del comando `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" }, ... ] } ``` *Resultados*: CloudFormation se creó correctamente la pila. La lógica de Hook verificó que el `AWS::S3::Bucket` recurso contenía cifrado del lado del servidor antes de aprovisionar el recurso. ### Ejemplo 2: Para aprovisionar una pila **Aprovisione una pila que no cumpla con las normas** 1. Cree una plantilla que especifique un bucket de S3. Por ejemplo, `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. Cree una pila y especifique la plantilla en AWS CLI. En el siguiente ejemplo, especifique el nombre de la pila como `my-hook-stack` y el nombre de la plantilla como`aes256-bucket.yml`. ``` $ aws cloudformation create-stack \ --stack-name my-hook-stack \ --template-body file://aes256-bucket.yml ``` 1. (Opcional) Para ver el progreso de la pila, especifique el nombre de la pila. En el siguiente ejemplo, especifique el nombre de la pila`my-hook-stack`. ``` $ aws cloudformation describe-stack-events \ --stack-name my-hook-stack ``` Utilice la `describe-stack-events` operación para ver el error de Hook al crear el depósito. A continuación, se muestra un ejemplo de la salida del comando . ``` { "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" }, ... ] } ``` *Resultados*: la invocación de Hook falló en la configuración de la pila e impidió el aprovisionamiento del recurso. Se produjo un error en la pila debido a que el cifrado del bucket de S3 estaba mal configurado. La configuración del tipo Hook es necesaria `aws:kms` mientras este bucket esté en uso`AES256`. **Usa una CloudFormation plantilla para pasar la validación de Hook** 1. Para crear una pila y pasar la validación de Hook, actualiza la plantilla para que tu recurso utilice un bucket de S3 cifrado. En este ejemplo, se utiliza la plantilla `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 ``` **nota** Los ganchos no se invocarán para los recursos omitidos. 1. Crea una pila y especifica tu plantilla. En este ejemplo, el nombre de la pila es`my-encrypted-bucket-stack`. ``` $ aws cloudformation create-stack \ --stack-name my-encrypted-bucket-stack \ --template-body file://kms-bucket-and-queue.yml ``` 1. (Opcional) Para ver el progreso de la pila, especifique el nombre de la pila. ``` $ aws cloudformation describe-stack-events \ --stack-name my-encrypted-bucket-stack ``` Usa el `describe-stack-events` comando para ver la respuesta. A continuación, se muestra un ejemplo del comando `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" }, ... ] } ``` *Resultados*: CloudFormation se creó correctamente la pila. La lógica de Hook verificó que el `AWS::S3::Bucket` recurso contenía cifrado del lado del servidor antes de aprovisionar el recurso. # Actualización de un Hook personalizado La actualización de un Hook personalizado permite que las revisiones del Hook estén disponibles en el CloudFormation registro. Para actualizar un Hook personalizado, envíe sus revisiones al CloudFormation registro mediante la [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)operación CloudFormation CLI. ``` $ cfn submit ``` Para especificar la versión predeterminada de tu Hook en tu cuenta, usa el [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)comando y especifica el tipo, el nombre del tipo y el ID de la versión. ``` $ aws cloudformation set-type-default-version \ --type HOOK \ --type-name MyCompany::Testing::MyTestHook \ --version-id 00000003 ``` Para recuperar información sobre las versiones de un Hook, usa [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" ``` # Anular el registro de un Hook personalizado del registro CloudFormation Al anular el registro de un Hook personalizado, se marca la extensión o versión de la extensión como tal `DEPRECATED` en el CloudFormation registro, lo que la elimina del uso activo. Una vez obsoleto, el Hook personalizado no se puede usar en ninguna operación. CloudFormation **nota** Antes de anular el registro del Hook, debes anular el registro de forma individual todas las versiones activas anteriores de esa extensión. Para obtener más información, consulte [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DeregisterType.html). Para anular el registro de un Hook, utilice la [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html)operación y especifique su ARN de Hook. ``` $ aws cloudformation deregister-type \ --arn HOOK_TYPE_ARN ``` Este comando no produce ningún resultado. # Publicar ganchos para uso público Para desarrollar un Hook público de terceros, desarrolla tu Hook como una extensión privada. Luego, en cada una de las extensiones Región de AWS en las que quieras que la extensión esté disponible públicamente: 1. Registra tu Hook como una extensión privada en el CloudFormation registro. 1. Prueba tu Hook para asegurarte de que cumple con todos los requisitos necesarios para ser publicado en el CloudFormation registro. 1. Publica tu Hook en el CloudFormation registro. **nota** Antes de publicar cualquier extensión en una región determinada, primero debes registrarte como editor de extensiones en esa región. Para hacerlo en varias regiones simultáneamente, consulte [Publicar extensiones en varias regiones mediante StackSets](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension-stacksets.html) la *Guía del usuario de CloudFormation CLI*. Una vez que hayas desarrollado y registrado tu Hook, podrás ponerlo a disposición del público en CloudFormation general *publicándolo* en el CloudFormation registro, como una extensión pública de terceros. Los Hooks públicos de terceros te permiten ofrecer a CloudFormation los usuarios la posibilidad de inspeccionar de forma proactiva la configuración de AWS los recursos antes de aprovisionarlos. Al igual que ocurre con los Hooks privados, los Hooks públicos reciben el mismo trato que cualquier Hook publicado por AWS ellos. CloudFormation Todos los CloudFormation usuarios pueden ver los Hooks publicados en el registro Regiones de AWS en el que están publicados. A continuación, los usuarios pueden *activar* la extensión en su cuenta, de modo que esté disponible para su uso en sus plantillas. Para obtener más información, consulte [Utilizar extensiones públicas de terceros del CloudFormation registro](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html) en la *Guía del CloudFormation usuario*. # Probando un Hook personalizado para uso público Para publicar tu Hook personalizado registrado, debe superar todos los requisitos de prueba definidos para él. La siguiente es una lista de requisitos necesarios antes de publicar tu Hook personalizado como una extensión de terceros. Cada controlador y objetivo se prueban dos veces. Una vez para `SUCCESS` y otra para`FAILED`. + Para un caso de `SUCCESS` respuesta: + El estado debe ser`SUCCESS`. + No debe devolver un código de error. + El retardo de devolución de llamada debe establecerse en `0` segundos, si se especifica. + Para el caso `FAILED` de respuesta: + El estado debe ser`FAILED`. + Debe devolver un código de error. + Debe tener un mensaje de respuesta. + El retardo de devolución de llamada se debe establecer en `0` segundos, si se especifica. + Para el caso `IN_PROGRESS` de respuesta: + No debe devolver un código de error. + `Result`el campo no debe configurarse como respuesta. # Especificación de los datos de entrada para su uso en las pruebas de contrato De forma predeterminada, CloudFormation realiza pruebas de contrato utilizando las propiedades de entrada generadas a partir de los patrones que definas en tu esquema de Hook. Sin embargo, la mayoría de los Hooks son lo suficientemente complejos como para que las propiedades de entrada para precrear o actualizar las pilas de aprovisionamiento requieran una comprensión del recurso que se está aprovisionando. Para solucionar este problema, puedes especificar la entrada que CloudFormation utilizan al realizar sus pruebas de contrato. CloudFormation ofrece dos formas de especificar los datos de entrada para utilizarlos al realizar las pruebas de contrato: + Anula el archivo El uso de un `overrides` archivo proporciona una forma ligera de especificar los datos de entrada para determinadas propiedades específicas CloudFormation para utilizarlos durante `preCreate` las pruebas `preUpdate` y `preDelete` las operaciones. + Archivos de entrada También puede usar varios `input` archivos para especificar los datos de entrada de las pruebas de contrato si: + Desea o necesita especificar datos de entrada diferentes para las operaciones de creación, actualización y eliminación, o bien datos no válidos con los que realizar las pruebas. + Desea especificar varios conjuntos de datos de entrada diferentes. ## Especificar los datos de entrada mediante un archivo de anulación El siguiente es un ejemplo de los datos de entrada de Amazon S3 Hook utilizando el `overrides` archivo. ``` { "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" } } } } ``` ## Especificar los datos de entrada mediante archivos de entrada Utilice `input` los archivos para especificar diferentes tipos de datos de entrada CloudFormation para su uso: `preCreate` entrada, `preUpdate` entrada y entrada no válida. Cada tipo de datos se especifica en un archivo independiente. También puede especificar varios conjuntos de datos de entrada para las pruebas de contrato. Para especificar `input` los archivos CloudFormation que se van a utilizar en las pruebas por contrato, añade una `inputs` carpeta al directorio raíz de tu proyecto de Hooks. Luego agrega tus archivos de entrada. Especifique el tipo de datos de entrada que contiene un archivo mediante las siguientes convenciones de nomenclatura, donde **n**es un número entero: + `inputs_n_pre_create.json`: utilice archivos con `preCreate` controladores para especificar las entradas a fin de crear el recurso. + `inputs_n_pre_update.json`: Utilice archivos con `preUpdate` controladores para especificar las entradas a fin de actualizar el recurso. + `inputs_n_pre_delete.json`: Utilice archivos con `preDelete` controladores para especificar las entradas a fin de eliminar el recurso. + `inputs_n_invalid.json`: Para especificar entradas no válidas para probarlas. Para especificar varios conjuntos de datos de entrada para las pruebas de contrato, incremente el número entero en los nombres de los archivos para ordenar los conjuntos de datos de entrada. Por ejemplo, el primer conjunto de archivos de entrada debe tener el nombre `inputs_1_pre_create.json``inputs_1_pre_update.json`, y`inputs_1_pre_invalid.json`. El siguiente conjunto se llamaría `inputs_2_pre_create.json``inputs_2_pre_update.json`, y`inputs_2_pre_invalid.json`, y así sucesivamente. Cada archivo de entrada es un archivo JSON que contiene solo las propiedades del recurso que se utilizarán en las pruebas. El siguiente es un ejemplo de directorio `inputs` para Amazon S3 especificar datos de entrada mediante archivos de entrada. `inputs_1_pre_create.json` El siguiente es un ejemplo de la prueba de `inputs_1_pre_create.json` contrato. ``` { "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` El siguiente es un ejemplo de la prueba de `inputs_1_pre_update.json` contrato. ``` { "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` El siguiente es un ejemplo de la prueba de `inputs_1_invalid.json` contrato. ``` { "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` El siguiente es un ejemplo de la prueba de `inputs_1_invalid_pre_update.json` contrato. ``` { "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" } } } ``` Para obtener más información, consulte [Publishing extensions to make them available for public use](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/publish-extension.html) (Publicar extensiones para que estén disponibles para uso público) en la *Guía del usuario de la CLI de CloudFormation *. # Referencia de sintaxis del esquema para CloudFormation Hooks En esta sección se describe la sintaxis del esquema que utilizas para desarrollar CloudFormation Hooks. Un Hook incluye una especificación de Hook representada por un esquema JSON y controladores de Hook. El primer paso para crear un Hook personalizado es modelar un esquema que defina el Hook, sus propiedades y sus atributos. Al inicializar un proyecto Hook personalizado mediante el [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)comando CloudFormation CLI, se crea un archivo de esquema Hook para usted. Usa este archivo de esquema como punto de partida para definir la forma y la semántica de tu Hook personalizado. ## Sintaxis del esquema El siguiente esquema es la estructura de 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` El nombre exclusivo de tu Hook. Especifica un espacio de nombres de tres partes para tu Hook, con un patrón recomendado de. `Organization::Service::Hook` Los siguientes espacios de nombres de organización están reservados y no se pueden usar en los nombres de tipo Hook: + `Alexa` + `AMZN` + `Amazon` + `ASK` + `AWS` + `Custom` + `Dev` *Obligatorio*: sí *Patrón*: `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *Mínimo*: `10` *Máximo*: `196` `description` Una breve descripción del Hook que se muestra en la CloudFormation consola. *Obligatorio*: sí `sourceUrl` La URL del código fuente del Hook, si es pública. *Obligatorio*: no *Máximo*: `4096` `documentationUrl` La URL de una página que proporciona documentación detallada del Hook. *Obligatorio*: sí *Patrón*: `^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$` *Máximo*: `4096` Si bien el esquema de Hook debe incluir descripciones de propiedades completas y precisas, puedes usar la `documentationURL` propiedad para proporcionar a los usuarios más detalles, incluidos ejemplos, casos de uso y otra información detallada. `definitions` Usa el `definitions` bloque para proporcionar esquemas de propiedades de Hook compartidos. Se considera una buena práctica utilizar la `definitions` sección para definir elementos de esquema que se puedan utilizar en varios puntos del esquema de tipo Hook. A continuación, puedes usar un puntero JSON para hacer referencia a ese elemento en los lugares correspondientes de tu esquema de tipo Hook. *Obligatorio*: no `typeConfiguration` La definición de los datos de configuración de un Hook. *Obligatorio*: sí `properties` Las propiedades del Hook. Todas las propiedades de un Hook deben expresarse en el esquema. Alinee las propiedades del esquema Hook con las propiedades de configuración del tipo Hook. No se permiten propiedades anidadas. En su lugar, defina las propiedades anidadas en el `definitions` elemento y utilice un `$ref` puntero para hacer referencia a ellas en la propiedad deseada. Actualmente se admiten las siguientes propiedades: + `default`— El valor por defecto de la propiedad. + `description`— Una descripción de la propiedad. + `pattern`— Un patrón de expresiones regulares que se utiliza para validar la entrada. + `type`— El tipo de propiedad aceptado. `additionalProperties` `additionalProperties` se debe establecer en `false`. Todas las propiedades de un Hook deben expresarse en el esquema: no se permiten entradas arbitrarias. *Obligatorio*: sí *Valores válidos*: `false` `handlers` Los controladores especifican las operaciones que pueden iniciar el Hook definido en el esquema, como los puntos de invocación del Hook. Por ejemplo, se invoca un `preUpdate` controlador antes de las operaciones de actualización para todos los objetivos especificados en el controlador. *Valores válidos*: `preCreate` \$1 `preUpdate` \$1 `preDelete` Debe especificarse al menos un valor para el controlador. Apila las operaciones que dan como resultado el estado de `UpdateCleanup` no invocan un Hook. Por ejemplo, en los dos escenarios siguientes, no se invoca el `preDelete` controlador del Hook: + la pila se actualiza después de eliminar un recurso de la plantilla. + se elimina un recurso con el tipo de actualización de [reemplazo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement). `targetNames` Un conjunto de cadenas de nombres de tipos a los que apunta Hook. Por ejemplo, si un `preCreate` controlador tiene un `AWS::S3::Bucket` objetivo, el Hook se ejecuta para los buckets de Amazon S3 durante la fase de preaprovisionamiento. + `TargetName` Especifique al menos un nombre de destino para cada controlador implementado. *Patrón*: `^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$` *Mínimo*: `1` *Obligatorio*: sí **aviso** Las referencias dinámicas de SSM SecureString y Secrets Manager no se resuelven antes de pasarlas a Hooks. `permissions` Una matriz de cadenas que especifica los AWS permisos necesarios para invocar el controlador. *Obligatorio*: sí `additionalProperties` `additionalProperties` se debe establecer en `false`. Todas las propiedades de un Hook deben expresarse en el esquema: no se permiten entradas arbitrarias. *Obligatorio*: sí *Valores válidos*: `false` ## Ejemplos de esquemas de Hooks **Ejemplo 1** Los tutoriales de Java y Python utilizan el siguiente ejemplo de código. El siguiente es un ejemplo de estructura para un Hook llamado. `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 } ``` **Ejemplo 2** El siguiente ejemplo es un esquema que usa `STACK` and `CHANGE_SET` for para apuntar `targetNames` a una plantilla de pila y a una operación de conjunto de cambios. ``` { "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 } ```