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 la política de CDK en el momento de la síntesis

Validación de políticas en el momento de la síntesis

Si usted o su organización utilizan alguna herramienta de validación de políticas, como AWS CloudFormation Guard u OPA, para definir las restricciones en su AWS CloudFormation plantilla, pueden integrarla en la AWS CDK en el momento de la síntesis. Al utilizar el complemento de validación de políticas adecuado, puede hacer que la aplicación AWS CDK compare la AWS CloudFormation plantilla generada con sus políticas inmediatamente después de la síntesis. Si se produce alguna infracción, la síntesis fallará y se imprimirá un informe en la consola.

La validación que realiza la AWS CDK en el momento de la síntesis valida los controles en un momento del ciclo de vida de la implementación, pero no puede afectar a las acciones que se producen fuera de la síntesis. Entre los ejemplos se incluyen las acciones que se toman directamente en la consola o mediante las API de servicio. No son resistentes a la alteración de las AWS CloudFormation plantillas después de la síntesis. Algún otro mecanismo para validar el mismo conjunto de reglas con más autoridad debería configurarse de forma independiente, como AWS CloudFormation hooks o AWS Config. Sin embargo, la capacidad del AWS CDK para evaluar el conjunto de reglas durante el desarrollo sigue siendo útil, ya que mejorará la velocidad de detección y la productividad de los desarrolladores.

El objetivo de la validación de las políticas de AWS CDK es minimizar la cantidad de configuración necesaria durante el desarrollo y hacerlo lo más fácil posible.

Para desarrolladores de aplicaciones

Añadir complementos de validación

Para usar uno o más complementos de validación en tu aplicación, usa 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.

Añadir advertencias y errores

La Validations clase también proporciona métodos para añadir advertencias y errores personalizados a sus construcciones:

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');

Reconocimiento de las advertencias

Si desea suprimir una advertencia específica, utilice el acknowledge método:

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

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

El acknowledge método acepta Acknowledgment objetos con una id y unareason. idUtiliza un :: delimitador para separar el prefijo de la fuente de validación del nombre de la regla (por ejemplo, annotation::MyWarning ocdknag::AwsSolutions-S1). Si proporciona un identificador simple sin él::, el annotation:: prefijo se agrega automáticamente.

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.

Informe de validación

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

Validation Report (CfnGuardValidator)
-------------------------------------
(Summary)
╔═══════════╤════════════════════════╗
║ Status    │ failure                ║
╟───────────┼────────────────────────╢
║ Plugin    │ CfnGuardValidator      ║
╚═══════════╧════════════════════════╝
(Violations)
Ensure S3 Buckets are encrypted with a KMS CMK (1 occurrences)
Severity: medium
  Occurrences:

    - Construct Path: MyStack/MyCustomL3Construct/Bucket
    - Stack Template Path: ./cdk.out/MyStack.template.json
    - Creation Stack:
        └──  MyStack (MyStack)
             │ Library: aws-cdk-lib.Stack
             │ Library Version: 2.50.0
             │ Location: Object.<anonymous> (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:25:20)
             └──  MyCustomL3Construct (MyStack/MyCustomL3Construct)
                  │ Library: N/A - (Local Construct)
                  │ Library Version: N/A
                  │ Location: new MyStack (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:15:20)
                  └──  Bucket (MyStack/MyCustomL3Construct/Bucket)
                       │ Library: aws-cdk-lib/aws-s3.Bucket
                       │ Library Version: 2.50.0
                       │ Location: new MyCustomL3Construct (/home/johndoe/tmp/cdk-tmp-app/src/main.ts:9:20)
    - Resource Name: amzn-s3-demo-bucket
    - Locations:
      > BucketEncryption/ServerSideEncryptionConfiguration/0/ServerSideEncryptionByDefault/SSEAlgorithm
  Recommendation: Missing value for key `SSEAlgorithm` - must specify `aws:kms`
  How to fix:
    > Add to construct properties for `cdk-app/MyStack/Bucket`
      `encryption: BucketEncryption.KMS`

Validation failed. See above reports for details

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.

Para los autores de complementos

Plugins

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 de la AWS CDK y la herramienta de validación de políticas. 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 su complemento depende de una herramienta externa, tenga 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, le recomendamos que proporcione algún script de instalación junto con su paquete de complementos, para automatizar todo el proceso. Mejor aún, ejecute ese script como parte de la instalación de su paquete. Con npm, por ejemplo, puede agregarlo al script postinstall del archivo package.json.

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.