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.

Préservez les ressources déployées lors de la refactorisation du code CDK

Grâce à la refactorisation du AWS Cloud Development Kit (AWS CDK), vous pouvez refactoriser votre code CDK, par exemple en renommant des constructions, en déplaçant des ressources entre des piles et en réorganisant votre application, tout en préservant les ressources déployées au lieu de les remplacer. Cette fonctionnalité vous aide à maintenir les bonnes pratiques d'ingénierie logicielle sans entraîner le remplacement involontaire des ressources.

Qu'est-ce que le refactoring CDK avec préservation des ressources ?

Lorsque vous déployez une application CDK, elle AWS CloudFormation identifie les ressources en fonction de leur logique IDs. Le AWS CDK génère ces logiques en IDs fonction de l'ID de construction et de son chemin dans l'arbre de construction. Si vous modifiez l'ID d'une construction ou si vous la déplacez vers un autre emplacement dans votre code, cela est AWS CloudFormation généralement interprété comme une demande de création d'une nouvelle ressource et de suppression de l'ancienne. Pour les ressources dynamiques telles que les bases de données, les compartiments de stockage ou les files d'attente, ce remplacement peut entraîner des interruptions de service ou des pertes de données.

Le refactoring CDK répond à ce défi en :

Vous pouvez effectuer une refactorisation du CDK à l'aide de la cdk refactor commande CDK CLI ou de l'action de la bibliothèque du kit d'outils CDK. refactor Ce guide traite principalement de l'approche CLI, mais les principes sous-jacents s'appliquent aux deux méthodes. Pour plus d'informations sur l'utilisation de la bibliothèque de boîtes à outils, voir Exécuter des actions de programmation à l'aide de la bibliothèque de boîtes à outils CDK.

Avantages du refactoring CDK

La refactorisation des CDK offre les avantages suivants aux développeurs de CDK : AWS

Fonctionnement de la cdk refactor commande CDK CLI

Tout d'abord, vous déployez votre application CDK initiale pour établir les ressources de base de votre AWS compte. Après avoir refactorisé votre code CDK, par exemple en renommant des constructions ou en déplaçant des ressources entre des piles, utilisez la cdk refactor commande pour commencer le processus de refactorisation de vos ressources déployées.

Lorsque vous exécutez la commande refactor, la CLI CDK détecte vos modifications locales en comparant votre code actuel à l'état déployé. Il vérifie que votre application CDK contient exactement le même ensemble de ressources que l'état déployé, les différences se limitant à leur emplacement dans l'arbre de construction. La CLI CDK génère ensuite un plan de refactorisation qui mappe les anciens emplacements des ressources avec leurs nouveaux emplacements. La CLI CDK vous montre les modifications proposées et, après votre confirmation, utilise AWS CloudFormation l'API de refactorisation pour mettre à jour la logique IDs des ressources sans les remplacer.

Dans les coulisses, la CLI CDK détermine quelles ressources ont été déplacées en comparant leurs propriétés et leurs dépendances, en identifiant les ressources qui sont fonctionnellement équivalentes mais qui ont des chemins différents dans l'arbre de construction. S'il détecte des ajouts, des suppressions ou des modifications de ressources, l'opération de refactorisation sera rejetée avec un message d'erreur.

Exemple de préservation des ressources lors de la refactorisation du code CDK

Dans cet exemple, nous préservons les ressources déployées tout en refactorisant notre code CDK à l'aide de la commande CDK CLI. cdk refactor

Notre exemple d'application CDK consiste en une pile unique contenant un compartiment S3, une CloudFront distribution et une fonction Lambda. L'arbre de construction est structuré comme suit :

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

Voici un exemple du code de notre application :

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Maintenant, imaginez que vous vouliez refactoriser ce code pour :

Après la refactorisation, l'arbre de construction ressemblerait à ceci :

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

Et le code refactorisé serait :

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

