pulumi-arm-to-pulumi

Par pulumi · agent-skills

Convertir ou migrer des templates Azure ARM (Azure Resource Manager), des templates Bicep, ou du code vers Pulumi, y compris l'import de ressources Azure existantes. Cette skill DOIT être chargée dès qu'un utilisateur demande la migration, la conversion ou l'import de templates ARM, de templates Bicep, de code ARM, de code Bicep, ou de ressources Azure vers Pulumi.

npx skills add https://github.com/pulumi/agent-skills --skill pulumi-arm-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 conseils 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 éléments suivants :

  1. Couverture complète des ressources

    • Chaque ressource de template ARM 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 preview réussie (en supposant une configuration appropriée).

  3. Validation d'import sans différence (si importation de ressources existantes)

    • Après l'import, pulumi preview doit montrer :
      • AUCUNE mise à jour
      • AUCUN remplacement
      • AUCUNE création
      • AUCUNE suppression
    • Toute différence doit être résolue en utilisant le Workflow de résolution d'aperçu. Voir arm-import.md.

  4. Rapport final de migration

    • Toujours générer un rapport formel de migration adapté à une Pull Request.
    • Inclure :
      • Mappage des ressources ARM → Pulumi
      • Décisions de fournisseur (azure-native vs azure)
      • Différences comportementales
      • Étapes manquantes ou requises manuellement
      • Instructions de validation

QUAND DES INFORMATIONS MANQUENT

Si le template ARM fourni par l'utilisateur est incomplet, ambigu ou manque d'artefacts, posez des questions ciblées avant de générer du code Pulumi.

Si l'ambiguïté porte sur la gestion d'une propriété de ressource spécifique lors de l'import, posez des questions ciblées avant de modifier le code Pulumi.

WORKFLOW DE MIGRATION

Suivez ce workflow exactement et dans cet ordre :

1. COLLECTE D'INFORMATIONS

1.1 Vérifier les credentials Azure

Exécuter des commandes Azure CLI (p. ex., az resource list, az resource show). Nécessite une connexion initiale avec ESC et az login

  • 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 aux commandes Azure CLI.

Configuration d'Azure CLI avec ESC :

  • Les environnements ESC peuvent fournir des credentials Azure via des variables d'environnement ou la configuration Azure CLI
  • Connectez-vous à Azure avec ESC pour fournir les credentials, par ex : pulumi env run {org}/{project}/{environment} -- bash -c 'az login --service-principal -u "$ARM_CLIENT_ID" --tenant "$ARM_TENANT_ID" --federated-token "$ARM_OIDC_TOKEN"'. ESC n'est pas requis après l'établissement de la session
  • Vérifier que les credentials fonctionnent : az account show
  • Confirmer l'abonnement : az account list --query "[].{Name:name, SubscriptionId:id, IsDefault:isDefault}" -o table

Pour des informations détaillées sur ESC : Chargez la skill pulumi-esc en appelant l'outil "Skill" avec name = "pulumi-esc"

1.2 Analyser la structure du template ARM

Les templates ARM n'ont pas le concept de « stacks » comme CloudFormation. Lisez le fichier JSON du template ARM directement :

# Afficher la structure du template
cat template.json | jq '.resources[] | {type: .type, name: .name}'

# Afficher les paramètres
cat template.json | jq '.parameters'

# Afficher les variables
cat template.json | jq '.variables'

