Migration de la AWS CDK v1 vers la v2 AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
Nouveaux prérequisMise à niveau depuis AWS CDK v2 Developer PreviewMigration de la AWS CDK v1 vers la v2 CDKTester votre application migrée avant de la déployerRésolution des problèmesTrouver des piles v1

Ceci est le guide du AWS CDK développeur de la version 2. L'ancienne CDK version 1 est entrée 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.

Migration de la AWS CDK v1 vers la v2 AWS CDK

La version 2 AWS Cloud Development Kit (AWS CDK) est conçue pour faciliter l'écriture de l'infrastructure sous forme de code dans votre langage de programmation préféré. Cette rubrique décrit les modifications entre la v1 et la v2 du AWS CDK.

Astuce

Pour identifier les piles déployées avec la version AWS CDK 1, utilisez l'utilitaire awscdk-v1-stack-finder.

Les principaux changements entre la AWS CDK v1 et la CDK v2 sont les suivants.

  • AWS CDK v2 consolide les parties stables de la bibliothèque AWS Construct, y compris la bibliothèque principale, dans un seul package,aws-cdk-lib. Les développeurs n'ont plus besoin d'installer de packages supplémentaires pour les différents AWS services qu'ils utilisent. Cette approche à package unique signifie également que vous n'avez pas à synchroniser les versions des différents packages de CDK bibliothèque.

    Les constructions L1 (CfnXXXX), qui représentent les ressources exactes disponibles dans AWS CloudFormation, sont toujours considérées comme stables et sont donc incluses. aws-cdk-lib

  • Les modules expérimentaux, dans lesquels nous travaillons toujours avec la communauté pour développer de nouvelles constructions L2 ou L3, ne sont pas inclus. aws-cdk-lib Ils sont plutôt distribués sous forme de packages individuels. Les packages expérimentaux sont nommés avec un alpha suffixe et un numéro de version sémantique. Le numéro de version sémantique correspond à la première version de la bibliothèque AWS Construct avec laquelle ils sont compatibles, également avec un alpha suffixe. Les constructions sont déplacées aws-cdk-lib après avoir été désignées stables, ce qui permet à la bibliothèque de constructions principale de respecter un versionnage sémantique strict.

    La stabilité est spécifiée au niveau du service. Par exemple, si nous commençons à créer une ou plusieurs constructions L2 pour Amazon AppFlow, qui, au moment d'écrire ces lignes, ne comporte que des constructions L1, elles apparaissent d'abord dans un module nommé. @aws-cdk/aws-appflow-alpha Ensuite, ils passent au aws-cdk-lib moment où nous pensons que les nouvelles constructions répondent aux besoins fondamentaux des clients.

    Une fois qu'un module a été désigné comme stable et intégréaws-cdk-lib, de nouveaux APIs sont ajoutés en utilisant la convention « beTAN » décrite dans le bullet suivant.

    Une nouvelle version de chaque module expérimental est publiée à chaque sortie du AWS CDK. Cependant, dans la plupart des cas, ils n'ont pas besoin d'être synchronisés. Vous pouvez mettre à jour aws-cdk-lib le module expérimental quand vous le souhaitez. L'exception est que lorsque deux ou plusieurs modules expérimentaux connexes dépendent les uns des autres, ils doivent être de la même version.

  • Pour les modules stables auxquels de nouvelles fonctionnalités sont ajoutées, les nouveaux modules APIs (qu'il s'agisse de constructions entièrement nouvelles ou de nouvelles méthodes ou propriétés sur une construction existante) reçoivent un Beta1 suffixe pendant que le travail est en cours. (Suivi par Beta2Beta3, et ainsi de suite lorsque des modifications importantes sont nécessaires.) Une version API sans suffixe est ajoutée lorsque le API est désigné stable. Toutes les méthodes sauf la plus récente (qu'elle soit bêta ou finale) sont alors déconseillées.

    Par exemple, si nous ajoutons une nouvelle méthode grantPower() à une construction, elle apparaît initialement sous la formegrantPowerBeta1(). Si des modifications importantes sont nécessaires (par exemple, un nouveau paramètre ou une nouvelle propriété obligatoire), la version suivante de la méthode sera nomméegrantPowerBeta2(), et ainsi de suite. Lorsque le travail est terminé et API qu'il est finalisé, la méthode grantPower() (sans suffixe) est ajoutée et les méthodes betAN sont déconseillées.

    Toutes les versions bêta APIs restent dans la bibliothèque Construct jusqu'à la sortie de la prochaine version majeure (3.0), et leurs signatures ne changeront pas. Vous verrez des avertissements d'obsolescence si vous les utilisez. Vous devez donc passer à la version finale du API dès que possible. Cependant, aucune future version AWS CDK 2.x n'interrompra votre application.

  • La Construct classe a été extraite du AWS CDK dans une bibliothèque séparée, avec les types associés. Ceci est fait pour soutenir les efforts visant à appliquer le modèle de programmation Construct à d'autres domaines. Si vous écrivez vos propres constructions ou si vous utilisez des composants connexesAPIs, vous devez déclarer le constructs module comme dépendance et apporter des modifications mineures à vos importations. Si vous utilisez des fonctionnalités avancées, telles que l'intégration au cycle de vie de l'CDKapplication, d'autres modifications peuvent être nécessaires. Pour plus de détails, consultez le RFC.

  • Les propriétés, méthodes et types obsolètes de la AWS CDK v1.x et de sa bibliothèque de construction ont été complètement supprimés de la v2. CDK API Dans la plupart des langues prises en charge, elles APIs génèrent des avertissements sous la version v1.x. Vous avez donc peut-être déjà migré vers la version de remplacement. APIs Une liste complète des versions obsolètes APIs de la CDK version v1.x est disponible sur. GitHub

  • Le comportement qui était contrôlé par des indicateurs de fonctionnalité dans la AWS CDK version v1.x est activé par défaut dans la CDK version 2. Les indicateurs de fonctionnalité antérieurs ne sont plus nécessaires et, dans la plupart des cas, ils ne sont pas pris en charge. Quelques-uns sont encore disponibles pour vous permettre de revenir au comportement de la CDK v1 dans des circonstances très spécifiques. Pour de plus amples informations, veuillez consulter Mise à jour des indicateurs de fonctionnalités.

  • Avec la CDK version v2, les environnements dans lesquels vous déployez doivent être amorcés à l'aide de la pile bootstrap moderne. L'ancienne pile bootstrap (par défaut sous v1) n'est plus prise en charge. CDKLa v2 nécessite en outre une nouvelle version de la pile moderne. Pour mettre à niveau vos environnements existants, redémarrez-les. Il n'est plus nécessaire de définir des indicateurs de fonctionnalité ou des variables d'environnement pour utiliser la pile bootstrap moderne.

Important

Le modèle bootstrap moderne accorde efficacement les autorisations implicites --cloudformation-execution-policies à n'importe quel AWS compte de la --trust liste. Par défaut, cela étend les autorisations de lecture et d'écriture à n'importe quelle ressource du compte bootstrap. Assurez-vous de configurer la pile d'amorçage avec des politiques et des comptes fiables avec lesquels vous êtes à l'aise.

Nouveaux prérequis

La plupart des exigences pour la AWS CDK v2 sont les mêmes que pour la AWS CDK v1.x. Les exigences supplémentaires sont répertoriées ici.

  • Pour TypeScript les développeurs, la version TypeScript 3.8 ou ultérieure est requise.

  • Une nouvelle version du CDK Toolkit est requise pour une utilisation avec la CDK v2. Maintenant que la CDK v2 est généralement disponible, la v2 est la version par défaut lors de l'installation du CDK Toolkit. Il est rétrocompatible avec les projets CDK v1, vous n'avez donc pas besoin de conserver la version précédente installée, sauf si vous souhaitez créer des CDK projets v1. Pour effectuer une mise à niveau, problèmenpm install -g aws-cdk.

Mise à niveau depuis AWS CDK v2 Developer Preview

Si vous utilisez la version CDK v2 Developer Preview, votre projet dépend d'une version Release Candidate du AWS CDK, telle que2.0.0-rc1. Mettez-les à jour2.0.0, puis mettez à jour les modules installés dans votre projet.

TypeScript

npm install ou yarn install

JavaScript

npm install ou yarn install

Python
python -m pip install -r requirements.txt
Java
mvn package
C#
dotnet restore
Go
go get

Après avoir mis à jour vos dépendances, npm update -g aws-cdk lancez la mise à jour du CDK Toolkit vers la version finale.

Migration de la AWS CDK v1 vers la v2 CDK

Pour migrer votre application vers la AWS CDK version v2, mettez d'abord à jour les indicateurs de fonctionnalité danscdk.json. Mettez ensuite à jour les dépendances et les importations de votre application selon les besoins du langage de programmation dans lequel elle est écrite.

Mise à jour vers une version v1 récente

Nous constatons qu'un certain nombre de clients passent d'une ancienne version de AWS CDK v1 à la version la plus récente de v2 en une seule étape. Bien que cela soit certainement possible, vous devrez à la fois effectuer une mise à niveau après plusieurs années de changements (qui, malheureusement, n'ont peut-être pas tous fait l'objet du même nombre de tests d'évolution que ceux d'aujourd'hui) et effectuer une mise à niveau entre des versions avec de nouveaux paramètres par défaut et une organisation du code différente.

Pour une expérience de mise à niveau la plus sûre et pour diagnostiquer plus facilement les sources de modifications inattendues, nous vous recommandons de séparer ces deux étapes : commencez par effectuer la mise à niveau vers la dernière version v1, puis passez ensuite à la version v2.

Mise à jour des indicateurs de fonctionnalités

Supprimez les indicateurs de fonctionnalité v1 suivants cdk.json s'ils existent, car ils sont tous actifs par défaut dans la AWS CDK version v2. Si leur effet antérieur est important pour votre infrastructure, vous devrez apporter des modifications au code source. Consultez la liste des drapeaux GitHub pour plus d'informations.

  • @aws-cdk/core:enableStackNameDuplicates

  • aws-cdk:enableDiffNoFail

  • @aws-cdk/aws-ecr-assets:dockerIgnoreSupport

  • @aws-cdk/aws-secretsmanager:parseOwnedSecretName

  • @aws-cdk/aws-kms:defaultKeyPolicies

  • @aws-cdk/aws-s3:grantWriteWithoutAcl

  • @aws-cdk/aws-efs:defaultEncryptionAtRest

Quelques indicateurs de fonctionnalités de la version 1 peuvent être définis pour false revenir à des comportements spécifiques de la version AWS CDK 1 ; voir Revenir au comportement de la version 1 la liste ci-dessous GitHub pour une référence complète.

Pour les deux types d'indicateurs, utilisez la cdk diff commande pour inspecter les modifications apportées à votre modèle synthétisé afin de voir si les modifications apportées à l'un de ces indicateurs affectent votre infrastructure.

CDKCompatibilité avec les outils

CDKv2 nécessite la version v2 ou ultérieure du CDK Toolkit. Cette version est rétrocompatible avec CDK les applications v1. Par conséquent, vous pouvez utiliser une seule version de CDK Toolkit installée dans le monde entier avec tous vos AWS CDK projets, qu'ils utilisent la v1 ou la v2. Une exception est que CDK Toolkit v2 ne crée que des projets CDK v2.

Si vous devez créer des CDK projets v1 et v2, n'installez pas CDK Toolkit v2 globalement. (Supprimez-le si vous l'avez déjà installé :npm remove -g aws-cdk.) Pour appeler le CDK kit d'outils, utilisez npx la version v1 ou v2 du CDK kit comme vous le souhaitez.

npx aws-cdk@1.x init app --language typescript
npx aws-cdk@2.x init app --language typescript
Astuce

Configurez des alias de ligne de commande afin de pouvoir utiliser les cdk1 commandes cdk et pour appeler la version souhaitée du CDK Toolkit.

macOS/Linux
alias cdk1="npx aws-cdk@1.x"
alias cdk="npx aws-cdk@2.x"
Windows
doskey cdk1=npx aws-cdk@1.x $*
doskey cdk=npx aws-cdk@2.x $*

Mettre à jour les dépendances et les importations

Mettez à jour les dépendances de votre application, puis installez les nouveaux packages. Enfin, mettez à jour les importations dans votre code.

TypeScript
Applications

Pour les CDK applications, procédez à la mise à jour package.json comme suit. Supprimez les dépendances sur les modules stables individuels de style v1 et établissez la version la plus basse dont aws-cdk-lib vous avez besoin pour votre application (2.0.0 ici).

Les constructions expérimentales sont fournies dans des packages séparés, versionnés indépendamment, dont les noms se terminent par alpha et un numéro de version alpha. Le numéro de version alpha correspond à la première version aws-cdk-lib avec laquelle ils sont compatibles. Ici, nous nous sommes concentrés sur la version aws-codestar 2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}
Construire des bibliothèques

