Migrer les ressources et les AWS CloudFormation modèles existants vers le AWS CDK - AWS Kit de développement Cloud (AWS CDK) v2
Comment fonctionne la migrationAvantages de CDK MigrateConsidérationsPrérequisCommencez avec CDK MigrateMigrer à partir d'une AWS CloudFormation pileMigrer à partir d'un AWS CloudFormation modèleMigrer à partir des ressources déployéesGérez et déployez votre application CDK

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.

Migrer les ressources et les AWS CloudFormation modèles existants vers le AWS CDK

La fonctionnalité CDK Migrate est en version préliminaire pour AWS CDK et est sujette à modification.

Utilisez l'interface de ligne de commande (AWS CDK AWS CLI) du AWS Cloud Development Kit (CDK) pour migrer les AWS ressources déployées, les AWS CloudFormation piles déployées et les AWS CloudFormation modèles locaux vers le CDK. AWS

Comment fonctionne la migration

Utilisez la cdk migrate commande AWS CDK CLI pour effectuer une migration à partir des sources suivantes :

  • AWS Ressources déployées.

  • AWS CloudFormation Stacks déployés.

  • AWS CloudFormation Modèles locaux.

AWS Ressources déployées

Vous pouvez migrer AWS les ressources déployées depuis un environnement spécifique (AWS compte et AWS région) qui ne sont pas associées à une AWS CloudFormation pile.

La CLI AWS CDK utilise le service de génération IaC pour rechercher les ressources de votre AWS environnement afin de recueillir des informations détaillées sur les ressources. Pour en savoir plus sur le générateur IaC, consultez la section Génération de modèles pour les ressources existantes dans le guide de AWS CloudFormation l'utilisateur.

Après avoir collecté les détails des ressources, la CLI AWS CDK crée une nouvelle application CDK qui inclut une pile unique contenant vos ressources migrées.

AWS CloudFormation Stacks déployés

Vous pouvez migrer une seule AWS CloudFormation pile vers une nouvelle application AWS CDK. La CLI AWS CDK récupérera le AWS CloudFormation modèle de votre pile et créera une nouvelle application CDK. L'application CDK sera composée d'une seule pile contenant votre pile migrée. AWS CloudFormation

AWS CloudFormation Modèles locaux

Vous pouvez effectuer la migration à partir d'un AWS CloudFormation modèle local. Les modèles locaux peuvent contenir ou non des ressources déployées. La CLI AWS CDK créera une nouvelle application CDK contenant une pile unique contenant vos ressources.

Après la migration, vous pouvez gérer, modifier et déployer votre application CDK pour approvisionner ou mettre AWS CloudFormation à jour vos ressources.

Avantages de CDK Migrate

La migration des ressources vers le AWS CDK a toujours été un processus manuel qui nécessite du temps et de l'expertise avec AWS CloudFormation le AWS CDK pour commencer. Avec CDK Migrate, la AWS CLI CDK facilite la majeure partie des efforts de migration pour vous en un rien de temps. CDK Migrate vous permettra de commencer rapidement à utiliser le AWS CDK pour développer et gérer des applications nouvelles et existantes sur. AWS

Considérations

Considérations d’ordre général

CDK Migrate ou CDK Import

La cdk import commande peut importer des ressources déployées dans une application CDK nouvelle ou existante. Lors de l'importation, chaque ressource devra être définie manuellement en tant que construction L1 dans votre application. Nous vous recommandons d'cdk importutiliser cette option pour importer une ou plusieurs ressources à la fois dans une application CDK nouvelle ou existante. Pour en savoir plus, voir Importer des ressources existantes dans une pile.

La cdk migrate commande migre des ressources déployées, des AWS CloudFormation piles déployées ou des AWS CloudFormation modèles locaux vers une nouvelle application CDK. Pendant la migration, la CLI AWS CDK permet cdk import d'importer vos ressources dans la nouvelle application CDK. La CLI AWS CDK génère également des constructions L1 pour chaque ressource pour vous. Nous vous recommandons de l'utiliser cdk migrate lors de l'importation depuis une source de migration prise en charge vers une nouvelle application AWS CDK.