Extraire :

  • Types et noms de ressources
  • Paramètres et leurs valeurs par défaut
  • Variables et expressions
  • Dépendances (tableaux dependsOn)
  • Templates imbriqués ou liés
  • Boucles de copie (constructs d'itération)
  • Déploiements conditionnels (propriété condition)

Documentation : Structure du template ARM

1.3 Construire l'inventaire des ressources (si import de ressources existantes)

Si le template ARM a déjà été déployé et que vous importez des ressources existantes :

# Lister toutes les ressources d'un groupe de ressources
az resource list \
  --resource-group <resource-group-name> \
  --output json

# Obtenir les détails d'une ressource spécifique
az resource show \
  --ids <resource-id> \
  --output json

# Interroger des propriétés spécifiques en utilisant JMESPath
az resource show \
  --ids <resource-id> \
  --query "{name:name, location:location, properties:properties}" \
  --output json

Documentation : Documentation Azure CLI

2. CONVERSION DE CODE (ARM → PULUMI)

IMPORTANT : La conversion ARM vers Pulumi nécessite une traduction manuelle. Il n'existe AUCUN outil de conversion automatisé pour les templates ARM. Vous êtes responsable de la conversion complète.

Principes clés de conversion

  1. Stratégie de fournisseur :

    • Par défaut : Utiliser @pulumi/azure-native pour une couverture complète de l'API Azure Resource Manager
    • Secours : Utiliser @pulumi/azure (fournisseur classique) quand azure-native ne supporte pas des fonctionnalités spécifiques ou quand vous avez besoin d'abstractions simplifiées

    Documentation :

  2. Support des langages :

    • TypeScript/JavaScript : Le plus courant, excellent support IDE
    • Python : Idéal pour les équipes data et les workflows ML
    • C# : Naturel pour les équipes .NET
    • Go : Hautes performances, typage strict
    • Java : Équipes Java d'entreprise
    • YAML : Approche déclarative simple
    • Choisir selon la préférence de l'utilisateur ou la base de code existante

  3. Couverture complète :

    • Convertir TOUTES les ressources du template ARM
    • Préserver tous les conditionnels, boucles et dépendances
    • Maintenir la logique des paramètres et variables

Suivez les modèles de conversion dans arm-conversion-patterns.md.

arm-conversion-patterns.md fournit :

  • Mappage des paramètres, variables et outputs
  • Traduction des boucles copy, conditionnels et dependsOn
  • Templates imbriqués → ComponentResource
  • Exemples de fournisseur Azure classique (VNet, App Service)
  • Gestion des outputs TypeScript et pièges courants

3. IMPORT DE RESSOURCES (RESSOURCES EXISTANTES) - OPTIONNEL

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

CRITIQUE : Quand l'utilisateur demande d'importer des ressources Azure existantes dans Pulumi, consultez arm-import.md pour les procédures d'import détaillées et les workflows de validation sans différence.

arm-import.md fournit :

  • Modèles d'ID d'import inline et exemples
  • Conventions de format des ID de ressource Azure
  • Gestion des ressources enfants (p. ex., WebAppApplicationSettings)
  • Workflow de résolution d'aperçu pour atteindre une absence de différence après import
  • Débogage étape par étape pour les conflits de propriétés

Principes clés d'import

  1. Approche d'import inline :

    • Utiliser l'option de ressource import avec les ID de ressource Azure
    • Aucun outil d'import séparé (contrairement à pulumi-cdk-importer)

  2. ID de ressource Azure :

    • Suivre le modèle prévisible : /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
    • Peut être généré par convention ou interrogé via Azure CLI

  3. Validation sans différence :

    • Exécuter pulumi preview après import
    • Résoudre toutes les différences avec le Workflow de résolution d'aperçu
    • Objectif : AUCUNE mise à jour, remplacement, création ou suppression

4. CONFIGURATION PULUMI

Configurer la stack pour correspondre aux paramètres du template ARM :

# Définir la région Azure
pulumi config set azure-native:location eastus --stack dev

# Définir les paramètres d'application
pulumi config set storageAccountName mystorageaccount --stack dev

# Définir les paramètres secrets
pulumi config set --secret adminPassword MyS3cr3tP@ssw0rd --stack dev

5. VALIDATION

Après atteindre l'absence de différence en aperçu (si import), valider la migration :

  1. Examiner tous les exports :

    pulumi stack output

  2. Vérifier les relations entre ressources :

    pulumi stack graph

  3. Tester la fonctionnalité de l'application (le cas échéant)

  4. Documenter les étapes manuelles requises après la migration

TRAVAIL AVEC L'UTILISATEUR

Si l'utilisateur demande de l'aide pour planifier ou effectuer une migration ARM vers Pulumi, utilisez les informations ci-dessus pour guider l'utilisateur à travers le processus de conversion et d'import.

POUR LA DOCUMENTATION DÉTAILLÉE

Quand l'utilisateur souhaite des informations supplémentaires, utilisez l'outil web-fetch pour obtenir le contenu de la documentation officielle Pulumi :

Documentation Microsoft Azure :

FORMAT DE SORTIE (REQUIS)

En effectuant une migration, toujours produire :

  1. Aperçu (description de haut niveau)
  2. Résumé du plan de migration
    • Ressources du template ARM identifiées
    • Stratégie de conversion (langage, fournisseurs)
    • Approche d'import (si applicable)
  3. Sorties de code Pulumi (organisées par fichier)
    • Fichier du programme principal
    • Ressources de composant (le cas échéant)
    • Instructions de configuration
  4. Tableau de mappage des ressources (ARM → Pulumi)
    • Type de ressource ARM → Type de ressource Pulumi
    • Nom de ressource ARM → Nom logique Pulumi
    • ID d'import (si import)
  5. Notes de résolution d'aperçu (si import)
    • Différences rencontrées
    • Stratégie de résolution appliquée
    • Propriétés ignorées vs. ajoutées
  6. Rapport final de migration (prêt pour PR)
    • Résumé des modifications
    • Instructions de test
    • Limitations connues
    • Prochaines étapes
  7. Configuration
    • Valeurs de config requises
    • Exemples de commandes pulumi config set

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

Skills similaires

pulumi-component
pulumi / agent-skills

Créer et structurer des ComponentResource Pulumi réutilisables dans plusieurs langages.

45
pulumi-best-practices
pulumi / agent-skills

Appliquer les meilleures pratiques Pulumi pour structurer et déployer l'infrastructure correctement.

45
cloudformation-to-pulumi
pulumi / agent-skills

Migrer des templates CloudFormation vers Pulumi avec import et rapport automatisés.

45
provider-upgrade
pulumi / agent-skills

Mettre à niveau les providers Pulumi en traduisant le code sans modifier l'infrastructure réelle.

45
pulumi-cdk-to-pulumi
pulumi / agent-skills

Migrer un projet AWS CDK vers Pulumi avec rapport et couverture complète des ressources.

45