Mise à niveau des fournisseurs Pulumi

Le Principe

Une mise à niveau de fournisseur est une traduction, non une demande de changement.

L'intention infrastructure de l'utilisateur n'a pas changé - il souhaite toujours le même bucket, la même fonction, le même cluster. Ce qui a changé, c'est comment l'API du fournisseur exprime cette intention. Votre travail consiste à traduire leur code existant dans la nouvelle API pour que Pulumi ne voie aucune différence entre ce que le code dit et ce qui existe déjà.

Il y a quatre couches à garder à l'esprit :

Intention de l'utilisateur - ce que l'utilisateur veut dans le cloud (inchangé lors d'une mise à niveau)
Code - comment le programme exprime cette intention en utilisant l'API du fournisseur (peut nécessiter une mise à jour)
État Pulumi - la représentation stockée par Pulumi de ce qui existe (peut nécessiter une réconciliation)
Cloud réel - l'infrastructure réelle (ne doit pas changer lors d'une mise à niveau)

Lors d'une mise à niveau, les couches 2 et 3 peuvent nécessiter des changements pour continuer à représenter correctement les couches 1 et 4 inchangées.

Une traduction correcte produit une différence zéro. Le moteur Pulumi n'a pas de concept de « mise à niveau » - il compare simplement l'état objectif (votre code) par rapport à l'état réel (le fichier d'état) et effectue la réconciliation. Si la traduction est correcte, ces deux états correspondent et rien ne se passe. Si vous voyez une différence, soit votre traduction est incorrecte, soit quelque chose au-delà d'un changement de code est nécessaire (import, alias, étape manuelle). Dans tous les cas, la différence est un problème à résoudre, non une conséquence à accepter.

La Boucle Centrale

flowchart TD
    A[Bump version] --> B[Run preview with env vars]
    B --> C{Clean?}
    C -->|Yes| D[Create PR]
    C -->|No| E[Diff Checkpoint: categorize every diff]
    E --> F{Any Category A?}
    F -->|Yes| G[Fix wrong translations]
    G --> B
    F -->|No| H{Any Category B?}
    H -->|Yes| I[Investigate with toolbox]
    I --> J[Fix or document]
    J --> B
    H -->|No| D

Mettez à jour la dépendance du fournisseur
Lancez la preview avec les drapeaux CLI requis
Diff Checkpoint - catégorisez chaque ressource non-same (voir section suivante)
Corrigez la catégorie A - changements de code qui n'ont pas produit same
Enquêtez sur la catégorie B - diffs sur les ressources que vous n'avez pas modifiées
Répétez jusqu'à ce que ce soit propre ou que les diffs restantes soient pleinement enquêtées
Créez une PR avec un résumé de mise à niveau

Le Diff Checkpoint

C'est la section la plus importante. Lancez-la après CHAQUE preview.

Pour chaque ressource non-same, posez-vous une question : « Mes changements de code ont-ils affecté cette ressource - directement ou indirectement ? »

« Directement » signifie que vous avez modifié le bloc de ressource lui-même. « Indirectement » signifie que vous avez modifié quelque chose qui alimente cette ressource - une variable partagée, une sortie d'une autre ressource, une fonction d'aide, une valeur par défaut, ou une ressource dont celle-ci dépend. Si vos changements auraient pu modifier ce que Pulumi calcule pour cette ressource, c'est une catégorie A.

Suivez ensuite la catégorie qui s'applique.

Catégorie A : J'ai modifié le code pour cette ressource

Votre changement de code était censé traduire la même intention dans la nouvelle API. Si la ressource montre same, votre traduction est correcte. Si elle montre autre chose, votre traduction est incorrecte. Pas « la différence est attendue parce que j'ai modifié le code » - si le changement était sémantiquement équivalent, il n'y aurait pas de différence.

J'ai modifié une ressource existante et elle affiche update :

Votre renommage, restructuration ou ajustement de valeur a changé le sens, pas seulement la syntaxe. La ressource montrerait same si l'ancien et le nouveau code compilaient au même état objectif. update signifie qu'ils ne le font pas.