CDK Migrate crée uniquement des constructions L1

L'application CDK nouvellement créée inclura uniquement les constructions L1. Vous pouvez ajouter des constructions de niveau supérieur à votre application après la migration.

CDK Migrate crée des applications CDK contenant une seule pile

L'application CDK nouvellement créée contiendra une seule pile.

Lors de la migration des ressources déployées, toutes les ressources migrées seront contenues dans une pile unique dans la nouvelle application CDK.

Lors de la migration de AWS CloudFormation piles, vous ne pouvez migrer qu'une seule AWS CloudFormation pile vers une seule pile dans la nouvelle application CDK.

Migration des actifs

Les actifs du projet, tels que le code AWS Lambda, ne migreront pas directement vers la nouvelle application CDK. Après la migration, vous pouvez spécifier les valeurs des actifs pour les inclure dans l'application CDK.

Migration de ressources dynamiques

Lorsque vous migrez des ressources dynamiques, telles que des bases de données et des compartiments Amazon Simple Storage Service (Amazon S3), vous souhaiterez le plus souvent migrer la ressource existante plutôt que d'en créer une nouvelle.

Pour migrer et préserver les ressources dynamiques, procédez comme suit :

  • Vérifiez que votre ressource dynamique prend en charge l'importation. Pour plus d'informations, consultez la section Support des types de ressources dans le Guide de AWS CloudFormation l'utilisateur.

  • Après la migration, vérifiez que l'ID logique de la ressource migrée dans la nouvelle application CDK correspond à l'ID logique de la ressource déployée.

  • Si vous migrez depuis une AWS CloudFormation pile, vérifiez que le nom de la pile dans la nouvelle application CDK correspond à la AWS CloudFormation pile.

  • Déployez l'application CDK en utilisant le même AWS compte et la même AWS région que ceux de la ressource migrée.

Considérations relatives à la migration à partir d'un modèle AWS CloudFormation

CDK Migrate prend en charge la migration d'un modèle unique

Lors de la migration AWS CloudFormation de modèles, vous pouvez sélectionner un seul modèle à migrer. Les modèles imbriqués ne sont pas pris en charge.

Migration de modèles dotés de fonctions intrinsèques

Lors de la migration à partir d'un AWS CloudFormation modèle qui utilise des fonctions intrinsèques, la AWS CLI CDK tente de faire migrer votre logique vers l'application CDK avec la classe. Fn Pour en savoir plus, consultez la classe Fn dans le Guide de référence de l'API AWS Cloud Development Kit (AWS CDK).

Considérations relatives à la migration à partir de ressources déployées

Limites de numérisation

Lorsque vous analysez votre environnement à la recherche de ressources, le générateur iAc est soumis à des limites spécifiques quant aux données qu'il peut récupérer et à des limites de quotas lors de l'analyse. Pour en savoir plus, consultez la section Considérations du guide de AWS CloudFormation l'utilisateur.

Prérequis

Avant d'utiliser la cdk migrate commande, effectuez toutes les étapes de configuration dans Getting started with the AWS CDK.

Commencez avec CDK Migrate

Pour commencer, exécutez la cdk migrate commande AWS CDK CLI depuis le répertoire de votre choix. Fournissez les options obligatoires et facultatives, en fonction du type de migration que vous effectuez.

Pour une liste complète et une description des options que vous pouvez utilisercdk migrate, consultez cdk migrate.

Voici quelques options importantes que vous souhaiterez peut-être proposer.

Nom de la pile

La seule option requise est--stack-name. Utilisez cette option pour spécifier le nom de la pile qui sera créée dans l'application AWS CDK après la migration. Le nom de la pile sera également utilisé comme nom de votre AWS CloudFormation pile lors du déploiement.

Langue

