Infrastructure CDK

AWS CDK est un framework permettant de définir une infrastructure cloud via du code et de la déployer via AWS CloudFormation.

Le générateur d’infrastructure TypeScript crée une application d’infrastructure AWS CDK écrite en TypeScript. L’application générée intègre des bonnes pratiques de sécurité grâce aux vérifications de Checkov.

Utilisation

Générer un projet d’infrastructure

Vous pouvez générer un nouveau projet d’infrastructure de deux manières :

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#infra
5. Remplissez les paramètres requis
6. Cliquez sur Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	The name of the application.
directory	string	packages	The directory of the new application.

Résultat du générateur

Le générateur créera la structure de projet suivante dans le répertoire <directory>/<name> :

• Répertoiresrc

  • main.ts Point d’entrée de l’application instanciant les stages CDK à déployer
  • Répertoirestages Définitions des stages CDK

    • application-stage.ts Définit un ensemble de stacks à déployer dans un stage
  • Répertoirestacks Définitions des stacks CDK

    • application-stack.ts Stack principale de l’application
• cdk.json Configuration CDK
• project.json Configuration du projet et cibles de build
• checkov.yml Fichier de configuration Checkov

Astuce

Votre infrastructure étant un projet TypeScript, vous pouvez consulter la documentation des projets TypeScript pour plus de détails sur leur utilisation générale.

Implémentation de votre infrastructure CDK

Vous pouvez commencer à écrire votre infrastructure CDK dans src/stacks/application-stack.ts, par exemple :

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Déclarez votre infrastructure ici
    new Bucket(this, 'MyBucket');
  }
}

Stages et Stacks

Vous remarquerez que le fichier principal src/main.ts instancie un Stage CDK nommé <namespace>-sandbox. Ce stage est destiné à vos propres développements et tests.

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

Vous pouvez ajouter d’autres stages, par exemple définir des stages beta et prod déployés dans des environnements distincts :

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // compte beta
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // compte prod
    region: 'us-west-2',
  },
});

Un Stage définit un ensemble de stacks à déployer conjointement pour composer votre application. Vous pouvez instancier autant de stacks que nécessaire dans un stage, par exemple :

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * Définit un ensemble de stacks CDK composant votre application
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

Infrastructure d’API

Si vous avez utilisé les générateurs tRPC API ou FastAPI, vous remarquerez que des constructs sont déjà disponibles dans packages/common/constructs pour les déployer.

Par exemple, si vous avez créé une API tRPC nommée my-api, vous pouvez simplement importer et instancier le construct pour ajouter l’infrastructure nécessaire :

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Ajoutez l'infrastructure pour votre API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Infrastructure de site web

Si vous avez utilisé le générateur site web CloudScape, un construct est déjà disponible dans packages/common/constructs. Par exemple :

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Ajoutez l'infrastructure pour votre site web
    new MyWebsite(this, 'MyWebsite');
  }
}

Il est important de déclarer le site web après les constructs d’API pour que la Configuration d’exécution du site inclue toutes les configs d’API.

Synthèse de votre infrastructure

En plus des cibles de compilation, lint et test par défaut, votre projet d’infrastructure est synthétisé en CloudFormation lors du build. Cette opération peut aussi être exécutée séparément via la cible synth :

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

Vous trouverez l’assembly cloud synthétisée dans le dossier dist racine, sous dist/packages/<my-infra-project>/cdk.out.

Tests de sécurité

Une cible checkov est ajoutée pour exécuter des vérifications de sécurité sur votre infrastructure via Checkov.

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

Les résultats des tests de sécurité se trouvent dans le dossier dist racine, sous dist/packages/<my-infra-project>/checkov.

Note

Checkov utilise uvx, vous devez donc installer uv si ce n’est pas déjà fait.

Attention

Certaines règles Checkov sont désactivées par défaut via le fichier checkov.yml. Il est recommandé de les revoir selon votre cas d’usage.

Suppression de vérifications Checkov

Il peut être nécessaire de supprimer certaines règles sur des ressources. Deux méthodes sont possibles :

Supprimer une règle sur un construct donné

import { suppressRules } from ':my-scope/common-constructs';

// Supprime la règle CKV_AWS_XXX pour le construct donné
suppressRules(construct, ['CKV_AWS_XXX'], 'Raison');

Supprimer une règle sur un construct descendant

import { suppressRules } from ':my-scope/common-constructs';

// Supprime CKV_AWS_XXX pour le construct ou ses descendants de type Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Raison', (construct) => construct instanceof Bucket);

Bootstrap de votre(vos) compte(s) AWS

Si vous déployez une application CDK sur un compte AWS pour la première fois, celui-ci doit être bootstrappé.

Assurez-vous d’abord d’avoir configuré les credentials pour votre compte AWS.

Utilisez ensuite la commande cdk bootstrap :

npx cdk bootstrap aws://<account-id>/<region>

Pour plus de détails, consultez la documentation CDK.

Déploiement sur AWS

Après un build, vous pouvez déployer votre infrastructure via la cible deploy.

Attention

Utilisez la cible deploy-ci pour les pipelines CI/CD. Voir ci-dessous pour plus de détails.

Assurez-vous d’avoir configuré les credentials pour votre compte AWS.

Exécutez ensuite la cible de déploiement :

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

Astuce

Cette commande déploie toutes les stacks du stage <my-infra>-sandbox. Vous pouvez spécifier d’autres stages s’ils sont définis dans main.ts.

Vous pouvez aussi déployer des stacks individuelles en spécifiant leur nom complet :

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

Déploiement sur AWS dans un pipeline CI/CD

Utilisez la cible deploy-ci pour les déploiements dans un pipeline CI/CD :

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

Cette cible diffère légèrement en déployant l’assembly cloud pré-synthétisée plutôt que de synthétiser à la volée. Cela évite les problèmes de non-déterminisme liés aux versions de packages, garantissant que chaque étape du pipeline déploie la même assembly cloud.

Suppression de l’infrastructure AWS

Utilisez la cible destroy pour supprimer vos ressources :

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

Informations complémentaires

Pour en savoir plus sur CDK, consultez le Guide développeur CDK et la Référence API.