Demandez-vous : « Si ce renommage était vraiment équivalent, la ressource montrerait same. Ce n'est pas le cas. Qu'est-ce qui est sémantiquement différent entre mon ancien code et mon nouveau code ? »

Causes courantes : le nouveau nom de propriété mappe à un champ sous-jacent différent ; la forme de valeur a changé et votre conversion a perdu ou ajouté des informations ; une valeur par défaut a changé dans la nouvelle version et vous devez définir explicitement l'ancienne valeur ; des propriétés supplémentaires apparaissent maintenant dans la différence parce que la nouvelle version du fournisseur suit des champs qu'elle ne faisait pas avant (ceux-ci doivent être définis explicitement pour correspondre à l'état actuel).

Si la mise à jour inclut des propriétés que vous n'avez pas modifiées - de nouveaux champs qui apparaissent, normalisations de type (string->number), défauts supplémentaires - c'est le fournisseur qui change ce qu'il suit. Mais si la différence est là, pulumi up ENVERRA ces valeurs à l'API cloud. Ne supposez pas qu'ils ne font rien. Enquêtez sur chaque propriété modifiée.

J'ai ajouté un nouveau bloc de ressource et il affiche create :

Lors d'une mise à niveau, un nouveau bloc de ressource représente presque toujours une infrastructure qui existe déjà dans le cloud. L'ancien fournisseur l'a géré implicitement (dans le cadre d'une autre ressource) ; le nouveau fournisseur a besoin d'une ressource explicite. Mais l'objet cloud est déjà là. Pulumi veut créer une NOUVELLE infrastructure - ce n'est pas ce que vous voulez.

La correction est import, non create. Dites à Pulumi d'adopter la ressource cloud existante.

Demandez-vous : « Quel objet cloud cette nouvelle ressource représente-t-elle ? Existe-t-il déjà ? Comment a-t-il été géré avant la mise à niveau ? »

// Mauvais - crée une infrastructure en double
const stage = new aws.apigateway.Stage("prodStage", { ... });

// Correct - adopte la ressource existante
const stage = new aws.apigateway.Stage("prodStage", { ... }, {
    import: "<rest-api-id>/prod",  // le format d'ID d'import varie selon le type de ressource
});

J'ai supprimé un bloc de ressource et il affiche delete :

Un delete dans la preview signifie que pulumi up appellera l'API Delete du fournisseur pour détruire ou déconfigurer cette ressource cloud. C'est une vraie destruction - pas seulement un nettoyage d'état. L'infrastructure cloud existe toujours et est presque certainement toujours nécessaire.

C'est différent de pulumi state delete, qui supprime la ressource du suivi de Pulumi SANS appeler l'API du fournisseur. Quand un type de ressource est supprimé dans une nouvelle version du fournisseur, l'approche correcte est :

pulumi state delete '<urn>' - étape manuelle, supprime du suivi uniquement
Ajouter les ressources de remplacement (le cas échéant) avec les imports - adopte l'état cloud sous les nouveaux types
Vérifier avec la preview

NE LAISSEZ PAS un delete dans la preview et procédez à la création d'une PR. Un delete qui s'exécute via pulumi up détruira une infrastructure réelle. Si la ressource doit être supprimée de l'état, documentez-la comme une étape manuelle pour l'utilisateur.

Demandez-vous : « Quelle infrastructure cloud cette ressource gère-t-elle ? Si pulumi up exécute ce delete, qu'est-ce qui est détruit ou déconfiguré ? »

Catégorie B : Je n'ai pas modifié le code pour cette ressource

Cette différence n'a pas été causée par vos changements de code. Elle provient du changement de version du fournisseur lui-même - une valeur par défaut différente, une représentation d'état modifiée, ou une différence de comportement. Lisez references/diagnostic-toolbox.md et enquêtez.

Ces différences pourraient être :

Corriger avec le code - définir une valeur explicite pour un défaut modifié, ajouter un alias
Un no-op documenté - le guide de mise à niveau dit qu'il se résout sur pulumi up sans affecter l'infrastructure réelle. Cette classification NÉCESSITE une citation du guide de mise à niveau ou de la documentation du fournisseur. Votre propre jugement selon lequel « cela semble être un no-op » n'est pas suffisant - l'utilisateur vous fait confiance pour distinguer les changements d'infrastructure réels des artefacts, et se tromper signifie des changements inattendus à leur cloud.
Nécessitant des étapes manuelles - suppression d'état + réimport, documenté pour l'utilisateur
Inconnu - présentez ce que vous avez trouvé à l'utilisateur et demandez des conseils