--languageÀ utiliser pour spécifier le langage de programmation de la nouvelle application CDK.

AWS compte et AWS région

La CLI AWS CDK récupère les informations de AWS compte et de AWS région à partir de sources par défaut. Pour plus d'informations, consultez Environnements pour le AWS CDK. Vous pouvez utiliser --account des --region options cdk migrate pour fournir d'autres valeurs.

Répertoire de sortie de votre nouveau projet CDK

Par défaut, la CLI AWS CDK crée un nouveau projet CDK dans votre répertoire de travail et utilise la valeur que vous fournissez --stack-name pour nommer le dossier du projet. Si un dossier portant le même nom existe actuellement, la CLI AWS CDK remplacera ce dossier.

Vous pouvez spécifier un chemin de sortie différent pour le nouveau dossier de projet CDK à l'aide de l'--output-pathoption.

Source de migration

Fournissez une option pour spécifier la source à partir de laquelle vous effectuez la migration.

  • --from-path— Migrez à partir d'un AWS CloudFormation modèle local.

  • --from-scan— Migrez à partir des ressources déployées dans un AWS compte et une AWS région.

  • --from-stack— Migrez depuis une AWS CloudFormation pile.

En fonction de votre source de migration, vous pouvez proposer des options supplémentaires pour personnaliser la cdk migrate commande.

Migrer à partir d'une AWS CloudFormation pile

Pour effectuer une migration à partir d'une AWS CloudFormation pile déployée, offrez l'--from-stackoption. Indiquez le nom de votre AWS CloudFormation stack déployé avec--stack-name. Voici un exemple :

$ cdk migrate --from-stack --stack-name "myCloudFormationStack"

La CLI AWS CDK effectuera les opérations suivantes :

  1. Récupérez le AWS CloudFormation modèle de votre stack déployé.

  2. Exécutez cdk init pour initialiser une nouvelle application CDK.

  3. Créez une pile dans l'application CDK qui contient votre pile migrée. AWS CloudFormation

Lorsque vous migrez depuis une AWS CloudFormation pile déployée, la CLI AWS CDK tente de faire correspondre la logique des ressources déployées IDs et le nom de la AWS CloudFormation pile déployée aux ressources migrées et à la pile dans la nouvelle application CDK.

Après la migration, vous pouvez gérer et modifier votre application CDK normalement. Lorsque vous déployez, AWS CloudFormation identifiera le déploiement comme une mise à jour de AWS CloudFormation pile en raison du nom de AWS CloudFormation pile correspondant. Les ressources associées à la logique correspondante IDs seront mises à jour. Pour plus d'informations sur le déploiement, consultez Gérer et déployer votre application CDK.

Migrer à partir d'un AWS CloudFormation modèle

CDK Migrate prend en charge la migration à partir de AWS CloudFormation modèles formatés en ou. JSON YAML

Pour effectuer une migration depuis un AWS CloudFormation modèle local, utilisez l'--from-pathoption et indiquez un chemin d'accès au modèle local. Vous devez également fournir l'--stack-nameoption requise. Voici un exemple :

$ cdk migrate --from-path "./template.json" --stack-name "myCloudFormationStack"

La CLI AWS CDK effectuera les opérations suivantes :

  1. Récupérez votre AWS CloudFormation modèle local.

  2. Exécutez cdk init pour initialiser une nouvelle application CDK.

  3. Créez une pile dans l'application CDK qui contient votre modèle migré. AWS CloudFormation

Après la migration, vous pouvez gérer et modifier votre application CDK normalement. Lors du déploiement, vous disposez des options suivantes :

  • Mettre à jour une AWS CloudFormation pile : si le AWS CloudFormation modèle local a déjà été déployé, vous pouvez mettre à jour la AWS CloudFormation pile déployée.

  • Déployer une nouvelle AWS CloudFormation pile : si le AWS CloudFormation modèle local n'a jamais été déployé, ou si vous souhaitez créer une nouvelle pile à partir d'un modèle précédemment déployé, vous pouvez déployer une nouvelle AWS CloudFormation pile.