Pour les bibliothèques de construction, définissez la version la plus basse dont aws-cdk-lib vous avez besoin pour votre application (2.0.0 ici) et mettez-la à jour package.json comme suit.

Notez que cela aws-cdk-lib apparaît à la fois comme une dépendance entre pairs et comme une dépendance de développement.

{
  "peerDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0",
    "typescript": "~3.9.0"
  }
}
Note

Vous devez effectuer une augmentation de version majeure sur le numéro de version de votre bibliothèque lorsque vous publiez une bibliothèque compatible avec la version 2, car il s'agit d'un changement radical pour les utilisateurs de bibliothèques. Il n'est pas possible de prendre en charge à la fois la CDK v1 et la v2 avec une seule bibliothèque. Pour continuer à soutenir les clients qui utilisent toujours la version 1, vous pouvez maintenir la version précédente en parallèle ou créer un nouveau package pour la version 2.

C'est à vous de décider combien de temps vous souhaitez continuer à soutenir les clients de la version AWS CDK 1. Vous pourriez vous inspirer du cycle de vie de la CDK version 1 elle-même, qui est entrée en maintenance le 1er juin 2022 et arrivera à end-of-life expiration le 1er juin 2023. Pour plus de détails, consultez la politique de AWS CDK maintenance.

Bibliothèques et applications

