Pulumi - preparer un projet local et son backend

Ce guide vous mene d'un dossier vide a un projet Pulumi pret pour un premier lab local sur KVM/libvirt. Vous allez generer le squelette Python, preparer l'environnement virtuel, activer un backend local, creer une stack dev et ajouter le package libvirt. A la fin, vous ne dependez ni d'un cloud public ni d'un token Pulumi Cloud pour commencer.

La sequence ci-dessous a ete rejouee depuis un dossier vide le 1 avril 2026. Elle sert de base de reference pour le guide pratique suivant.

Ce guide existe pour separer clairement trois sujets que beaucoup de contenus melangent trop tot : le runtime du projet, le backend et la stack, puis la premiere ressource provisionnee. Quand vous arriverez au guide de la VM, vous saurez deja d'ou vient un probleme eventuel.

Ce que vous allez preparer

un dossier de projet Pulumi Python ;
un environnement virtuel venv ;
une stack locale dev ;
la configuration libvirt:uri vers qemu:///system ;
le package libvirt pour ecrire ensuite votre premiere stack.

Prerequis

Verifiez d'abord que votre machine repond aux commandes suivantes :

pulumi version
python3 --version
virsh --version
virsh list --all

Si virsh ne fonctionne pas deja, corrigez d'abord votre environnement libvirt/KVM. Ce guide suppose que l'acces a qemu:///system est deja operationnel.

Etape 1 - Generer le projet Pulumi Python

Commencez dans un dossier vide :

mkdir -p ~/pulumi-kvm-local
cd ~/pulumi-kvm-local

pulumi new python --generate-only --yes \
  --name pulumi-kvm-local \
  --description "Premiere stack Pulumi locale sur KVM/libvirt"

L'option --generate-only est utile ici parce qu'elle vous laisse maitriser la suite du bootstrap au lieu de lancer immediatement un deploiement.

Vous obtenez alors un squelette minimal avec au moins :

Pulumi.yaml ;
__main__.py ;
requirements.txt.

Etape 2 - Preparer l'environnement Python

Le template Python attend un environnement virtuel. Creez-le puis installez les dependances de base du projet.

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Verification : pip install -r requirements.txt doit installer le package Pulumi sans erreur.

Etape 3 - Ajouter le package libvirt

Le provider libvirt valide dans le lab local est ajoute via le bridge Terraform provider :

pulumi package add terraform-provider dmacvicar/libvirt

Cette commande genere le SDK local puis l'ajoute aux dependances du projet.

Vous pourrez ensuite l'importer en Python avec :

import pulumi_libvirt as libvirt

Verification : a la fin de la commande, Pulumi annonce Added package libvirt.

Etape 4 - Basculer sur le backend local

Le backend local permet d'apprendre Pulumi sans service distant.

pulumi login --local

Verification : la commande doit confirmer une connexion de type file://~.

Etape 5 - Initialiser la stack et la config libvirt

Creer la stack maintenant permet de separer clairement le projet, la configuration et le state.

pulumi stack init dev
pulumi config set libvirt:uri qemu:///system --stack dev

Vous pouvez verifier la configuration avec :

pulumi stack ls
pulumi config get libvirt:uri --stack dev

La stack dev doit apparaitre et la commande de lecture de configuration doit retourner qemu:///system.

Ce que vous avez maintenant

Vous avez un projet local pret pour le premier guide pratique :

le runtime Python est initialise ;
le package libvirt est disponible ;
le backend local est actif ;
la stack dev est creee ;
la cible libvirt est configuree.

La prochaine etape consiste a remplacer le code par une stack qui cree un reseau, un disque clone, un disque cloud-init et une vraie VM KVM.

Depannage

Symptome	Cause probable	Correctif
`pulumi: command not found`	Le CLI Pulumi n'est pas disponible dans le shell courant	Verifiez l'installation de la CLIet votre `PATH` avant de reprendre
`permission denied` sur `qemu:///system`	Votre utilisateur n'a pas l'acces libvirt necessaire	Corrigez l'appartenance au groupe ou la configuration libvirt avant de continuer
`Added package libvirt` n'apparait pas	La commande `pulumi package add` a echoue	Relisez le message d'erreur et rejouez la commande dans le projet active
`stack 'dev' already exists`	La stack a deja ete creee	Utilisez `pulumi stack select dev` au lieu de `pulumi stack init dev`

A retenir

Le demarrage valide repose sur pulumi new python --generate-only.
Le bon fichier de dependances du template Python est requirements.txt.
pulumi login --local suffit pour apprendre Pulumi sans backend SaaS.
La stack dev et la config libvirt:uri doivent exister avant le premier preview utile.

Prochaines etapes

Comprendre stacks et state Clarifier le role du projet, de la stack, du backend local et du preview avant le premier provisionnement.

Premiere stack KVM Ecrire le code du reseau, du disque, du cloud-init et de la VM, puis verifier le demarrage avec virsh.

Hub Pulumi Revenir a la vue d'ensemble de la section et aux concepts a garder en tete.