Migrer depuis un modèle AWS SAM

Pour migrer depuis un modèle d'application AWS sans serveur (AWS SAM), vous devez d'abord le convertir en AWS CloudFormation modèle ou le déployer pour créer une AWS CloudFormation pile.

Pour convertir un modèle AWS SAM en AWS CloudFormation, vous pouvez utiliser la sam validate --debug commande AWS SAM CLI. Vous devrez peut-être le lint définir false dans votre samconfig.toml fichier avant d'exécuter cette commande.

Pour le convertir en AWS CloudFormation pile, déployez le modèle AWS SAM à l'aide de la CLI AWS SAM. Migrez ensuite depuis la pile déployée.

Migrer à partir des ressources déployées

Pour effectuer une migration à partir de AWS ressources déployées, offrez l'--from-scanoption. Vous devez également fournir l'--stack-nameoption requise. Voici un exemple :

$ cdk migrate --from-scan --stack-name "myCloudFormationStack"

La CLI AWS CDK effectuera les opérations suivantes :

  1. Scannez votre compte pour obtenir des informations sur les ressources et les propriétés — La CLI AWS CDK utilise le générateur IaC pour scanner votre compte et recueillir des informations.

  2. Générer un AWS CloudFormation modèle — Après la numérisation, la CLI AWS CDK utilise le générateur IaC pour créer un AWS CloudFormation modèle.

  3. Initialisez une nouvelle application CDK et migrez votre modèle — La CLI AWS CDK cdk init s'exécute pour initialiser une AWS nouvelle application CDK et migre AWS CloudFormation votre modèle vers l'application CDK sous la forme d'une pile unique.

Utiliser des filtres

Par défaut, la CLI AWS CDK analyse l'ensemble de l' AWS environnement et migre les ressources jusqu'à la limite de quota maximale du générateur IaC. Vous pouvez fournir des filtres avec la CLI AWS CDK pour spécifier les critères selon lesquels les ressources seront migrées de votre compte vers la nouvelle application CDK. Pour en savoir plus, veuillez consulter la section --filter .

Recherche de ressources avec le générateur IaC

Selon le nombre de ressources de votre compte, la numérisation peut prendre quelques minutes. Une barre de progression s'affiche pendant le processus de numérisation.

Types de ressources pris en charge

La CLI AWS CDK migrera les ressources prises en charge par le générateur IaC. Pour une liste complète, consultez la section Support des types de ressources dans le guide de AWS CloudFormation l'utilisateur.

Résolution des propriétés en écriture seule

Certaines ressources prises en charge contiennent des propriétés en écriture seule. Ces propriétés peuvent être écrites pour configurer la propriété, mais ne peuvent pas être lues par le générateur IaC ou AWS CloudFormation pour obtenir la valeur. Par exemple, une propriété utilisée pour spécifier un mot de passe de base de données peut être en écriture seule pour des raisons de sécurité.

Lors de l'analyse des ressources pendant la migration, le générateur iAC détecte les ressources susceptibles de contenir des propriétés en écriture seule et les classe dans l'un des types suivants :

  • MUTUALLY_EXCLUSIVE_PROPERTIES— Il s'agit de propriétés en écriture seule pour une ressource spécifique qui sont interchangeables et ont un objectif similaire. L'une des propriétés mutuellement exclusives est requise pour configurer votre ressource. Par exemple, les propriétés S3BucketImageUri, et d'une AWS::Lambda::Function ressource sont des ZipFile propriétés en écriture seule qui s'excluent mutuellement. N'importe lequel d'entre eux peut être utilisé pour spécifier les actifs de votre fonction, mais vous devez en utiliser un.

  • MUTUALLY_EXCLUSIVE_TYPES— Il s'agit de propriétés en écriture seule obligatoires qui acceptent plusieurs types de configuration. Par exemple, la Body propriété d'une AWS::ApiGateway::RestApi ressource accepte un type d'objet ou de chaîne.

  • UNSUPPORTED_PROPERTIES— Il s'agit de propriétés en écriture seule qui n'entrent pas dans les deux autres catégories. Il s'agit soit de propriétés facultatives, soit de propriétés obligatoires qui acceptent un ensemble d'objets.

