cloudformation-to-pulumi

IMPORTANT: AJUSTEMENT DU PLAN REQUIS

Si vous avez déjà généré un plan de migration avant de charger cette skill, vous DEVEZ:

1. Examiner votre plan existant par rapport aux workflows et exigences de cette skill
2. Identifier les lacunes, étapes manquantes ou hypothèses incorrectes
3. Mettre à jour et réviser votre plan pour l'aligner avec les recommandations de cette skill
4. Communiquer le plan ajusté à l'utilisateur avant de procéder

EXIGENCES CRITIQUES DE SUCCÈS

La sortie de migration DOIT satisfaire tous les points suivants:

1. Couverture complète des ressources

   • Chaque ressource CloudFormation DOIT être représentée dans le programme Pulumi OU explicitement justifiée dans le rapport final.

2. Identifiant logique CloudFormation comme nom de ressource

   • CRITIQUE: Chaque ressource Pulumi DOIT utiliser l'identifiant logique CloudFormation comme nom de ressource.
   • Cela permet à l'outil cdk-importer de trouver automatiquement les identifiants d'import.
   • NE RENOMMEZ PAS les ressources. L'import automatisé ÉCHOUERA si vous modifiez les identifiants logiques.

3. Déploiement réussi

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

4. Validation import sans différence (si import de ressources existantes)

   • Après import, pulumi preview ne doit afficher AUCUNE mise à jour, remplacement, création ou suppression.

5. Rapport de migration final

   • Toujours produire un rapport de migration formel adapté à une Pull Request.

LORSQUE DES INFORMATIONS MANQUENT

Si l'utilisateur n'a pas fourni de template CloudFormation, vous DEVEZ le récupérer depuis AWS en utilisant le nom de stack.

WORKFLOW DE MIGRATION

Suivez ce workflow exactement et dans cet ordre:

1. COLLECTE D'INFORMATIONS

1.1 Vérifier les credentials AWS (ESC)

L'exécution de commandes AWS requiert des credentials chargées 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 procéder.

Pour des informations détaillées sur ESC: Utilisez la skill pulumi-esc.

Vous DEVEZ confirmer la région AWS avec l'utilisateur.

1.2 Obtenir le template CloudFormation

Si l'utilisateur a fourni un fichier template: Lisez le template directement.

Si l'utilisateur a fourni uniquement un nom de stack: Récupérez le template depuis AWS:

aws cloudformation get-template \
  --region <region> \
  --stack-name <stack-name> \
  --query 'TemplateBody' \
  --output json > template.json

1.3 Créer un inventaire des ressources

Listez toutes les ressources de la stack:

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

Cela fournit:

• LogicalResourceId - Utilisez ceci comme nom de ressource Pulumi
• PhysicalResourceId - L'identifiant AWS réel de la ressource
• ResourceType - Le type de ressource CloudFormation

1.4 Analyser la structure du template

Extrayez du template:

• Les paramètres et leurs valeurs par défaut
• Les mappages
• Les conditions
• Les sorties
• Les dépendances de ressources (Ref, GetAtt, DependsOn)

2. CONVERSION DE CODE (CloudFormation → Pulumi)

IMPORTANT: Il n'existe PAS d'outil de conversion automatisé pour CloudFormation. Vous DEVEZ convertir chaque ressource manuellement.

2.1 Convention de nommage des ressources (CRITIQUE)

Chaque ressource Pulumi DOIT utiliser l'identifiant logique CloudFormation comme nom.

// CloudFormation:
// "MyAppBucketABC123": { "Type": "AWS::S3::Bucket", ... }

// Pulumi - CORRECT:
const myAppBucket = new aws.s3.Bucket("MyAppBucketABC123", { ... });

// Pulumi - INCORRECT (NE PAS faire ceci - l'import échouera):
const myAppBucket = new aws.s3.Bucket("my-app-bucket", { ... });

Cette convention de nommage est REQUISE car l'outil cdk-importer associe les ressources par nom.

2.2 Stratégie de fournisseur

⚠️ CRITIQUE: UTILISEZ TOUJOURS aws-native PAR DÉFAUT ⚠️

• Utilisez aws-native pour toutes les ressources sauf s'il existe une raison spécifique d'utiliser aws.
• Les types CloudFormation sont mappés directement à aws-native (p. ex., AWS::S3::Bucket → aws-native.s3.Bucket).
• Utilisez aws (classique) uniquement quand aws-native ne supporte pas une fonctionnalité requise.

C'est OBLIGATOIRE pour les imports réussis avec cdk-importer. Le cdk-importer fonctionne en associant les ressources CloudFormation aux ressources Pulumi, et CloudFormation se mappe 1:1 à aws-native. L'utilisation du fournisseur aws classique causera des échecs d'import.

2.3 Fonctions intrinsèques CloudFormation

