Ceci est le guide du développeur du AWS CDK v2. L'ancien CDK v1 est entré en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AWS Validation du CDK au moment de la synthèse

Validation au moment de la synthèse

Votre application AWS CDK génère une description de l'infrastructure au moment de la synthèse sous forme de CloudFormation modèles. Ces modèles sont validés immédiatement après la synthèse. Le AWS CDK est doté d'un ensemble intégré de règles de validation, que vous pouvez étendre à d'autres outils de CDK-specific validation tels que CDK Nag ou à tout autre outil de validation des politiques que votre organisation utilise déjà, tel que AWS CloudFormation Guard ou OPA. En cas de violation, la synthèse échouera et un rapport sera imprimé sur la console. Grâce à la validation hors ligne de vos modèles synthétisés, vous pouvez découvrir et résoudre rapidement les problèmes potentiels liés à votre infrastructure. Vous utiliseriez la validation pour détecter les problèmes susceptibles d'entraîner l'échec des déploiements, des erreurs de configuration courantes ou le non-respect des normes de l'entreprise.

Ce qu'est et n'est pas la validation

La validation effectuée par le AWS CDK au moment de la synthèse est une validation basée sur le meilleur effort pour améliorer l'expérience des développeurs ; il ne s'agit pas d'un mécanisme de conformité aux normes à part entière. Il valide les modèles générés normalement par une application CDK, mais il ne peut pas affecter les actions qui se produisent en dehors de la synthèse. Par exemple, des actions effectuées directement dans la console ou via des API de service. De plus, comme les applications CDK sont écrites dans un langage de programmation à usage général, les développeurs déterminés peuvent contourner le mécanisme de validation s'ils le souhaitent. C'est pourquoi la validation CDK est un mécanisme de validation précoce, qui doit être utilisé en combinaison avec un autre mécanisme pour valider les ensembles de règles souhaités, tels que hooks AWS CloudFormation ou Config.AWS

Pour les développeurs d'applications

Ajouter des plugins de validation

La validation est effectuée par des plugins de validation. Un plugin par défaut qui utilise un ensemble de règles complet pour les ressources AWS est automatiquement ajouté à votre application, sur la base de @ aws/cloudformation -validate. Si vous souhaitez ajouter des plugins supplémentaires à votre application, utilisez la Validations classe :

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

Immédiatement après la synthèse, tous les plugins enregistrés de cette manière seront invoqués pour valider tous les modèles générés dans le champ que vous avez défini. En particulier, si vous enregistrez les modèles dans l'Appobjet, tous les modèles seront soumis à validation.

Rapport de validation

Lorsque vous synthétiserez l'application AWS CDK, les plugins de validation seront appelés et les résultats seront imprimés. Un exemple de rapport est présenté ci-dessous.

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'

...

Par défaut, le rapport sera imprimé dans un format lisible par l'homme. Si vous souhaitez un rapport au format JSON, activez-le @aws-cdk/core:validationReportJson via la CLI ou transmettez-le directement à l'application :

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

Vous pouvez également définir cette paire clé-valeur de contexte à l'aide des cdk.context.json fichiers cdk.json or du répertoire de votre projet (voir Valeurs de contexte et AWS CDK).

Si vous choisissez le format JSON, le AWS CDK imprimera le rapport de validation des politiques dans un fichier appelé policy-validation-report.json dans le répertoire d'assemblage du cloud. Pour le format par défaut lisible par l'homme, le rapport sera imprimé sur la sortie standard.

Reconnaissance des avertissements

Si vous avez évalué un avertissement ou une erreur et que vous estimez qu'il ne vous concerne pas, vous pouvez le supprimer à l'aide de acknowledge cette méthode. La suppression est basée sur la portée et s'applique à toutes les constructions relevant de la portée donnée.

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

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

idUtilise un :: délimiteur pour séparer le préfixe de la source de validation du nom de la règle (par exemple, Construct-Annotations:: ouAwsSolutions-S1::).

AWS CloudFormation Plug-in Guard

L'utilisation du CfnGuardValidatorplugin vous permet d'utiliser AWS CloudFormation Guard pour effectuer des validations de politiques. Le CfnGuardValidator plugin est livré avec un ensemble sélectionné de AWS contrôles proactifs intégrés de la Control Tower. L'ensemble de règles actuel se trouve dans la documentation du projet. Comme indiqué dans la section Validation des politiques au moment de la synthèse, nous recommandons aux organisations de mettre en place une méthode de validation plus fiable à l'aide de AWS CloudFormation crochets.

