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 à des vérifications CFN Guard.

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.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
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 une collection 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

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 pour définir des environnements beta et prod déployés séparément :

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 une collection de stacks à déployer ensemble 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 une collection 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 API tRPC ou FastAPI, vous remarquerez que des constructs sont déjà disponibles dans packages/common/constructs pour les déployer.

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 pour le déployer. 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 Runtime du site inclue tous les paramètres des API.

Synthèse de votre infrastructure

Dans le cadre de votre cible build, en plus des cibles par défaut de compilation, lint et tests, votre projet d’infrastructure est synthétisé en CloudFormation. Ceci peut aussi être exécuté indépendamment 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 votre assembly cloud synthétisée dans le dossier racine dist, sous dist/packages/<my-infra-project>/cdk.out.

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 d’abord être bootstrappé.

1. Assurez-vous d’avoir configuré les credentials pour votre compte AWS.
2. Utilisez la commande cdk bootstrap :

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

Pour plus de détails, référez-vous à la documentation CDK.

Déploiement sur AWS

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

Attention

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

1. Assurez-vous d’avoir configuré les credentials pour votre compte AWS.
2. Exécutez la cible deploy :

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

La commande ci-dessus 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 en pipeline CI/CD

Utilisez la cible deploy-ci pour déployer sur AWS 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 de deploy en ce qu’elle déploie une cloud-assembly 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 cloud-assembly.

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/*

Plus d’informations

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