Ceci est le guide du AWS CDK développeur de la version 2. 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.
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 AWS CDK v1 et 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 bibliothèques CDK.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 unalpha
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 unalpha
suffixe. Les constructions sont déplacéesaws-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 auaws-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 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 parBeta2
Beta3
, et ainsi de suite lorsque des modifications importantes sont nécessaires.) Une version de l'API sans suffixe est ajoutée lorsque l'API est désignée 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 que l'API est finalisée, la méthodegrantPower()
(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 de l'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 connexes APIs, vous devez déclarer leconstructs
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'application CDK, d'autres modifications peuvent être nécessaires. Pour plus de détails, consultez la RFC. -
Les propriétés, méthodes et types obsolètes de la AWS CDK version v1.x et de sa bibliothèque de construction ont été complètement supprimés de l'API CDK v2. 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 du
CDK 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 CDK v2. 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 CDK v1 dans des circonstances très spécifiques. Pour de plus amples informations, veuillez consulter Mise à jour des indicateurs de fonctionnalités.
-
Avec CDK 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. Le CDK 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 kit d'outils CDK est requise pour être utilisée avec CDK v2. Maintenant que le CDK v2 est généralement disponible, la version 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 projets CDK v1. Pour effectuer une mise à niveau, problème
npm install -g aws-cdk
.
Mise à niveau depuis AWS CDK v2 Developer Preview
Si vous utilisez le 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.
npm install
ou yarn install
Après avoir mis à jour vos dépendances, lancez la mise npm update -g aws-cdk
à jour du kit d'outils CDK vers la version finale.
Migration de la AWS CDK v1 vers le CDK v2
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 : passez d'abord à 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
-
@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.
Compatibilité avec le kit CDK
Le CDK v2 nécessite la version v2 ou ultérieure du kit d'outils CDK. Cette version est rétrocompatible avec les applications CDK v1. Par conséquent, vous pouvez utiliser une seule version installée dans le monde entier de CDK Toolkit 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 projets CDK 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 kit d'outils CDK, utilisez la version v1 ou v2 du kit d'outils CDK comme npx vous le souhaitez.
npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript
Astuce
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.
Applications
Pour les applications CDK, 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 les CDK v1 et v2 avec une seule bibliothèque. Pour continuer à soutenir les clients qui utilisent encore 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 du CDK v1 lui-même, qui est entré en maintenance le 1er juin 2022 et arrivera à expiration end-of-life 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
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.
-
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 du 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 :
-
Mettez à jour votre application vers la dernière version v1.x
-
Supprimer les drapeaux de fonctionnalités
-
Révisez votre code si nécessaire
-
Déploiement
-
Passez à la version v2
Note
Si votre application mise à niveau n'est pas déployable après la mise à niveau en deux étapes, signalez
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' expected
ou ';' 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 application CDK de la v1 à 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 fichier README d'awscdk-v1-stack-finder.