Sans la refactorisation du CDK, ces modifications entraîneraient la création AWS CloudFormation de nouvelles ressources et la suppression des anciennes, car la logique IDs changerait :

Avec le refactoring CDK, la CLI CDK détecte ces changements de chemin et utilise les capacités de refactorisation AWS CloudFormation du CDK pour préserver les ressources sous-jacentes. Lorsque vous l'exécutezcdk refactor, la CLI vous indique les modifications qu'elle va apporter :

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

Lorsque vous confirmez en entranty, la CLI CDK indique la progression de l'opération de refactorisation :

Refactoring...
✅  Stack refactor complete

Après confirmation, la CLI CDK exécute l'opération de refactorisation, préservant les deux ressources tout en mettant à jour leur logique IDs pour qu'elle corresponde à votre nouvelle structure de code.

Le même mappage est également affiché dans la sortie de la cdk diff commande, organisé par pile :

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

Commencez avec le refactoring des CDK

Pour commencer à refactoriser, remplissez les conditions préalables suivantes :

Utiliser des fichiers de remplacement pour résoudre les ambiguïtés liées à la refactorisation

La CLI CDK calcule automatiquement tous les mappages de ressources en comparant votre code aux ressources déployées. Dans la plupart des cas, cette détection automatique fonctionne bien, mais il existe des situations dans lesquelles la CLI peut rencontrer des ambiguïtés qu'elle ne peut résoudre seule. Pour fournir des conseils à la CLI CDK, utilisez un fichier de remplacement.

Refactorisation des piles dans plusieurs environnements

Une application CDK peut contenir plusieurs piles déployées dans différents environnements (AWS comptes et régions). Lors de la préservation des ressources lors du refactoring dans de telles applications, la CLI CDK gère les environnements d'une manière spécifique :

Ce comportement garantit que les ressources restent dans leur AWS compte et leur région d'origine, ce qui est nécessaire car les CloudFormation ressources ne peuvent pas être déplacées physiquement au-delà des limites du compte ou de la région.

Par exemple, si votre application CDK définit des piles pour les environnements de développement et de production, l'opération de refactorisation sera effectuée indépendamment dans chaque environnement. Les ressources peuvent être déplacées d'une pile à l'autre au sein de l'environnement de développement ou au sein de l'environnement de production, mais pas du développement à la production ou vice versa.

Gestion des ressources conçues pour être remplacées

Certaines constructions CDK s'appuient sur le comportement CloudFormation de remplacement des ressources dans le cadre de leur conception. Par exemple, les Version constructions d'API Gateway Deployment et de Lambda sont conçues pour créer de nouvelles ressources lorsque leurs propriétés changent.

Lors de la refactorisation, n'incluez aucune modification susceptible d'entraîner le remplacement des ressources. Dans le cas contraire, la CLI CDK peut détecter et préserver ces ressources. Cela signifie que les ressources conçues pour être remplacées doivent être traitées séparément des opérations de refactorisation.

Pour gérer correctement les ressources destinées à être remplacées :

Cette approche en deux étapes garantit que les ressources conçues pour être remplacées sont correctement gérées, tout en vous permettant de bénéficier de la refactorisation CDK pour d'autres ressources.

Considérations générales et limites

Lorsque vous préservez les ressources lors de la refactorisation du CDK, tenez compte des considérations suivantes :

Refactorisation avec des pipelines CI/CD

Pour utiliser la fonctionnalité de refactorisation dans les CI/CD pipelines, vous devez être en mesure d'exécuter la CLI CDK dans le cadre de votre pipeline. Voici quelques points importants à prendre en compte pour intégrer le refactoring dans votre CI/CD flux de travail.

Ressources connexes

Pour plus d'informations sur les options et les arguments de la cdk refactor commande CDK CLI, consultez cdk refactor .

Pour commencer à utiliser l'refactoraction de la bibliothèque du kit d'outils CDK, voir Exécuter des actions de programmation à l'aide de la bibliothèque du kit d'outils CDK.