Esta es la guía para desarrolladores de AWS CDK v2. La primera versión del CDK pasó a la etapa de mantenimiento el 1.° de junio de 2022 y no cuenta con soporte desde el 1.° de junio de 2023.

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.

AWS Validación de CDK en el momento de la síntesis

Validación en el momento de la síntesis

Su aplicación de AWS CDK genera una descripción de la infraestructura en el momento de la síntesis en forma de CloudFormation plantillas. Estas plantillas se validan inmediatamente después de la síntesis. La AWS CDK incluye un conjunto integrado de reglas de validación, que puede ampliar con otras herramientas de CDK-specific validación, como CDK Nag, o con cualquier herramienta de validación de políticas que su organización ya utilice, como AWS CloudFormation Guard u OPA. Si se produce alguna infracción, la síntesis fallará y se imprimirá un informe en la consola. Mediante la validación sin conexión de las plantillas sintetizadas, puede detectar y solucionar los posibles problemas de su infraestructura en una fase temprana. Utilizaría la validación para detectar problemas que pudieran provocar implementaciones fallidas, errores de configuración habituales o el incumplimiento de los estándares de la empresa.

¿Qué es y qué no es la validación

La validación que realiza el AWS CDK en el momento de la síntesis es una validación que hace todo lo posible para mejorar la experiencia de los desarrolladores; no es un mecanismo de cumplimiento total de las normas por sí solo. Valida las plantillas generadas normalmente por una aplicación de CDK, pero no puede afectar a las acciones que se producen fuera de la síntesis. Por ejemplo, las acciones que se realizan directamente en la consola o mediante las API de servicio. Además, dado que las aplicaciones CDK están escritas en un lenguaje de programación de uso general, los desarrolladores decididos pueden eludir el mecanismo de validación si así lo desean. Por eso, la validación de CDK es un mecanismo que se mueve hacia la izquierda para validar anticipadamente y debe usarse en combinación con otro mecanismo para validar los conjuntos de reglas deseados, como hooks AWS CloudFormation o Config.AWS

Para desarrolladores de aplicaciones

Añadir complementos de validación

La validación se realiza mediante complementos de validación. En función de @ aws/cloudformation -validate, se añade automáticamente a la aplicación un complemento predeterminado que utiliza un conjunto de reglas completo para los recursos de AWS. Si desea añadir complementos adicionales a su aplicación, utilice la Validations clase:

import { Validations } from 'aws-cdk-lib';
import { CfnGuardValidator } from '@cdklabs/cdk-validator-cfnguard';

const app = new App();

// Add a validation plugin to the entire app
Validations.of(app).addPlugins(new CfnGuardValidator());

// Or add to a particular stage
const prodStage = new Stage(app, 'ProdStage');
Validations.of(prodStage).addPlugins(new CfnGuardValidator());

Inmediatamente después de la síntesis, se invocarán todos los complementos registrados de esta manera para validar todas las plantillas generadas en el ámbito que haya definido. En concreto, si registra las plantillas en el objeto App, todas las plantillas estarán sujetas a validación.

Informe de validación

Al sintetizar la aplicación AWS CDK, se llamarán los complementos de validación y se imprimirán los resultados. A continuación, se muestra un ejemplo de informe.

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'.
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check'

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse'
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check'

...

De forma predeterminada, el informe se imprimirá en un formato legible para las personas. Si desea un informe en formato JSON, habilítelo mediante @aws-cdk/core:validationReportJson a través de la CLI o pasándolo directamente a la aplicación:

const app = new App({
  context: { '@aws-cdk/core:validationReportJson': true },
});

Como alternativa, puede configurar este par clave-valor del contexto utilizando los cdk.context.json archivos cdk.json o del directorio de su proyecto (consulte Los valores de contexto y la CDK). AWS

Si elige el formato JSON, la AWS CDK imprimirá el informe de validación de políticas en un archivo llamado policy-validation-report.json en el directorio de ensamblaje de la nube. En el formato predeterminado, legible por humanos, el informe se imprimirá en la salida estándar.

Reconocimiento de las advertencias

Si ha evaluado una advertencia o un error y ha considerado que no es válido en su caso, puede suprimirlo mediante acknowledge este método. La supresión se basa en el alcance y se aplica a todos los constructos incluidos en el ámbito dado.

import { Validations } from 'aws-cdk-lib';

Validations.of(myConstruct).acknowledge({
  id: 'PluginName::MyWarningId',
  reason: 'This is acceptable for our use case',
});

idUtiliza un :: delimitador para separar el prefijo de la fuente de validación del nombre de la regla (por ejemplo, o). Construct-Annotations:: AwsSolutions-S1::

AWS CloudFormation Complemento Guard

