AWS Versionnage du CDK - AWS Kit de développement Cloud (AWS CDK) v2
AWS Compatibilité avec le kit CDKAWS Gestion des versions de la bibliothèque ConstructAWS Clarifications relatives au versionnement sémantique de la bibliothèque ConstructStabilité des liaisons linguistiques

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 Versionnage du CDK

Cette rubrique fournit des informations de référence sur la manière dont le AWS Cloud Development Kit (AWS CDK) gère le versionnement.

Les numéros de version se composent de trois parties numériques : majeure. mineur. patch, et suivez globalement les principes de versionnement sémantique avec quelques mises en garde décrites dans les clarifications de version sémantiques de AWS Construct Library. Cela signifie que les modifications majeures que APIs nous considérons comme stables sont limitées aux versions majeures.

Les versions mineures et les correctifs sont rétrocompatibles. Le code écrit dans une version précédente avec la même version majeure peut être mis à niveau vers une version plus récente au sein de la même version majeure. Il continuera à être créé et à fonctionner, produisant un résultat fonctionnellement équivalent. Pour certains cas d'utilisation avancés, de petites modifications de votre code seront nécessaires, comme indiqué dans la rubrique suivante.

AWS Compatibilité avec le kit CDK

Chaque version de la bibliothèque AWS Construct (aws-cdk-lib) principale est compatible avec les versions AWS CDK Toolkit CLI (aws-cdk-cli) et Toolkit Library (@aws-cdk/toolkit-lib) qui étaient en vigueur au moment de la publication de la bibliothèque AWS Construct. Il est également compatible avec toute version plus récente du kit d'outils AWS CDK. Chaque version de la bibliothèque AWS Construct conserve cette compatibilité jusqu'à la date de fin de vie de la bibliothèque. Par conséquent, tant que vous utilisez une version compatible de AWS Construct Library, vous pouvez toujours mettre à niveau votre version du AWS CDK Toolkit en toute sécurité.

Chaque version de la bibliothèque AWS Construct peut également fonctionner avec des versions du kit d'outils AWS CDK antérieures à la version en cours au moment de la publication de la bibliothèque AWS Construct. Toutefois, cela n'est pas garanti. La compatibilité dépend de la version du schéma d'assemblage cloud de la bibliothèque AWS Construct. Le AWS CDK génère un assemblage cloud lors de la synthèse et le AWS CDK Toolkit l'utilise pour le déploiement. Le schéma qui définit le format de l'assemblage cloud est strictement spécifié et versionné. Par conséquent, une ancienne version du kit d'outils AWS CDK devrait prendre en charge la version du schéma d'assemblage cloud de la bibliothèque AWS Construct pour être compatible.

Lorsque la version d'assemblage cloud requise par la bibliothèque AWS Construct n'est pas compatible avec la version prise en charge par le AWS CDK Toolkit, vous recevez un message d'erreur du type suivant :

Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.
    Please upgrade your CLI in order to interact with this app.

Pour résoudre cette erreur, mettez à jour le kit d'outils AWS CDK vers une version compatible avec la version d'assemblage cloud requise ou vers la dernière version disponible. L'alternative (rétrograder les modules de la bibliothèque AWS Construct que votre application utilise) n'est généralement pas recommandée.

Note

Pour plus d'informations sur les combinaisons exactes de versions qui fonctionnent ensemble, consultez le tableau de compatibilité dans le aws-cdk-cli GitHub référentiel.

AWS Gestion des versions de la bibliothèque Construct

Les modules de la bibliothèque AWS Construct passent par différentes étapes au fur et à mesure qu'ils passent du concept à l'API mature. Les différentes étapes offrent différents degrés de stabilité de l'API dans les versions suivantes du AWS CDK.

