Pulumi - comprendre projet, stack, state et backend

Quand on debute avec Pulumi, on voit vite apparaitre 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 modele mental minimum pour lire un projet Pulumi Python local, comprendre ou sont stockees 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 represente la stack dev, ce que contient Pulumi.yaml, pourquoi le backend local compte, et comment un preview annonce l’infrastructure qui va etre creee.

Objectif

Avant d’ecrire davantage de code, vous devez pouvoir repondre a ces questions simples :

ou est defini le projet Pulumi ;
ce que designe exactement une stack ;
ou Pulumi memorise l’etat 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 dependances. 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 designe donc pas seulement un repertoire. Il pose aussi le cadre du workflow : nom du projet, runtime choisi, packages ajoutes et conventions utiles a l’execution.

Dans un projet local deja initialise, vous pouvez observer ce socle avec :

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

Concretement, le fichier Pulumi.yaml indique au minimum :

le nom du projet ;
sa description ;
le runtime utilise ;
les packages ajoutes, 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’etat. Dans ce parcours, la stack s’appelle dev.

L’idee importante est la suivante : le code du projet peut rester le meme, alors que la stack change le contexte d’execution. 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 etat.

A quoi correspond le state

Le state est la memoire de ce que Pulumi connait deja sur votre stack. Il sert a comparer trois choses :

ce que dit votre code ;
ce que Pulumi a memorise precedemment ;
ce qui existe reellement sur la plateforme cible.

Sans ce state, Pulumi ne pourrait pas distinguer une creation, une mise a jour, une suppression ou une ressource deja geree. C’est lui qui rend possible le raisonnement de reconciliation.

Dans la pratique, le state ne remplace pas la verification cote libvirt. Il faut lire les deux ensemble : le state dit ce que Pulumi croit gerer, virsh montre l’etat reel de l’hyperviseur.

Quel est le role du backend

Le backend est l’endroit et le mecanisme utilises 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 dependance immediate a un service SaaS ;
il rend plus simple la lecture du fonctionnement de base de Pulumi.

Ce choix n’annule pas l’interet des backends distants. Il permet simplement de comprendre d’abord le coeur du workflow sur une machine locale.

Pour verifier 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 systeme.

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 reseau 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 evite beaucoup de surprises et de corrections apres coup.

Comment les pieces s’articulent ensemble

Vous pouvez lire le workflow local comme une chaine simple :

le projet contient le code et les metadonnees du runtime ;
la stack choisit le contexte courant ;
le backend stocke le suivi de cette stack ;
le state memorise les ressources deja gerees ;
le preview annonce l’ecart entre le code et l’etat connu ;
up applique cet ecart 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 previsible.

Scenario concret a garder en tete

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 ecrivez le code de la premiere 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 reseau, le disque, le cloud-init et la VM ;
destroy ramene la stack a un etat 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 frequents

Piege	Pourquoi c’est trompeur	Bonne lecture
Confondre projet et stack	On croit qu’un seul dossier suffit a definir tout le contexte	Le projet porte le code, la stack porte le contexte d’execution
Croire que le state est optionnel	On pense que Pulumi lit seulement le code courant	Le state est central pour savoir quoi creer, 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 securite 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 verifier votre intention avant pulumi up.

Prochaines etapes

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 modele mental a la pratique avec le reseau, 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.