Pulumi - préparer un projet local et son backend

Ce guide vous mène d'un dossier vide à un projet Pulumi prêt pour un premier lab local sur KVM/libvirt. Vous allez générer le squelette Python, préparer l'environnement virtuel, activer un backend local, créer 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 été rejouee depuis un dossier vide le 1 avril 2026. Elle sert de base de reference pour le guide pratique suivant.

Ce guide existe pour séparer clairement trois sujets que beaucoup de contenus melangent trop tot : le runtime du projet, le backend et la stack, puis la première ressource provisionnee. Quand vous arriverez au guide de la VM, vous saurez déjà d'où vient un problème eventuel.

Ce que vous allez préparer

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 écrire ensuite votre première stack.

Prérequis

Vérifiez d'abord que votre machine répond aux commandes suivantes :

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

Si virsh ne fonctionne pas déjà, corrigez d'abord votre environnement libvirt/KVM. Ce guide suppose que l'accès a qemu:///system est déjà opérationnel.

Etape 1 - Générer 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 maîtriser la suite du bootstrap au lieu de lancer immédiatement un déploiement.

Vous obtenez alors un squelette minimal avec au moins :

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

Etape 2 - Préparer l'environnement Python

Le template Python attend un environnement virtuel. Creez-le puis installez les dépendances 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 dépendances 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

Créer la stack maintenant permet de séparer clairement le projet, la configuration et le state.

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

Vous pouvez vérifier la configuration avec :

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

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

Ce que vous avez maintenant

Vous avez un projet local prêt pour le premier guide pratique :

le runtime Python est initialise ;
le package libvirt est disponible ;
le backend local est actif ;
la stack dev est créée ;
la cible libvirt est configurée.

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

Dépannage

Symptôme	Cause probable	Correctif
`pulumi: command not found`	Le CLI Pulumi n'est pas disponible dans le shell courant	Vérifiez l'installation de la CLIet votre `PATH` avant de reprendre
`permission denied` sur `qemu:///system`	Votre utilisateur n'a pas l'accès libvirt nécessaire	Corrigez l'appartenance au groupe ou la configuration libvirt avant de continuer
`Added package libvirt` n'apparaît 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 déjà été créée	Utilisez `pulumi stack select dev` au lieu de `pulumi stack init dev`

A retenir

Le démarrage valide repose sur pulumi new python --generate-only.
Le bon fichier de dépendances 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 étapes

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 réseau, du disque, du cloud-init et de la VM, puis vérifier le démarrage avec virsh.

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