Installez les nouvelles dépendances en exécutant npm install ouyarn install.

Modifiez vos importations pour importer Construct depuis le nouveau constructs module, les types de base tels que App et Stack depuis le niveau supérieur deaws-cdk-lib, et les modules stables de Construct Library pour les services que vous utilisez à partir des espaces de noms situés sousaws-cdk-lib.

import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib';                 // core constructs
import { aws_s3 as s3 } from 'aws-cdk-lib';               // stable module
import * as codestar from '@aws-cdk/aws-codestar-alpha';  // experimental module
JavaScript

Mettez à jour package.json comme suit. Supprimez les dépendances sur les modules stables individuels de style v1 et établissez la version la plus basse dont aws-cdk-lib vous avez besoin pour votre application (2.0.0 ici).

Les constructions expérimentales sont fournies dans des packages séparés, versionnés indépendamment, dont les noms se terminent par alpha et un numéro de version alpha. Le numéro de version alpha correspond à la première version aws-cdk-lib avec laquelle ils sont compatibles. Ici, nous nous sommes concentrés sur la version aws-codestar 2.0.0-alpha.1.

{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}

Installez les nouvelles dépendances en exécutant npm install ouyarn install.

Modifiez les importations de votre application comme suit :

  • Importer Construct depuis le nouveau constructs module

  • Importez des types de base, tels que App etStack, depuis le niveau supérieur de aws-cdk-lib

  • Importez les modules de la bibliothèque AWS Construct à partir des espaces de noms sous aws-cdk-lib

