Pulumi - comprendre projet, stack, state et backend

Quand on debute avec Pulumi, on voit vite apparaître les mots projet, stack, state, backend et preview. Si ces termes restent flous, on peut lancer des commandes sans comprendre ce qu'elles modifient vraiment. Cette page vous donne le modèle mental minimum pour lire un projet Pulumi Python local, comprendre ou sont stockées les informations utiles et savoir pourquoi le cycle preview -> up -> destroy reste central dans le parcours KVM/libvirt.

Vous n'allez pas encore provisionner une nouvelle ressource ici. L'objectif est de rendre les prochains guides beaucoup plus lisibles : vous saurez ce que représente la stack dev, ce que contient Pulumi.yaml, pourquoi le backend local compte, et comment un preview annonce l'infrastructure qui va être créée.

Objectif

Avant d'écrire davantage de code, vous devez pouvoir répondre a ces questions simples :

ou est défini le projet Pulumi ;
ce que désigne exactement une stack ;
ou Pulumi memorise l'état de ce qu'il a cree ;
a quoi sert le backend ;
pourquoi pulumi preview vient avant pulumi up.

Qu'est-ce qu'un projet Pulumi

Le projet est le dossier qui rassemble votre code, votre runtime et vos dépendances. Dans le parcours local de cette section, vous avez cree un projet Python avec un fichier Pulumi.yaml, un fichier __main__.py, un fichier requirements.txt et un environnement venv.

Le projet ne désigne donc pas seulement un répertoire. Il pose aussi le cadre du workflow : nom du projet, runtime choisi, packages ajoutés et conventions utiles a l'exécution.

Dans un projet local déjà initialise, vous pouvez observer ce socle avec :

pulumi stack ls
sed -n '1,80p' Pulumi.yaml

Concrètement, le fichier Pulumi.yaml indique au minimum :

le nom du projet ;
sa description ;
le runtime utilise ;
les packages ajoutés, ici libvirt.

Qu'est-ce qu'une stack

La stack est une instance de votre projet avec sa propre configuration et son propre suivi d'état. Dans ce parcours, la stack s'appelle dev.

L'idée importante est la suivante : le code du projet peut rester le même, alors que la stack change le contexte d'exécution. C'est elle qui porte la configuration de l'environnement courant.

Dans un projet local prepare, vous pouvez voir la stack avec :

pulumi stack ls
pulumi stack select dev

Si la stack dev est selectionnee, cela signifie que les prochaines commandes Pulumi liront sa configuration et agiront sur son état.

A quoi correspond le state

Le state est la mémoire de ce que Pulumi connaît déjà sur votre stack. Il sert a comparer trois choses :

ce que dit votre code ;
ce que Pulumi a memorise précédemment ;
ce qui existe réellement sur la plateforme cible.

Sans ce state, Pulumi ne pourrait pas distinguer une création, une mise a jour, une suppression ou une ressource déjà gérée. C'est lui qui rend possible le raisonnement de réconciliation.

Dans la pratique, le state ne remplace pas la verification côté libvirt. Il faut lire les deux ensemble : le state dit ce que Pulumi croit gérer, virsh montre l'état réel de l'hyperviseur.

Quel est le role du backend

Le backend est l'endroit et le mecanisme utilisés par Pulumi pour stocker et retrouver le state de vos stacks.

Dans cette section, on part volontairement sur un backend local active avec pulumi login --local. Ce choix a deux avantages pedagogiques :

il supprime la dépendance immediate a un service SaaS ;
il rend plus simple la lecture du fonctionnement de base de Pulumi.

Ce choix n'annule pas l'intérêt des backends distants. Il permet simplement de comprendre d'abord le coeur du workflow sur une machine locale.

Pour vérifier la configuration utile du parcours actuel, vous pouvez utiliser :

pulumi config get libvirt:uri --stack dev

Dans le lab valide de cette section, cette commande retourne qemu:///system, ce qui rattache la stack au provider libvirt système.

Pourquoi le preview est une etape centrale

pulumi preview sert a lire le changement avant de l'appliquer. C'est la commande qui vous permet de voir si Pulumi a bien compris votre intention.

Dans le premier guide pratique, le preview doit annoncer au minimum :

le réseau pulumi-lab-net ;
le disque clone pulumi-lab-vm.qcow2 ;
le disque cloud-init ;
la VM pulumi-lab-vm.

Un bon debutant ne cherche pas a aller le plus vite possible vers up. Il apprend d'abord a lire un preview, parce que c'est lui qui évite beaucoup de surprises et de corrections après coup.

Comment les pieces s'articulent ensemble

Vous pouvez lire le workflow local comme une chaîne simple :

le projet contient le code et les métadonnées du runtime ;
la stack choisit le contexte courant ;
le backend stocke le suivi de cette stack ;
le state memorise les ressources déjà gérées ;
le preview annonce l'écart entre le code et l'état connu ;
up applique cet écart sur la cible libvirt.

Si une de ces briques reste floue, on se retrouve vite a lancer des commandes en aveugle. Si elles sont claires, le comportement de Pulumi devient beaucoup plus prévisible.

Scenario concret a garder en tête

Prenons le parcours valide de cette section. Vous avez un projet Python, une stack dev, un backend local et un provider libvirt configure vers qemu:///system.

Quand vous écrivez le code de la première VM :

le projet dit quel runtime et quels packages utiliser ;
la stack dev fournit la configuration de cette execution ;
le backend local retrouve le state associe a dev ;
preview calcule les creations a venir ;
up cree ensuite le réseau, le disque, le cloud-init et la VM ;
destroy ramène la stack a un état propre pour rejouer le scenario.

Ce n'est pas seulement une suite de commandes. C'est un cycle complet de suivi de l'infrastructure.

Pieges fréquents

Piège	Pourquoi c'est trompeur	Bonne lecture
Confondre projet et stack	On croit qu'un seul dossier suffit a définir tout le contexte	Le projet porte le code, la stack porte le contexte d'exécution
Croire que le state est optionnel	On pense que Pulumi lit seulement le code courant	Le state est central pour savoir quoi créer, modifier ou supprimer
Confondre backend et provider	Les deux parlent de "cible" ou de "configuration"	Le backend stocke le suivi, le provider parle a la plateforme
Sauter `preview`	On veut aller plus vite vers `up`	`preview` est justement la lecture de sécurité avant action

A retenir

Le projet rassemble le code, le runtime et les packages Pulumi.
La stack est l'instance de travail qui porte sa configuration et son suivi.
Le backend stocke le state de la stack.
Le state permet a Pulumi de raisonner sur les creations, mises a jour et suppressions.
pulumi preview est la meilleure commande pour vérifier votre intention avant pulumi up.

Prochaines étapes

Preparer le backend local Mettre en place le projet Python, la stack dev et la configuration libvirt si vous partez d'un dossier vide.

Premiere VM KVM Passer du modèle mental a la pratique avec le réseau, le disque clone, le cloud-init et la VM KVM.

Hub Pulumi Revenir a la vue d'ensemble de la section, des runtimes et du parcours local valide.