Mappez les fonctions intrinsèques CloudFormation aux équivalents Pulumi:

Exemple: !Sub

// CloudFormation: !Sub "arn:aws:s3:::${MyBucket}/*"
// Pulumi:
const bucketArn = pulumi.interpolate`arn:aws:s3:::${myBucket.bucket}/*`;

Exemple: !GetAtt

// CloudFormation: !GetAtt MyFunction.Arn
// Pulumi:
const functionArn = myFunction.arn;

2.4 Conditions CloudFormation

Convertissez les conditions CloudFormation en logique TypeScript:

// CloudFormation:
// "Conditions": {
//   "CreateProdResources": { "Fn::Equals": [{ "Ref": "Environment" }, "prod"] }
// }

// Pulumi:
const config = new pulumi.Config();
const environment = config.require("environment");
const createProdResources = environment === "prod";

if (createProdResources) {
  // Créer les ressources spécifiques à la production
}

2.5 Paramètres CloudFormation

Convertissez les paramètres en configuration Pulumi:

// CloudFormation:
// "Parameters": {
//   "InstanceType": { "Type": "String", "Default": "t3.micro" }
// }

// Pulumi:
const config = new pulumi.Config();
const instanceType = config.get("instanceType") || "t3.micro";

2.6 Mappages CloudFormation

Convertissez les mappages en objets TypeScript:

// CloudFormation:
// "Mappings": {
//   "RegionMap": {
//     "us-east-1": { "AMI": "ami-12345" },
//     "us-west-2": { "AMI": "ami-67890" }
//   }
// }

// Pulumi:
const regionMap: Record<string, { ami: string }> = {
  "us-east-1": { ami: "ami-12345" },
  "us-west-2": { ami: "ami-67890" },
};
const ami = regionMap[aws.config.region!].ami;

2.7 Ressources personnalisées

Les ressources personnalisées CloudFormation (AWS::CloudFormation::CustomResource ou Custom::*) requièrent un traitement spécial:

1. Identifier l'objectif: Lisez le code de la fonction Lambda pour comprendre ce qu'elle fait
2. Trouver un équivalent natif: Vérifiez si Pulumi possède une ressource native qui fournit la même fonctionnalité
3. Si pas d'équivalent: Documentez dans le rapport de migration qu'une implémentation manuelle est nécessaire

2.8 Gestion des sorties TypeScript

Les sorties aws-native contiennent souvent undefined. Évitez les assertions non-null !. Déroulez toujours en toute sécurité avec .apply():

// INCORRECT
functionName: lambdaFunction.functionName!,

// CORRECT
functionName: lambdaFunction.functionName.apply(name => name || ""),

3. IMPORT DE RESSOURCES

Après la conversion, importez les ressources existantes pour qu'elles soient gérées par Pulumi.

3.0 Validation pré-import (REQUISE)

Avant de procéder à l'import, validez votre code:

1. Vérifier l'utilisation du fournisseur: Scannez votre code pour vérifier que toutes les ressources utilisent aws-native
2. Documenter les exceptions: Toute utilisation du fournisseur aws (classique) doit être justifiée
3. Vérifier les noms de ressources: Confirmez que toutes les ressources utilisent les identifiants logiques CloudFormation comme noms

3.1 Import automatisé avec cdk-importer

Parce que vous avez utilisé les identifiants logiques CloudFormation comme noms de ressources, vous pouvez utiliser l'outil cdk-importer pour importer automatiquement les ressources.

Suivez cfn-importer.md pour les procédures d'import détaillées.

3.2 Import manuel pour les ressources non importées

Pour les ressources dont l'import automatique échoue:

1. Suivez cloudformation-id-lookup.md pour trouver le format de l'identifiant d'import
2. Utilisez pulumi import:

pulumi import <pulumi-resource-type> <logical-id> <import-id>

3.3 Exécution de Preview après l'import

Après l'import, exécutez pulumi preview. Il ne doit y avoir:

• AUCUNE mise à jour
• AUCUN remplacement
• AUCUNE création
• AUCUNE suppression

S'il y a des modifications, enquêtez et mettez à jour le programme jusqu'à ce que la preview soit propre.

FORMAT DE SORTIE (REQUIS)

Lors d'une migration, produisez toujours:

1. Vue d'ensemble (description de haut niveau)
2. Résumé du plan de migration
3. Sorties de code Pulumi (TypeScript; organisées par fichier)
4. Tableau de correspondance des ressources:

5. Résumé des ressources personnalisées (le cas échéant)
6. Rapport de migration final (adapté à Pull Request)
7. Étapes suivantes (instructions d'import)

POUR LA DOCUMENTATION DÉTAILLÉE

Récupérez le contenu de la documentation officielle Pulumi:

• https://www.pulumi.com/docs/iac/adopting-pulumi/migrating-to-pulumi/from-aws/