Il s'agit du guide du développeur 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 les piles et en réorganisant votre application, tout en préservant les ressources déployées au lieu de les remplacer. Cette fonctionnalité vous permet de maintenir les bonnes pratiques d'ingénierie logicielle sans entraîner de remplacements involontaires de ressources.

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

Lorsque vous déployez une application CDK, AWS CloudFormation identifie les ressources par leurs ID logiques. Le AWS CDK génère ces identifiants logiques en fonction de l'ID de construction et de son chemin dans l'arbre de construction. Si vous modifiez l'identifiant 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 avec état 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.

La refactorisation du CDK permet de relever ce défi en :

Vous pouvez effectuer la refactorisation du CDK à l'aide de la cdk refactor commande CDK CLI ou de l'action de la bibliothèque CDK Toolkit. 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 Toolkit, voir Exécuter des actions programmatiques à l'aide de la bibliothèque CDK Toolkit.

Avantages du refactoring CDK

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

Comment fonctionne la commande CDK CLI cdk refactor

Tout d'abord, vous déployez votre application CDK initiale pour établir les ressources de base de votre AWS compte. Après avoir remanié votre code CDK, par exemple en renommant des constructions ou en déplaçant des ressources entre les piles, utilisez la cdk refactor commande pour démarrer 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é, avec des différences uniquement par leur emplacement dans l'arbre de construction. La CLI CDK génère ensuite un plan de refactorisation qui met en correspondance 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 les ID logiques 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 de 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 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 refactorisation du CDK, ces modifications entraîneraient la création AWS CloudFormation de nouvelles ressources et la suppression des anciennes, car les identifiants logiques seraient modifiés :

Avec le refactoring CDK, la CLI CDK détecte ces changements de chemin et utilise les capacités de refactorisation AWS CloudFormation de ses fonctionnalités pour préserver les ressources sous-jacentes. Lorsque vous exécutezcdk refactor, la CLI vous montre 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 saisissanty, l'interface de ligne de commande CDK affiche 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 leurs identifiants logiques pour qu'ils correspondent à votre nouvelle structure de code.

Le même mappage est également affiché dans la sortie de la cdk diff commande, organisée 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 à refactoriser le CDK

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

Utiliser des fichiers de remplacement pour résoudre les ambiguïtés lors de 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 dans certains cas, la CLI peut rencontrer des ambiguïtés qu'elle ne peut résoudre seule. Pour fournir des conseils à l'interface de ligne de commande 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 de la refactorisation 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 entre les piles au sein de l'environnement de développement ou de production, mais pas du développement à la production ou vice versa.

Gestion des ressources destinées à ê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 gérées séparément des opérations de refactoring.

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

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

Considérations générales et limites

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

Refactorisation à l'aide de pipelines CI/CD

Pour utiliser la fonctionnalité de refactoring dans les CI/CD pipelines, vous devez être en mesure d'exécuter la CLI CDK dans le cadre de votre pipeline. Voici quelques considérations importantes à prendre en compte pour intégrer le refactoring à 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 CDK Toolkit, voir Exécuter des actions programmatiques à l'aide de la bibliothèque CDK Toolkit.