EXIGENCES CRITIQUES DE RÉUSSITE

La sortie de migration DOIT respecter tous les critères suivants :

1. Couverture Complète des Ressources

   • Chaque ressource CloudFormation synthétisée par CDK DOIT :
     • Être représentée dans le programme Pulumi OU
     • Être explicitement justifiée dans le rapport final.

2. Déploiement Réussi

   • Le programme Pulumi produit doit être structurellement valide et capable d'une pulumi up réussie (en supposant une configuration appropriée).

3. Rapport de Migration Final

   • Toujours produire un rapport de migration formel adapté à une Pull Request.
   • Inclure :
     • Mappage des ressources CDK → Pulumi
     • Décisions sur les providers (aws-native vs aws)
     • Différences comportementales
     • Étapes manquantes ou requérant une action manuelle
     • Instructions de validation

QUAND L'INFORMATION EST MANQUANTE

Si un projet CDK fourni par l'utilisateur est incomplet, ambigu ou manque d'artefacts (comme cdk.out), posez des questions ciblées avant de générer le code Pulumi.

FLUX DE MIGRATION

Suivez exactement ce flux de travail et dans cet ordre :

1. COLLECTE D'INFORMATIONS

1.1 Vérifier les Identifiants AWS (ESC)

L'exécution de commandes AWS (p. ex. aws cloudformation list-stack-resources) et de commandes CDK (p. ex. cdk synth) nécessite des identifiants chargés via Pulumi ESC.

• Si l'utilisateur a déjà fourni un environnement ESC, utilisez-le.
• Si aucun environnement ESC n'est spécifié, demandez à l'utilisateur quel environnement ESC utiliser avant de poursuivre avec les commandes AWS.

Vous DEVEZ confirmer la région AWS avec l'utilisateur. Les résultats de cdk synth peuvent être incorrects s'ils sont exécutés avec la mauvaise région AWS.

1.2 Synthétiser le CDK

Exécutez/inspectez :

npx cdk synth --quiet

• TOUJOURS exécuter synth avec --quiet pour éviter que le template ne soit affiché sur stdout.

En cas d'échec, inspectez cdk.json ou package.json pour les comportements de synth personnalisés.

1.3 Identifier les Stacks & Environnements CDK

Lisez cdk.out/manifest.json :

jq '.artifacts | to_entries | map(select(.value.type == "aws:cloudformation:stack") | {displayName: .key, environment: .value.environment}) | .[]' cdk.out/manifest.json

Exemple de sortie :

{
  "displayName": "DataStack-dev",
  "environment": "aws://616138583583/us-east-2"
}
{
  "displayName": "AppStack-dev",
  "environment": "aws://616138583583/us-east-2"
}

Dans le stack Pulumi que vous créez, vous DEVEZ définir les variables de configuration aws:region et aws-native:region. Par exemple :

pulumi config set aws-native:region us-east-2 --stack dev
pulumi config set aws:region us-east-2 --stack dev

1.4 Créer un Inventaire des Ressources

Pour chaque stack :

aws cloudformation list-stack-resources \
  --region <region> \
  --stack-name <stack> \
  --output json

1.5 Analyser la Structure CDK

Extrayez :

• Conditions spécifiques à l'environnement
• Dépendances entre stacks et références croisées
• Configuration à l'exécution (contexte/variables d'environnement)
• Types de constructs (L1, L2, L3)

2. CONVERSION DE CODE (CDK → PULUMI)

• Effectuez la conversion initiale à l'aide de l'outil cdk2pulumi. Suivez cdk-convert.md pour effectuer la conversion.
• Lisez le rapport de conversion et comblezles lacunes. Par exemple, si la conversion échoue à convertir une ressource, vous devez la convertir manuellement.

2.1 Gestion des Ressources Personnalisées

CDK utilise les Custom Resources sauvegardées par Lambda pour les fonctionnalités non disponibles dans CloudFormation. Dans les CloudFormation synthétisés, elles apparaissent comme :

• Type de ressource : AWS::CloudFormation::CustomResource ou Custom::<name>
• Les métadonnées contiennent aws:cdk:path avec le nom du handler (p. ex. aws-s3/auto-delete-objects-handler)

Comportement par défaut : cdk2pulumi réécrit les ressources personnalisées en aws-native:cloudformation:CustomResourceEmulator, qui invoque le Lambda original. Cela fonctionne mais comporte des compromis (dépendance Lambda, cold starts, cohérence finale).

Stratégies de migration par type de handler :

Handlers multi-comptes/régions :

• aws-cloudfront/edge-function → Utiliser aws.lambda.Function avec region: "us-east-1"
• aws-route53/cross-account-zone-delegation-handler → Utiliser un provider aws distinct avec assomption de rôle inter-comptes

Dégradation gracieuse pour les handlers inconnus :

1. Conservez le CustomResourceEmulator (comportement par défaut)
2. Documentez la ressource personnalisée dans le rapport de migration avec :
   • Nom et objectif du handler original (si discernible à partir du chemin CDK)
   • Note indiquant qu'elle utilise l'invocation Lambda à l'exécution
   • Recommandation pour l'utilisateur d'examiner les remplacements natifs potentiels

2.2 Stratégie de Provider

• Par défaut : Utiliser aws-native chaque fois que le type de ressource est disponible.
• Solution de secours : Utiliser aws quand aws-native ne supporte pas les fonctionnalités équivalentes.

2.3 Assets et Bundling

CDK utilise Assets et Bundling pour gérer les artefacts de déploiement. Ceux-ci sont traités par la CLI CDK avant le déploiement CloudFormation et apparaissent dans le répertoire cdk.out aux côtés des fichiers de métadonnées *.assets.json. Les templates CloudFormation contiennent des références codées en dur aux emplacements des assets (bucket/clé S3 ou repo/tag ECR).