Catégorie C : Bump de version du fournisseur

Un update sur pulumi:providers:{name} montrant uniquement un changement de version est la seule différence attendue. Vérifiez qu'aucune autre propriété n'a changé sur la ressource du fournisseur.

Après catégorisation

Vérification de complétude : Chaque ressource dans la preview qui montre n'importe quel état non-same doit apparaître dans votre checkpoint - y compris les ressources avec des annotations [diff: ...], même si elles n'ont pas de marqueur explicit create/update/delete. Si vous ne l'avez pas listé, votre checkpoint est incomplet. Retournez et catégorisez les ressources manquantes.

Exigence de preuve pour les diffs acceptées : Si vous voulez accepter n'importe quelle différence comme « OK » (ne pas la corriger), vous avez besoin de preuves - que ce soit une catégorie A ou une catégorie B. « Je crois que l'API traite ces équivalents » ou « cela semble être une réconciliation d'état » n'est pas une preuve. Preuve acceptable : le guide de mise à niveau le documente, un problème GitHub le confirme, ou la documentation du fournisseur explique le comportement. Si vous ne trouvez pas de preuve, soit corrigez la différence soit signalez-la à l'utilisateur.

Ordre : Corrigez tous les problèmes de catégorie A avant d'enquêter sur la catégorie B. Vos corrections de code changeront la sortie preview, donc enquêter sur les diffs de catégorie B en premier gaspille l'effort. Corrigez d'abord vos propres erreurs, relancez la preview, puis regardez ce qui reste.

Pas de delete ou replace dans la preview finale. Si un delete ou replace reste quand vous êtes prêt à créer une PR, arrêtez. Un delete signifie que pulumi up détruira une infrastructure cloud. Un replace signifie qu'il la détruira et la recréera. Ceux-ci ne sont jamais acceptables en tant que « diffs restantes » - elles doivent être résolues (via une correction de code, un alias, ou des étapes manuelles documentées) avant de procéder.

Règles Strictes

Drapeaux CLI requis

Utilisez ces drapeaux lors de l'exécution de la preview. Une preview sans eux peut montrer des diffs fausses (suppressions de tags fantômes, ajouts de région) qui ne sont pas réels. N'interprétez pas une preview qui a été exécutée sans eux.

pulumi preview --refresh --run-program

--refresh actualise l'état cloud réel avant de comparer.
--run-program exécute le programme Pulumi lors de l'actualisation.

N'essayez pas d'éliminer les dépréciations

Si quelque chose est déprécié mais fonctionne toujours, laissez-le tranquille. Migrer vers le remplacement introduit du risque pour aucun bénéfice. Un avertissement de dépréciation est acceptable - une différence ne l'est pas.

// MAUVAIS : migrer les propriétés dépréciées-mais-fonctionnelles introduit du risque
new aws.s3.Bucket('bucket');
new aws.s3.BucketLogging('bucketLogging', {...});  // migration inutile

// BON : corrigez seulement l'erreur réelle, laissez le code fonctionnant tranquille
new aws.s3.Bucket('bucket', {
  logging: {...},  // "loggings" renommé en "logging" - vrai changement de rupture
  website: {...},  // déprécié mais fonctionne - ne touchez pas
});

Soyez minimalement invasif

Chaque ligne modifiée pourrait introduire une régression. Préférez le plus petit changement qui fonctionne.

Ne lancez pas pulumi up

Les mises à niveau de fournisseur modifient le code source et ont besoin d'une revue de code avant le déploiement. PR -> review -> merge -> deploy via CI/CD.

Commencer

1. Obtenir les informations de version

Déterminez la version cible à partir de la demande de l'utilisateur, du registre Pulumi, des métadonnées du gestionnaire de packages, ou des contraintes de dépendance existantes du référentiel.