Pour plus d'informations sur les propriétés en écriture seule et sur la façon dont le générateur iAC les gère lors de la recherche de ressources déployées et de la création de AWS CloudFormation modèles, consultez les sections Générateur iAc et propriétés en écriture seule dans le Guide de l'utilisateur. AWS CloudFormation

Après la migration, vous devez spécifier des valeurs de propriétés en écriture seule dans la nouvelle application CDK. La CLI AWS CDK ajoutera une section Avertissements au ReadMe fichier du projet CDK pour documenter toutes les propriétés en écriture seule identifiées par le générateur IaC. Voici un exemple :

# Welcome to your CDK TypeScript project
...
## Warnings
### Write-only properties
Write-only properties are resource property values that can be written to but can't be read by AWS CloudFormation or CDK Migrate. For more information, see [IaC generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html).

Write-only properties discovered during migration are organized here by resource ID and categorized by write-only property type. Resolve write-only properties by providing property values in your CDK app. For guidance, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
### MyLambdaFunction
- **UNSUPPORTED_PROPERTIES**:
  - SnapStart/ApplyOn: Applying SnapStart setting on function resource type.Possible values: [PublishedVersions, None]
This property can be replaced with other types
  - Code/S3ObjectVersion: For versioned objects, the version of the deployment package object to use.
This property can be replaced with other exclusive properties
- **MUTUALLY_EXCLUSIVE_PROPERTIES**:
  - Code/S3Bucket: An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
This property can be replaced with other exclusive properties
  - Code/S3Key: The Amazon S3 key of the deployment package.
This property can be replaced with other exclusive properties

  • Les avertissements sont organisés sous des en-têtes qui identifient l'ID logique de la ressource à laquelle ils sont associés.

  • Les avertissements sont classés par type. Ces types proviennent directement du générateur IaC.