# Inspecter les définitions d'asset
jq '.files, .dockerImages' cdk.out/*.assets.json

Stratégies de migration par type d'asset :

Détecter le Bundling dans la Source CDK :

Vérifiez le code source CDK pour les constructs de bundling (NodejsFunction, PythonFunction, GoFunction, ou ressources utilisant l'option bundling). Si le bundling est utilisé, l'étape de compilation doit être répliquée dans Pulumi pour le développement continu - sinon les changements source nécessiteraient de réexécuter manuellement cdk synth.

Quand le bundling est détecté, informez l'utilisateur :

Étape de Compilation Détectée : Cette application CDK utilise <BUNDLING_TYPE> qui compile des artefacts déployables lors de la synthèse. Cette étape de compilation doit être répliquée dans Pulumi pour le développement continu.

Options :

1. Pipeline CI/CD (Recommandé) : Déplacer l'étape de compilation vers votre pipeline CI et référencer l'artefact pré-compilé dans Pulumi
2. Provider Command Pulumi : Utiliser command.local.Command pour exécuter la commande de compilation lors de pulumi up
3. Script de pré-compilation : Créer un script de compilation qui s'exécute avant pulumi up et exporte vers un emplacement connu

Chaque option comporte des compromis autour de la mise en cache, de la reproductibilité et de la vitesse de déploiement. Pour les charges de travail en production, l'option 1 est généralement préférée.

2.4 Gestion de TypeScript pour aws-native

Les sorties aws-native contiennent souvent undefined. Éviter les assertions non-null !. Toujours déballer en toute sécurité avec .apply() :

// ❌ FAUX - Causera des erreurs TypeScript
functionName: lambdaFunction.functionName!,

// ✅ CORRECT - Gérer undefined en toute sécurité
functionName: lambdaFunction.functionName.apply(name => name || ""),

2.5 Préservation de la Logique d'Environnement

Reporter tous les comportements conditionnels :

if (currentEnv.createVpc) {
  // créer des ressources
} else {
  const vpcId = pulumi.output(currentEnv.vpcId);
}

3. Importation de Ressources (optionnel)

Après la conversion, vous pouvez optionnellement importer les ressources existantes pour qu'elles soient désormais gérées par Pulumi. Si l'utilisateur ne demande pas cela, vous devriez suggérer cela comme étape de suivi à la conversion.

• Toujours commencer par une importation automatisée à l'aide de l'outil cdk-importer. Suivez cdk-importer.md pour effectuer l'importation automatisée.
• Pour toute ressource qui échoue à s'importer avec l'outil automatisé, l'importer manuellement.

Si vous devez importer des ressources manuellement :

• Suivez cloudformation-id-lookup.md pour rechercher les identifiants d'importation CloudFormation.

• Utilisez l'outil web-fetch pour obtenir le contenu de la documentation officielle Pulumi.

• Trouver les IDs d'importation AWS -> https://www.pulumi.com/docs/iac/guides/migration/aws-import-ids/

• Approches de migration manuelle -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app/#approach-b-manual-migration

3.1 Exécuter preview après l'importation

Après avoir effectué une importation, vous devez exécuter pulumi preview pour vous assurer qu'il n'y a aucun changement. Aucun changement signifie :

• PAS de mises à jour
• PAS de remplacements
• PAS de créations
• PAS de suppressions

S'il y a des changements, vous devez investiguer et mettre à jour le programme jusqu'à ce qu'il n'y ait aucun changement.

Travailler avec l'Utilisateur

Si l'utilisateur demande de l'aide pour planifier ou effectuer une migration CDK vers Pulumi, utilisez les informations ci-dessus pour guider l'utilisateur vers l'approche de migration automatisée.

Pour la Documentation Détaillée

Quand l'utilisateur veut s'écarter du chemin recommandé ci-dessus, utilisez l'outil web-fetch pour obtenir du contenu de la documentation officielle Pulumi -> https://www.pulumi.com/docs/iac/guides/migration/migrating-to-pulumi/migrating-from-cdk/migrating-existing-cdk-app

Cette documentation couvre les sujets :

• Stratégie de migration
  • Convertir vs. Réécrire
  • Importer vs. Réhydrater
  • Bonnes pratiques
• Gérer Plusieurs Stacks CDK
• Gérer les Stages CDK
• Organisation du code
• Conversion des Constructs CDK
• Stratégies d'Exécution
  • Migration Automatisée (recommandée)
  • Migration Manuelle

FORMAT DE SORTIE (REQUIS)

Lors de l'exécution d'une migration, toujours produire :

1. Aperçu (description générale)
2. Résumé du Plan de Migration
3. Sorties de Code Pulumi (TypeScript ; structurées par fichier)
4. Tableau de Mappage des Ressources (CDK → Pulumi)
5. Résumé des Ressources Personnalisées (le cas échéant) :
   • Handlers migrés vers les ressources Pulumi natives
   • Handlers conservés comme CustomResourceEmulator avec justification
   • Tous les handlers nécessitant l'attention de l'utilisateur
6. Résumé Assets & Bundling (le cas échéant) :
   • Migrés : Assets convertis avec succès (p. ex. images Docker → docker-build.Image, fichiers statiques → pulumi.FileArchive)
   • Nécessite attention : Assets avec étapes de bundling, options présentées et décision si prise
7. Rapport de Migration Final (prêt pour PR)
8. Étapes Suivantes (refactorisations optionnelles)

Garder le code syntaxiquement valide et clairement séparé par fichiers.