Réseau virtuel avec Terraform et libvirt

Votre VM atterrit sur le réseau default de libvirt — un réseau partagé avec toutes les autres VMs de la machine. Si deux labs utilisent la même plage IP, les conflits sont inévitables. Avec libvirt_network, vous créez un réseau dédié, isolé et entièrement décrit en code.

Un réseau virtuel dédié résout trois problèmes concrets : l’isolation entre projets (chaque lab a sa plage IP), le DHCP automatique (les VMs obtiennent une IP sans configuration manuelle), et la reproductibilité (le réseau est détruit et recréé avec terraform destroy / terraform apply). Sans réseau dédié, vos labs interfèrent les uns avec les autres et le nettoyage devient manuel.

Ce que vous allez apprendre :

• Créer un réseau NAT isolé avec DHCP via libvirt_network
• Connecter une VM au réseau dédié avec une référence dynamique
• Comprendre depends_on et la différence avec les dépendances implicites
• Vérifier le réseau avec virsh net-list et virsh net-dumpxml

Prérequis : avoir suivi le guide Première infrastructure et avoir KVM actif sur votre machine.

Ce qu’est un réseau virtuel libvirt

Un réseau virtuel libvirt est un bridge logiciel créé dans KVM qui connecte des VMs entre elles et, optionnellement, vers l’extérieur. C’est l’équivalent d’un switch réseau physique, mais entièrement logiciel et géré par libvirt.

L'analogie du switch dédié

Imaginez que chaque projet a son propre switch réseau dans une armoire. Les machines branchées sur le switch A ne voient pas celles du switch B. C’est exactement ce que fait libvirt_network : un réseau isolé par projet.

En mode NAT (le plus courant pour les labs), le réseau fournit :

• Une passerelle (gateway) qui route le trafic vers l’extérieur
• Un serveur DHCP qui distribue automatiquement des adresses IP aux VMs
• Une isolation : les VMs du réseau ne sont pas visibles depuis d’autres réseaux libvirt

Pourquoi créer un réseau dédié

Sans réseau dédié, toutes vos VMs partagent le réseau default de libvirt :

Situation	Réseau default	Réseau dédié
Deux labs en parallèle	Conflits d’IP possibles	Plages IP séparées
Nettoyage	Impossible de détruire le réseau default	terraform destroy supprime tout
Reproductibilité	Dépend de l’état de la machine	Décrit en code, reproductible

Glissez pour voir

Dès que vous travaillez sur plus d’un projet Terraform en parallèle, un réseau dédié par lab devient indispensable.

Créer le lab

Préparez le répertoire du lab et écrivez la configuration :

1. Créez le répertoire de travail :

   mkdir -p ~/terraform-reseau-virtuel
   cd ~/terraform-reseau-virtuel

2. Créez le fichier versions.tf :

   terraform {
     required_version = ">= 1.11.0"
     required_providers {
       libvirt = {
         source  = "dmacvicar/libvirt"
         version = "~> 0.8"
       }
     }
   }
   
   provider "libvirt" {
     uri = "qemu:///system"
   }

3. Créez le fichier main.tf avec le réseau, le disque et la VM :

   # Réseau NAT isolé avec DHCP
   resource "libvirt_network" "lab_net" {
     name      = "lab14-net"
     autostart = false
   
     forward = { mode = "nat" }
   
     ips = [{
       address = "10.99.14.1"
       netmask = "255.255.255.0"
       dhcp    = { ranges = [{ start = "10.99.14.100", end = "10.99.14.200" }] }
     }]
   }
   
   # Volume disque de la VM
   resource "libvirt_volume" "disk" {
     name   = "lab14-vm.qcow2"
     pool   = "default"
     target = { format = { type = "qcow2" } }
     create = { content = { url = pathexpand("~/images/ubuntu-24.04-cloudimg.img") } }
   }
   
   # VM connectée au réseau dédié
   resource "libvirt_domain" "vm" {
     name        = "lab14-vm"
     type        = "kvm"
     memory      = 512
     memory_unit = "MiB"
     vcpu        = 1
   
     os = { type = "hvm", type_arch = "x86_64", type_machine = "q35" }
   
     devices = {
       disks = [{
         source = { file = { file = libvirt_volume.disk.path } }
         target = { dev = "vda", bus = "virtio" }
       }]
       interfaces = [{
         model  = { type = "virtio" }
         source = { network = { network = libvirt_network.lab_net.name } }
       }]
     }
   
   }
   
   output "network_name" {
     value       = libvirt_network.lab_net.name
     description = "Nom du réseau virtuel créé"
   }
   
   output "vm_name" {
     value       = libvirt_domain.vm.name
     description = "Nom de la VM connectée au réseau"
   }

4. Initialisez et appliquez :

   terraform init
   terraform apply -auto-approve

   Terraform crée les ressources dans l’ordre des dépendances — le réseau en premier, puis le disque, enfin la VM.

Vérifier le résultat

Terraform affiche la progression pendant le apply. Notez l’ordre : le réseau est créé en premier, puis le disque, enfin la VM (car la VM dépend des deux autres) :

libvirt_network.lab_net: Creating...
libvirt_network.lab_net: Creation complete after 1s [id=...]
libvirt_volume.disk: Creating...
libvirt_volume.disk: Creation complete after 1s [id=...]
libvirt_domain.vm: Creating...
libvirt_domain.vm: Creation complete after 2s [id=...]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

network_name = "lab14-net"
vm_name = "lab14-vm"

Vérifiez que le réseau existe dans libvirt :

virsh net-list --all

 Name        State    Autostart   Persistent
----------------------------------------------
 default     active   yes         yes
 lab14-net   active   no          yes