Par défaut, utilisez la dernière version stable si l'utilisateur n'a pas spécifié une version cible. Si l'utilisateur demande quels stacks ou projets sont affectés, utilisez la skill package-usage ou le meilleur outil d'inventaire de packages disponible avant d'apporter des modifications.

2. Mettez à jour la dépendance

TypeScript/JavaScript : npm install @pulumi/{provider}@^{version} ou yarn add @pulumi/{provider}@^{version}
Python : Mettez à jour pyproject.toml ou requirements.txt avec pulumi_{provider}>={version} (tiret bas, pas tiret), puis installez
Go : go get github.com/pulumi/pulumi-{provider}/sdk/v{major}@latest, mettez à jour tous les chemins d'import (p. ex. v6 -> v7), exécutez go mod tidy
.NET : dotnet add package Pulumi.{Provider} --version {version}
Java : Mettez à jour la version de dépendance dans pom.xml ou build.gradle
YAML : Mettez à jour la version du fournisseur dans les options de ressource ou la configuration du fournisseur. Consultez https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#providers-and-provider-versions pour les exemples.

Après l'installation, vérifiez la version réellement installée à partir du lockfile (package-lock.json, go.sum, etc.) - utilisez ces versions exactes pour les comparaisons de schema-tools.

3. Lancez la preview

Exécutez pulumi preview --refresh --run-program immédiatement après la mise à jour de la dépendance. Ne recherchez pas d'abord les changements de rupture - beaucoup de mises à niveau fonctionnent simplement, en particulier les versions mineures.

Si la preview est propre (uniquement le bump de version du fournisseur), créez une PR.

Progression de la Preview

La preview peut échouer sur la première erreur et en masquer d'autres. Corriger une erreur révèle souvent de nouvelles erreurs. C'est un progrès normal, non un signe que les corrections empirent les choses.

Erreurs nouvelles ou différentes -> progrès, continuez
L'ensemble des erreurs s'est réduit -> progrès, continuez
La même erreur persiste -> votre correction n'a pas fonctionné, essayez une approche différente
Pas d'erreurs mais des diffs -> lancez le diff checkpoint

Résumé de Mise à Niveau

Une fois que la preview est propre (ou aussi propre que possible), présentez le résumé :

## Résumé de Mise à Niveau : {provider} v{current} -> v{target}

### Changements de Code
| Fichier | Changement | Pourquoi cela préserve l'intention |
|---------|-----------|--------------------------------|
| package.json | Version bump | - |
| index.ts:15 | loggings -> logging | Propriété renommée, même champ sous-jacent |

### Résultat de la Preview
Toutes les ressources affichent `same` sauf le bump de version du fournisseur.
{Ou : N ressources montrent des diffs - voir ci-dessous}

### Diffs Restantes (le cas échéant)
| Ressource | Opération | Ce qui se passe sur `pulumi up` | Risque | Source |
|-----------|-----------|------------------------------|--------|--------|
| aws:s3:Bucket (myBucket) | update (-tags) | No-op, l'état se réconcilie | Aucun | Guide AWS v7 section 3.2 |

Chaque diff restante DOIT citer une source faisant autorité (guide de mise à niveau, documentation du fournisseur,
problème GitHub en amont). « Je crois que c'est attendu » n'est pas une source.

### Étapes Manuelles Requises (le cas échéant)
1. `pulumi state delete '<urn>'` - supprimer l'ancienne liaison de type
2. `pulumi import <type> <name> <id>` - adopter sous le nouveau type
3. `pulumi preview --refresh --run-program` - vérifier que c'est propre

### Avertissements de Dépréciation (aucune action prise)
- Lister le code déprécié-mais-fonctionnel laissé intentionnellement

Si la preview est propre (ou si toutes les diffs restantes sont documentées comme des no-ops avec des sources citées), créez une pull request. Si des diffs non résolues restent, présentez le résumé comme un rapport d'exception et demandez à l'utilisateur comment il souhaite procéder avant de créer une PR.

Références

references/diagnostic-toolbox.md - guides de mise à niveau, schema-tools (installer, exécuter, interpréter la sortie), inspection d'état de stack, types SDK, problèmes GitHub. À lire lors de l'enquête sur les diffs de catégorie B.

provider-upgrade