Pour résoudre les propriétés en écriture seule

  1. Identifiez les propriétés en écriture seule à résoudre dans la section Avertissements du fichier de votre projet CDK. ReadMe Ici, vous pouvez prendre note des ressources de votre application CDK susceptibles de contenir des propriétés en écriture seule et identifier les types de propriétés en écriture seule découverts.

    1. Pour MUTUALLY_EXCLUSIVE_PROPERTIES déterminer la propriété mutuellement exclusive à configurer dans votre application AWS CDK.

    2. PourMUTUALLY_EXCLUSIVE_TYPES, déterminez le type accepté que vous utiliserez pour configurer la propriété.

    3. PourUNSUPPORTED_PROPERTIES, déterminez si la propriété est facultative ou obligatoire. Ensuite, configurez le cas échéant.

  2. Utilisez les instructions du générateur IaC et les propriétés en écriture seule pour faire référence à la signification des types d'avertissement.

  3. Dans votre application CDK, les valeurs des propriétés en écriture seule à résoudre seront également spécifiées dans la Props section de votre application. Indiquez les valeurs correctes ici. Pour obtenir des descriptions et des conseils sur les propriétés, vous pouvez vous référer à la référence de l'API AWS CDK.

    Voici un exemple de Props section d'une application CDK migrée avec deux propriétés en écriture seule à résoudre :

    export interface MyTestAppStackProps extends cdk.StackProps {
  /**
   * The Amazon S3 key of the deployment package.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Keym8P82: string;
  /**
   * An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Bucketzidw8: string;
}

    Une fois que vous avez résolu toutes les valeurs de propriété en écriture seule, vous êtes prêt à préparer le déploiement.

Le fichier migrate.json

La CLI AWS CDK crée un migrate.json fichier dans votre projet AWS CDK pendant la migration. Ce fichier contient des informations de référence sur vos ressources déployées. Lorsque vous déployez votre application CDK pour la première fois, la AWS CLI CDK utilise ce fichier pour référencer vos ressources déployées, associe vos ressources à la nouvelle AWS CloudFormation pile et supprime le fichier.

Gérez et déployez votre application CDK

Lors de la migration vers le AWS CDK, il est possible que la nouvelle application CDK ne soit pas immédiatement prête à être déployée. Cette rubrique décrit les actions à prendre en compte lors de la gestion et du déploiement de votre nouvelle application CDK.

Préparation au déploiement

Avant le déploiement, vous devez préparer votre application CDK.

Synthétisez votre application

Utilisez la cdk synth commande pour synthétiser la pile de votre application CDK dans un AWS CloudFormation modèle.

Si vous avez migré à partir d'une AWS CloudFormation pile ou d'un modèle déployé, vous pouvez comparer le modèle synthétisé au modèle migré pour vérifier les valeurs des ressources et des propriétés.

Pour en savoir pluscdk synth, consultez Synthesize stacks.

Effectuez une différence

Si vous avez migré depuis une AWS CloudFormation pile déployée, vous pouvez utiliser la commande cdk diff pour comparer avec la pile de votre nouvelle application CDK.

Pour en savoir plus sur cdk diff, consultez la section Comparer les piles.

Bootstrap votre environnement

Si vous déployez depuis un AWS environnement pour la première fois, utilisez-le cdk bootstrap pour préparer votre environnement. Pour en savoir plus, consultez la section AWS Démarrage du CDK.

Déployez votre application CDK

Lorsque vous déployez une application CDK, la AWS CLI CDK utilise le AWS CloudFormation service pour provisionner vos ressources. Les ressources sont regroupées en une seule pile dans l'application CDK et sont déployées en une seule AWS CloudFormation pile.

Selon l'endroit d'où vous avez migré, vous pouvez effectuer un déploiement pour créer une nouvelle AWS CloudFormation pile ou mettre à jour une AWS CloudFormation pile existante.

Déployer pour créer une nouvelle AWS CloudFormation pile

Si vous avez migré à partir de ressources déployées, la AWS CLI CDK créera automatiquement une nouvelle AWS CloudFormation pile lors du déploiement. Vos ressources déployées seront incluses dans la nouvelle AWS CloudFormation pile.

Si vous avez migré à partir d'un AWS CloudFormation modèle local qui n'a jamais été déployé, la AWS CLI CDK créera automatiquement une nouvelle AWS CloudFormation pile lors du déploiement.

Si vous avez migré à partir d'une AWS CloudFormation pile déployée ou d'un AWS CloudFormation modèle local précédemment déployé, vous pouvez effectuer un déploiement pour créer une nouvelle AWS CloudFormation pile. Pour créer une nouvelle pile, procédez comme suit :

  • Déployez dans un nouvel AWS environnement. Cela consiste à utiliser un autre AWS compte ou à effectuer un déploiement dans une autre AWS région.

  • Si vous souhaitez déployer une nouvelle pile dans le même AWS environnement que la pile ou le modèle migré, vous devez modifier le nom de la pile dans votre application CDK pour lui attribuer une nouvelle valeur. Vous devez également modifier toute IDs la logique des ressources de votre application CDK. Vous pouvez ensuite le déployer dans le même environnement pour créer une nouvelle pile et de nouvelles ressources.

Déployer pour mettre à jour une AWS CloudFormation pile existante

Si vous avez migré à partir d'une AWS CloudFormation pile déployée ou d'un AWS CloudFormation modèle local précédemment déployé, vous pouvez effectuer un déploiement pour mettre à jour la AWS CloudFormation pile existante.

Vérifiez que le nom de la pile dans votre application CDK correspond au nom de la AWS CloudFormation pile déployée et déployez-la dans le même AWS environnement.