const { Construct } = require('constructs');
const { App, Stack } = require('aws-cdk-lib');              // core constructs
const s3 = require('aws-cdk-lib').aws_s3;                   // stable module
const codestar = require('@aws-cdk/aws-codestar-alpha');    // experimental module
Python

Mettez à jour requirements.txt la install_requires définition setup.py comme suit. Supprimez les dépendances sur les modules stables individuels de style v1.

Les constructions expérimentales sont fournies dans des packages séparés, versionnés indépendamment, dont les noms se terminent par alpha et un numéro de version alpha. Le numéro de version alpha correspond à la première version aws-cdk-lib avec laquelle ils sont compatibles. Ici, nous avons épinglé la aws-codestar v2.0.0alpha1.

install_requires=[
     "aws-cdk-lib>=2.0.0",
     "constructs>=10.0.0",
     "aws-cdk.aws-codestar-alpha>=2.0.0alpha1",
     # ...
],
Astuce

Désinstallez toutes les autres versions des AWS CDK modules déjà installés dans l'environnement virtuel de votre application à l'aide depip uninstall. Installez ensuite les nouvelles dépendances avecpython -m pip install -r requirements.txt.

Modifiez les importations de votre application comme suit :

  • Importer Construct depuis le nouveau constructs module

  • Importez des types de base, tels que App etStack, depuis le niveau supérieur de aws_cdk

  • Importez les modules de la bibliothèque AWS Construct à partir des espaces de noms sous aws_cdk

from constructs import Construct
from aws_cdk import App, Stack                    # core constructs
from aws_cdk import aws_s3 as s3                  # stable module
import aws_cdk.aws_codestar_alpha as codestar     # experimental module

# ...

class MyConstruct(Construct):
    # ...

class MyStack(Stack):
    # ...

s3.Bucket(...)
Java

Danspom.xml, supprimez toutes les software.amazon.awscdk dépendances des modules stables et remplacez-les par des dépendances sur software.constructs (forConstruct) etsoftware.amazon.awscdk.

Les constructions expérimentales sont fournies dans des packages séparés, versionnés indépendamment, dont les noms se terminent par alpha et un numéro de version alpha. Le numéro de version alpha correspond à la première version aws-cdk-lib avec laquelle ils sont compatibles. Ici, nous nous sommes concentrés sur la version aws-codestar 2.0.0-alpha.1.

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>aws-cdk-lib</artifactId>
    <version>2.0.0</version>
</dependency><dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>code-star-alpha</artifactId>
    <version>2.0.0-alpha.1</version>