Pour les clients AWS de Control Tower, ces mêmes contrôles proactifs peuvent être déployés dans l'ensemble de leur organisation. Lorsque vous activez AWS les contrôles proactifs de la AWS Control Tower dans votre environnement Control Tower, les contrôles peuvent arrêter le déploiement de ressources non conformes déployées via AWS CloudFormation. Pour plus d'informations sur les contrôles proactifs gérés et leur fonctionnement, consultez la documentation AWS de Control Tower.

Il est préférable d'utiliser ensemble ces contrôles fournis par AWS CDK et ces contrôles proactifs gérés par AWS Control Tower. Dans ce scénario, vous pouvez configurer ce plugin de validation avec les mêmes contrôles proactifs que ceux actifs dans votre environnement cloud AWS Control Tower. Vous pouvez alors rapidement être sûr que votre application AWS CDK passera les commandes de la AWS Control Tower en s'exécutant cdk synth localement.

AWS Plug-in CDK Nag

Vous pouvez utiliser CDK Nag pour vérifier votre infrastructure par rapport à un certain nombre de normes telles que HIPAA, PCI DSS, etc. La version 3.x de cdk-nag s'intègre au mécanisme de validation standardisé de CDK.

Pour les auteurs de constructions : ajout direct d'avertissements et d'erreurs

La Validations classe fournit également des méthodes pour ajouter directement des avertissements et des erreurs personnalisés à vos constructions. Vous pouvez utiliser ce mécanisme pour signaler les erreurs de configuration directement sur votre build sans avoir à implémenter un plugin de validation. Les validations et les erreurs que vous ajoutez de cette manière seront signalées ainsi que les violations détectées par les plugins de validation.

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

Pour les auteurs de plugins

Le framework principal du AWS CDK est chargé d'enregistrer et d'appeler les plugins, puis d'afficher le rapport de validation formaté. La responsabilité du plugin est d'agir en tant que couche de traduction entre le framework AWS CDK et un outil de validation de politique externe auquel votre plugin pourrait par exemple débourser. Un plugin peut être créé dans n'importe quelle langue prise en charge par AWS CDK. Si vous créez un plugin susceptible d'être utilisé par plusieurs langues, il est recommandé de le créer TypeScript afin de pouvoir utiliser JSII pour le publier dans chaque langue du AWS CDK.

Création de plugins

Le protocole de communication entre le module principal du AWS CDK et votre outil de politique est défini par l'IPolicyValidationPlugininterface. Pour créer un nouveau plugin, vous devez écrire une classe qui implémente cette interface. Vous devez implémenter deux choses : le nom du plugin (en remplaçant la name propriété) et la validate() méthode.

Le framework appellera validate() en passant un IPolicyValidationContext objet. L'emplacement des modèles à valider est indiqué partemplatePaths. Le plugin doit renvoyer une instance dePolicyValidationPluginReport. Cet objet représente le rapport que l'utilisateur recevra à la fin de la synthèse.

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',
      }],
    }],
  };
}

Notez que les plugins ne sont pas autorisés à modifier quoi que ce soit dans l'assemblage du cloud. Toute tentative en ce sens entraînera l'échec de la synthèse.

Si votre plugin dépend d'un outil externe que vous déboursez, gardez à l'esprit que certains développeurs n'ont peut-être pas encore installé cet outil sur leur poste de travail. Pour minimiser les frictions, fournissez un script d'installation avec votre package de plug-in pour automatiser le processus d'installation.

Gestion des exemptions

Si votre organisation dispose d'un mécanisme de gestion des exemptions, celui-ci peut être mis en œuvre dans le cadre du plug-in de validation.

Exemple de scénario illustrant un éventuel mécanisme d'exemption :

Dans ce scénario, le développeur demanderait une exception dans le système interne, puis aurait besoin d'un moyen « d'enregistrer » cette exception. Pour compléter l'exemple du plugin Guard, vous pouvez créer un plugin qui gère les exemptions en filtrant les violations associées à une exemption correspondante dans un système de billetterie interne.

Consultez les plugins existants pour des exemples d'implémentations.