El uso del CfnGuardValidatorcomplemento le permite usar AWS CloudFormation Guard para realizar validaciones de políticas. El complemento CfnGuardValidator viene con un conjunto selecto de controles AWS Control Tower proactivos integrados. El conjunto de reglas actual se encuentra en la documentación del proyecto. Como se menciona en Validación de políticas en el momento de la síntesis, recomendamos que las organizaciones establezcan un método de validación más fiable mediante ganchos.AWS CloudFormation

Para los clientes AWS Control Tower, estos mismos controles proactivos se pueden implementar en toda la organización. Cuando habilita los controles proactivos de la Torre de AWS Control en su entorno de Torre de AWS Control, los controles pueden detener el despliegue de los recursos no conformes desplegados a través AWS CloudFormation de ella. Para obtener más información sobre los controles proactivos administrados y su funcionamiento, consulte la documentación de AWS Control Tower.

Es mejor utilizar estos controles AWS CDK agrupados y los controles proactivos gestionados de la Torre de AWS Control Tower juntos. En este escenario, puede configurar este complemento de validación con los mismos controles proactivos que están activos en su entorno de nube de AWS Control Tower. De este modo, podrá confiar rápidamente en que su aplicación AWS CDK superará los controles de la Torre de AWS Control ejecutándose cdk synth localmente.

AWS Complemento CDK Nag

Puedes usar CDK Nag para comparar tu infraestructura con una serie de estándares, como HIPAA, PCI DSS, etc. La versión 3.x de cdk-nag se integra con el mecanismo de validaciones estandarizado de CDK.

Para los autores de constructos: añadir advertencias y errores directamente

La Validations clase también proporciona métodos para añadir advertencias y errores personalizados directamente a las construcciones. Puedes usar este mecanismo para informar sobre las configuraciones erróneas directamente en tu construcción sin tener que implementar un complemento de validación. Las validaciones y los errores que añadas de esta manera se informarán junto con las infracciones detectadas por los complementos de validación.

import { Validations } from 'aws-cdk-lib';

const bucket = new s3.Bucket(this, 'MyBucket');

// Add a warning
Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled');

// Add an error (will cause synthesis to fail)
Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled');

Para los autores de complementos

El marco principal de AWS CDK es responsable de registrar e invocar los complementos y, a continuación, mostrar el informe de validación formateado. La responsabilidad del complemento es actuar como capa de traducción entre el marco del AWS CDK y una herramienta externa de validación de políticas que su complemento podría, por ejemplo, utilizar. Se puede crear un complemento en cualquier idioma compatible con AWS CDK. Si vas a crear un plugin que pueda ser utilizado en varios idiomas, te recomendamos que lo crees de TypeScript forma que puedas usar JSII para publicar el plugin en cada AWS idioma del CDK.

Creación de complementos

La interfaz define el protocolo de comunicación entre el módulo principal de la AWS CDK y tu herramienta de políticas. IPolicyValidationPlugin Para crear un nuevo complemento, debe escribir una clase que implemente esta interfaz. Hay dos cosas que debe implementar: el nombre del complemento (anulando la propiedad name) y el método validate().

El marco llamará a validate() y pasará un objeto IPolicyValidationContext. templatePaths da la ubicación de las plantillas a validar. El complemento debería devolver una instancia de PolicyValidationPluginReport. Este objeto representa el informe que recibirá el usuario al final de la síntesis.

validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
  // First read the templates using context.templatePaths...
  // ...then perform the validation, and then compose and return the report.
  // Using hard-coded values here for better clarity:
  return {
    success: false,
    violations: [{
      ruleName: 'CKV_AWS_117',
      description: 'Ensure that AWS Lambda function is configured inside a VPC',
      fix: 'https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1',
      violatingResources: [{
        resourceName: 'MyFunction3BAA72D1',
        templatePath: '/home/johndoe/myapp/cdk.out/MyService.template.json',
        locations: 'Properties/VpcConfig',
      }],
    }],
  };
}

Tenga en cuenta que los complementos no pueden modificar nada en el ensamblaje de la nube. Cualquier intento de hacerlo provocará un fallo en la síntesis.

Si tu complemento depende de una herramienta externa que hayas contratado, ten en cuenta que es posible que algunos desarrolladores aún no tengan esa herramienta instalada en sus estaciones de trabajo. Para minimizar la fricción, proporciona un script de instalación junto con el paquete de complementos para automatizar el proceso de instalación.

Tratamiento de excepciones

Si su organización tiene un mecanismo para administrar las exenciones, puede implementarlo como parte del complemento de validación.

Un ejemplo de escenario para ilustrar un posible mecanismo de exención:

En este escenario, el desarrollador solicitaría una excepción en el sistema interno y luego necesitaría alguna forma de “registrar” esa excepción. Si agregamos el ejemplo del complemento guard, podría crear un complemento que administre las exenciones filtrando las infracciones que cuenten con una exención equivalente en un sistema interno de venta de entradas.

Consulte los complementos existentes para ver ejemplos de implementaciones.