À l'exception des scénarios où les mises en garde décrites dans la rubrique suivante s'appliquent, APIs la bibliothèque principale de AWS Construct (aws-cdk-lib) est stable et la bibliothèque suit globalement les principes de versionnement sémantique. La bibliothèque inclut des constructions AWS CloudFormation (L1) pour tous les AWS services, qui sont générées automatiquement à partir de schémas de fournisseurs de CloudFormation ressources et peuvent parfois inclure des mises à jour incompatibles avec les versions antérieures. Il inclut également des constructions de niveau supérieur (L2 et L3) et les classes CDK de base telles que App etStack, qui sont toutes stables. APIs ne seront pas supprimés de ce package (bien qu'ils puissent être obsolètes) avant la prochaine version majeure du CDK. Lorsqu'une modification radicale est requise pour une API stable, une toute nouvelle API sera ajoutée.

Les nouveaux services en APIs cours de développement pour un service déjà intégré aws-cdk-lib sont identifiés à l'aide d'un Beta<N> suffixe, qui N commence à 1 et est incrémenté à chaque modification importante apportée à la nouvelle API. Beta<N> APIs ne sont jamais supprimés, mais uniquement obsolètes, de sorte que votre application existante continue de fonctionner avec les nouvelles versions de. aws-cdk-lib Lorsque l'API est jugée stable, une nouvelle API sans Beta<N> suffixe est ajoutée.

Lorsque des niveaux supérieurs (L2 ou L3) APIs commencent à être développés pour un AWS service qui ne comportait auparavant que la couche L1 APIs, ceux-ci APIs sont initialement distribués dans un package séparé. Le nom d'un tel package possède le suffixe « Alpha », et sa version correspond à la première version compatible avec une alpha sous-version. aws-cdk-lib Lorsque le module prend en charge les cas d'utilisation prévus, APIs il est ajouté àaws-cdk-lib.

AWS Clarifications relatives au versionnement sémantique de la bibliothèque Construct

Bien que la bibliothèque AWS Construct suive globalement les principes de versionnement sémantique, certaines mises en garde importantes sont spécifiques à notre implémentation. En général, la bibliothèque AWS Construct assure la stabilité pour les utilisateurs d'API, mais ajoute parfois des charges supplémentaires aux auteurs de constructions afin de permettre l'évolution nécessaire du framework.

  • Changements ayant un impact sur la sécurité

    Pour respecter notre barre de sécurité, il se peut que nous soyons tenus de les modifier de APIs manière rétroincompatible ou de les supprimer complètement. Cela empêche l'utilisation APIs des personnes concernées et oblige les implémentations à être mises à jour.

  • Les fonctionnalités sont décrites par intention

    Notre objectif est de minimiser les changements inattendus, mais nous privilégions l'intention par rapport à la stabilité de la mise en œuvre. La AWS bibliothèque de constructions ne garantit pas que les constructions soient toujours synthétisées exactement selon le même CloudFormation modèle ou utilisent exactement le même ensemble de ressources. Cela s'applique particulièrement aux constructions de niveau supérieur, où le même objectif peut souvent être atteint de différentes manières.

  • Implémentation d'interfaces et de classes abstraites

    Les interfaces et les classes abstraites de la bibliothèque AWS Construct sont stables pour les consommateurs, mais pas pour les implémenteurs. Cela signifie que vous pouvez compter en toute sécurité sur des interfaces fournissant s3.IBucket au moins les mêmes fonctionnalités qu'au moment (version AWS Construct Library) où vous avez commencé à utiliser l'interface ou la classe abstraite. Cependant, périodiquement, de nouveaux membres (abstraits) seront ajoutés aux interfaces et aux classes abstraites. Pour quiconque les implémente, cela crée une charge de mise en œuvre supplémentaire à prendre en compte lors de la mise à niveau, car l'implémentation n'implémenterait pas encore les nouveaux membres. Traiter strictement les ajouts aux interfaces et aux classes abstraites pour les implémenteurs comme des modifications radicales limiterait indûment l'évolutivité de la bibliothèque Construct. AWS Dans la plupart des cas, les implémenteurs devraient préférer étendre des classes concrètes telles ques3.Bucket.

  • Constructions L1, code généré et autres constructions APIs marquées comme externes

    Certaines parties de la bibliothèque AWS Construct sont générées à partir de sources de données provenant directement AWS des services. Pour les APIs aligner sur la réalité, le code généré peut contenir des modifications incompatibles avec les versions antérieures. La plupart du temps, les sources de données sont mises à jour pour refléter correctement la réalité et corriger les représentations incorrectes. Vos IDE s' IntelliSense afficheront en externe APIs avec l'@stability — externalannotation.

  • Liaisons linguistiques spécifiques

    Les liaisons linguistiques peuvent contenir des modifications incompatibles avec les versions antérieures dans un nombre très limité de situations. Cela est dû à des modifications de type en amont qui sont rétrocompatibles dans d'autres langues prises en charge. Ces modifications de types sont autorisées, car le contraire limiterait considérablement l'évolutivité de la bibliothèque.

    La liste suivante décrit toutes les instances connues :

    • Golang - Passage d'une tranche typée à une tranche quelconque : une liste d'un seul type se transforme en une liste de plusieurs types (types d'union inclus). TypeScript DansGo, ils sont saisis sous la forme d'une tranche de any (*[]any). En raison des règles d'attribution de saisie de Go, le passage de *[]string à n'est pas une conversion automatique. Par conséquent, cet élargissement de type nécessite une modification du code du consommateur. Consultez la section Utilisation de n'importe quelle tranche pour connaître les stratégies.

Stabilité des liaisons linguistiques

Au fil du temps, il se peut que nous ajoutions le support au AWS CDK pour d'autres langages de programmation. Bien que l'API décrite dans toutes les langues soit la même, la façon dont l'API est exprimée varie selon la langue et peut changer au fur et à mesure que le support linguistique évolue. Pour cette raison, les liaisons linguistiques sont considérées comme expérimentales pendant un certain temps jusqu'à ce qu'elles soient considérées comme prêtes à être utilisées en production.

Langue Stabilité

TypeScript

Stable

JavaScript

Stable

Python

Stable

Java

Stable

C#/.NET

Stable

Go

Stable