La commande virsh net-dumpxml lab14-net affiche la configuration complète du réseau tel que libvirt l’a créé — vous retrouverez la plage DHCP 10.99.14.100–200 et le bridge associé.

Affichez les outputs à tout moment avec :

terraform output

network_name = "lab14-net"
vm_name = "lab14-vm"

À retenir

L’ordre de création dans les logs confirme que Terraform respecte les dépendances : le réseau est prêt avant que la VM ne démarre. C’est le graphe de dépendances en action.

Anatomie de libvirt_network

Maintenant que le réseau fonctionne, détaillons chaque attribut de la ressource libvirt_network :

resource "libvirt_network" "lab_net" {
  name      = "lab14-net"      # Nom visible dans virsh net-list
  autostart = false            # Ne pas démarrer au boot de la machine hôte

  forward = { mode = "nat" }   # Trafic sortant via NAT (accès internet pour la VM)

  ips = [{
    address = "10.99.14.1"          # Adresse du routeur (gateway) sur ce réseau
    netmask = "255.255.255.0"       # Masque /24 → 254 adresses disponibles
    dhcp = { ranges = [{
      start = "10.99.14.100"        # Première adresse distribuée par DHCP
      end   = "10.99.14.200"        # Dernière adresse distribuée par DHCP
    }] }
  }]
}

Modes de forwarding disponibles

Le champ forward.mode accepte plusieurs valeurs :

• "nat" : les VMs accèdent à internet via NAT. C’est le mode par défaut pour les labs.
• "route" : routage direct sans NAT (nécessite une configuration du routeur hôte).
• "bridge" : la VM est directement sur le réseau physique.
• "" (vide) : réseau complètement isolé, aucun accès extérieur.

Pour un lab isolé sans accès internet, retirez simplement le bloc forward.

À retenir

La ressource libvirt_network est l’équivalent Terraform de la commande virsh net-define + virsh net-start. La différence : Terraform gère aussi la destruction et détecte les changements.

Le rôle de depends_on

depends_on : à utiliser quand la dépendance n'est pas visible dans le code

Imaginez que vous allumez votre box internet, puis immédiatement votre ordinateur. Si la box n’a pas fini de démarrer, votre ordinateur ne trouvera pas le réseau.

En Terraform, ce cas apparaît surtout quand une dépendance est comportementale et qu’aucune référence directe ne la montre dans le code.

Dans cet exemple, la VM référence déjà explicitement le réseau avec libvirt_network.lab_net.name. Cette référence suffit à créer une dépendance implicite : Terraform sait qu’il doit créer le réseau avant la VM.

Si vous vouliez malgré tout rendre cette intention visible, vous pourriez ajouter :

depends_on = [libvirt_network.lab_net]

… mais ce serait ici redondant, pas indispensable.

À retenir

Si votre code contient déjà une référence comme libvirt_network.lab_net.name, la dépendance est implicite. depends_on devient utile quand la dépendance est comportementale et qu’aucune référence directe ne l’exprime.

Référencer le réseau dans la VM

La connexion entre la VM et le réseau se fait dans le bloc devices.interfaces :

interfaces = [{
  model  = { type = "virtio" }
  source = { network = { network = libvirt_network.lab_net.name } }
  #                               ↑ référence dynamique au nom du réseau
}]

En écrivant libvirt_network.lab_net.name au lieu de "lab14-net" en dur, vous créez une dépendance implicite : si le nom du réseau change, la VM est automatiquement mise à jour. C’est une bonne pratique Terraform — toujours préférer les références dynamiques aux valeurs en dur.

À retenir

Utilisez type_ressource.nom_logique.attribut pour référencer une autre ressource. Cela crée automatiquement une dépendance et propage les changements.

Aller plus loin avec libvirt_network

La ressource libvirt_network supporte des attributs avancés utiles en pratique :

Attribut	Utilité
dns	Configurer un serveur DNS local pour les VMs
domain	Associer un domaine DNS (ex. lab.local)
bridge	Spécifier le nom du bridge Linux créé
mtu	Ajuster la MTU pour des réseaux spéciaux
ipv6	Activer IPv6 sur le réseau

Glissez pour voir

Pour la documentation complète des attributs, consultez le provider libvirt v0.9.7.

Nettoyer le lab

terraform destroy -auto-approve

Terraform détruit les ressources dans l’ordre inverse : VM d’abord, puis disque et réseau :

libvirt_domain.vm: Destroying...
libvirt_domain.vm: Destruction complete after 1s
libvirt_volume.disk: Destroying...
libvirt_network.lab_net: Destroying...
libvirt_volume.disk: Destruction complete after 0s
libvirt_network.lab_net: Destruction complete after 0s

Destroy complete! Resources: 3 destroyed.

Vérifiez que le nettoyage est complet :

virsh net-list --all | grep lab14
# (aucune sortie — réseau supprimé)

Cette propriété de destruction inversée est expliquée en détail dans le guide Détruire proprement.

À retenir

• libvirt_network crée un bridge virtuel KVM géré entièrement par Terraform.
• Le mode nat donne accès internet aux VMs sans configuration supplémentaire.
• depends_on sert surtout quand aucune référence directe n’exprime déjà la dépendance.
• Référencer libvirt_network.lab_net.name au lieu d’un nom en dur crée une dépendance automatique.
• virsh net-list confirme que le réseau existe indépendamment de Terraform.
• L’ordre de destruction est l’inverse de l’ordre de création : VM → disque → réseau.

Prochaines étapes

Variables et outputs Paramétrez votre infrastructure : noms, tailles, configurations sans modifier le code.

Détruire proprement Comprendre l'ordre de destruction, le destroy ciblé et la gestion du state partiel.

Déboguer un apply Identifier et corriger les erreurs Terraform les plus fréquentes, par catégorie.

×

📖 Voir la documentation →