</dependency>
<dependency>
    <groupId>software.constructs</groupId>
    <artifactId>constructs</artifactId>
    <version>10.0.0</version>
</dependency>

Installez les nouvelles dépendances en exécutantmvn package.

Modifiez votre code pour effectuer les opérations suivantes :

  • Importer Construct depuis la nouvelle software.constructs bibliothèque

  • Importez des classes de base, telles que Stack etApp, depuis software.amazon.awscdk

  • Importer des constructions de service depuis software.amazon.awscdk.services

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.App;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.codestar.alpha.GitHubRepository;
C#

Le moyen le plus simple de mettre à niveau les dépendances d'une CDK application C# consiste à modifier le .csproj fichier manuellement. Supprimez toutes les références aux Amazon.CDK.* packages stables et remplacez-les par des références aux Constructs packages Amazon.CDK.Lib et.

Les constructions expérimentales sont fournies dans des packages séparés, versionnés indépendamment, dont les noms se terminent par alpha et un numéro de version alpha. Le numéro de version alpha correspond à la première version aws-cdk-lib avec laquelle ils sont compatibles. Ici, nous nous sommes concentrés sur la version aws-codestar 2.0.0-alpha.1.

<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" />
<PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

Installez les nouvelles dépendances en exécutantdotnet restore.

Modifiez les importations dans vos fichiers source comme suit.

using Constructs;                   // for Construct class
using Amazon.CDK;                   // for core classes like App and Stack
using Amazon.CDK.AWS.S3;            // for stable constructs like Bucket
using Amazon.CDK.Codestar.Alpha;    // for experimental constructs
Go

Problème go get pour mettre à jour vos dépendances vers la dernière version et mettre à jour le .mod fichier de votre projet.

Tester votre application migrée avant de la déployer

Avant de déployer vos piles, utilisez-le cdk diff pour vérifier l'absence de modifications inattendues des ressources. Aucune modification de la logique IDs (entraînant le remplacement des ressources) n'est attendue.

Les changements attendus incluent, sans toutefois s'y limiter :

  • Modifications apportées à la CDKMetadata ressource.

  • Hashs d'actifs mis à jour.

  • Changements liés au nouveau style de synthèse des piles. S'applique si votre application utilisait l'ancien synthétiseur Stack dans la version 1. (La CDK v2 ne prend pas en charge l'ancien synthétiseur Stack.)

  • L'ajout d'une CheckBootstrapVersion règle.

Les modifications inattendues ne sont généralement pas causées par la mise à niveau vers la AWS CDK version v2 en elle-même. Ils sont généralement le résultat d'un comportement obsolète qui a été précédemment modifié par des indicateurs de fonctionnalité. Il s'agit d'un symptôme de mise à niveau à partir d'une version CDK antérieure à environ 1.85.x. Vous constaterez les mêmes modifications lors de la mise à niveau vers la dernière version v1.x. Vous pouvez généralement résoudre ce problème en procédant comme suit :

  1. Mettez à jour votre application vers la dernière version v1.x

  2. Supprimer les drapeaux de fonctionnalités

  3. Modifiez votre code si nécessaire

  4. Déploiement

  5. Passez à la version v2

Note

Si votre application mise à niveau n'est pas déployable après la mise à niveau en deux étapes, signalez le problème.

Lorsque vous êtes prêt à déployer les piles dans votre application, envisagez d'abord d'en déployer une copie afin de pouvoir la tester. Le moyen le plus simple de le faire est de le déployer dans une autre région. Cependant, vous pouvez également modifier le nombre IDs de vos piles. Après le test, assurez-vous de détruire la copie de test aveccdk destroy.

Résolution des problèmes

TypeScript 'from' expectedou ';' expected erreur lors des importations

Passez à la version TypeScript 3.8 ou ultérieure.

Exécutez « cdk bootstrap »

Si le message d'erreur suivant s'affiche :

❌  MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
    at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)

AWS CDK La v2 nécessite une pile de bootstrap mise à jour, et en outre, tous les déploiements de la v2 nécessitent des ressources de bootstrap. (Avec la version 1, vous pouvez déployer des piles simples sans amorçage.) Consultez AWS CDK bootstrap pour plus de détails.

Trouver des piles v1

Lors de la migration de votre CDK application de la v1 vers la v2, vous souhaiterez peut-être identifier les AWS CloudFormation piles déployées créées à l'aide de la version v1. Pour ce faire, exécutez la commande suivante : 

npx awscdk-v1-stack-finder

Pour plus de détails sur l'utilisation, consultez le READMEawscdk-v1-stack-finder.