Terraform + libvirt (KVM) : déployer des VMs avec Cloud-Init

Créer une VM KVM à la main, c'est bien pour apprendre. Mais pour un lab de 5, 10 ou 20 machines ? Terraform automatise la création de VMs libvirt avec des configurations reproductibles. Ce guide vous montre comment faire proprement, avec Cloud-Init et les bonnes pratiques 2026.

À la fin de ce guide, vous aurez :

• Un template Terraform réutilisable pour créer des VMs KVM
• Une configuration Cloud-Init robuste (SSH, hostname, packages)
• Les bonnes pratiques sécurité (pas de security_driver = none)
• Des commandes de debug pour dépanner sans interface graphique

Prérequis

Élément	Version	Vérification
KVM/libvirt	Ubuntu 22.04+ ou équivalent	virsh version
Terraform ou OpenTofu	≥ 1.6.0	terraform version ou tofu version
Image cloud	Ubuntu 24.04 QCOW2	Téléchargement ci-dessous
Clé SSH	Ed25519 recommandée	ls ~/.ssh/id_ed25519.pub

Glissez pour voir

Guides préalables recommandés

Si vous débutez avec KVM, consultez d'abord :

• Installation KVM/libvirt
• Commandes virsh essentielles
• Réseaux libvirt (NAT vs Bridge)

Ce que vous allez construire

terraform-kvm/
├── main.tf              # Ressources principales
├── variables.tf         # Variables configurables
├── outputs.tf           # Sorties (IP, hostname)
├── versions.tf          # Providers et versions
└── cloudinit/
    ├── user-data.yaml   # Configuration Cloud-Init
    └── network-config.yaml

Architecture cible :

┌─────────────────────────────────────────────────────────┐
│                    Hôte KVM                             │
│  ┌───────────────┐     ┌───────────────┐               │
│  │  Pool default │     │ Réseau NAT    │               │
│  │  (images)     │     │ (192.168.122.x)│               │
│  └───────┬───────┘     └───────┬───────┘               │
│          │                     │                        │
│          ▼                     ▼                        │
│  ┌─────────────────────────────────────┐               │
│  │           VM créée par Terraform    │               │
│  │  • Ubuntu 24.04 (cloud image)       │               │
│  │  • Cloud-Init configuré             │               │
│  │  • qemu-guest-agent installé        │               │
│  └─────────────────────────────────────┘               │
└─────────────────────────────────────────────────────────┘

Partie 1 : Préparer l'environnement

Vérifier libvirt

1. Vérifier que libvirtd fonctionne

   systemctl is-active libvirtd

   Sortie attendue : active

2. Vérifier votre appartenance au groupe libvirt

   groups | grep -E "libvirt|kvm"

   Si absent :

   sudo usermod -aG libvirt,kvm $USER
   # Puis déconnectez-vous et reconnectez-vous

3. Tester l'accès à qemu:///system

   virsh -c qemu:///system list --all

   Cette commande doit s'exécuter sans sudo. Si elle échoue, voir la section Dépannage.

Télécharger l'image cloud Ubuntu

Les images cloud sont des QCOW2 minimalistes, optimisées pour Cloud-Init :

# Créer un dossier pour les images de base
sudo mkdir -p /var/lib/libvirt/images/base

# Télécharger Ubuntu 24.04 cloud image
sudo wget -O /var/lib/libvirt/images/base/ubuntu-24.04-server-cloudimg-amd64.img \
  https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

# Vérifier le téléchargement
qemu-img info /var/lib/libvirt/images/base/ubuntu-24.04-server-cloudimg-amd64.img

Pourquoi une image cloud ?

Contrairement à une ISO, une image cloud est déjà installée. Elle démarre en quelques secondes et se configure automatiquement via Cloud-Init. Pas besoin d'installation manuelle.

Créer la clé SSH (si absente)

# Générer une clé Ed25519 (plus sécurisée que RSA)
ssh-keygen -t ed25519 -C "terraform-kvm" -f ~/.ssh/id_ed25519 -N ""

Partie 2 : Projet Terraform

Créer la structure du projet

mkdir -p ~/terraform-kvm/cloudinit
cd ~/terraform-kvm

Fichier versions.tf, Providers et versions

Créez versions.tf :

versions.tf

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    libvirt = {
      source  = "dmacvicar/libvirt"
      version = "~> 0.9.0"  # Version 2025+ avec breaking changes
    }
  }
}

provider "libvirt" {
  # Connexion au démon libvirt système (pas session utilisateur)
  uri = "qemu:///system"
}

Breaking changes provider 0.9.x

Le provider dmacvicar/libvirt 0.9.x introduit des changements majeurs par rapport aux versions 0.7/0.8 :

• Nouvelle structure pour libvirt_volume (target, create, backing_store)
• Bloc devices obligatoire pour libvirt_domain
• meta_data obligatoire pour libvirt_cloudinit_disk
• Memory en KiB (pas MiB)

Si vous migrez depuis une ancienne version, voir la section Migration 0.8 → 0.9 ci-dessous.

qemu:///system vs qemu:///session

URI	Accès	Pool par défaut	Réseau
qemu:///system	Tous les utilisateurs	/var/lib/libvirt/images	Complet (NAT, bridge)
qemu:///session	Utilisateur courant	~/.local/share/libvirt/images	Limité (usermode)

Glissez pour voir

Recommandation : utilisez qemu:///system pour la plupart des cas. C'est le mode "production-like".

Fichier variables.tf, Configuration

Créez variables.tf :

variables.tf

variable "vm_name" {
  description = "Nom de la VM"
  type        = string
  default     = "tf-kvm-01"
}

variable "memory_mb" {
  description = "Mémoire RAM en Mo"
  type        = number
  default     = 2048
}

variable "vcpu" {
  description = "Nombre de vCPU"
  type        = number
  default     = 2
}

variable "disk_size_gb" {
  description = "Taille du disque en Go (expansion de l'image cloud)"
  type        = number
  default     = 20
}

variable "base_image_path" {
  description = "Chemin vers l'image cloud de base"
  type        = string
  default     = "/var/lib/libvirt/images/base/ubuntu-24.04-server-cloudimg-amd64.img"
}

variable "ssh_public_key_path" {
  description = "Chemin vers la clé SSH publique"
  type        = string
  default     = "~/.ssh/id_ed25519.pub"
}

variable "network_name" {
  description = "Nom du réseau libvirt"
  type        = string
  default     = "default"
}

variable "pool_name" {
  description = "Nom du pool de stockage libvirt"
  type        = string
  default     = "default"
}

Fichier main.tf, Ressources

Créez main.tf :

main.tf

# ============================================================
# Provider libvirt 0.9.x - Configuration complète
# ============================================================

# 1) Volume de base (image cloud Ubuntu - copie locale)
resource "libvirt_volume" "base" {
  name   = "ubuntu-24.04-base.qcow2"
  pool   = var.pool_name

  target = {
    format = { type = "qcow2" }
  }

  create = {
    content = {
      url = var.base_image_path
    }
  }
}

# 2) Volume OS de la VM (overlay CoW sur l'image de base)
resource "libvirt_volume" "os_disk" {
  name     = "${var.vm_name}.qcow2"
  pool     = var.pool_name
  capacity = var.disk_size_gb * 1024 * 1024 * 1024  # Conversion en bytes

  target = {
    format = { type = "qcow2" }
  }

  # Utilise l'image de base comme backing store (Copy-on-Write)
  backing_store = {
    path   = libvirt_volume.base.path
    format = { type = "qcow2" }
  }
}

# 3) Cloud-Init : génération de l'ISO de configuration
resource "libvirt_cloudinit_disk" "init" {
  name = "${var.vm_name}-cloudinit"

  user_data = templatefile("${path.module}/cloudinit/user-data.yaml", {
    hostname   = var.vm_name
    public_key = file(pathexpand(var.ssh_public_key_path))
  })

  # meta_data est OBLIGATOIRE en 0.9.x
  meta_data = yamlencode({
    instance-id    = var.vm_name
    local-hostname = var.vm_name
  })

  network_config = file("${path.module}/cloudinit/network-config.yaml")
}

# 4) Volume pour l'ISO Cloud-Init (upload dans le pool)
resource "libvirt_volume" "cloudinit" {
  name = "${var.vm_name}-cloudinit.iso"
  pool = var.pool_name

  create = {
    content = {
      url = libvirt_cloudinit_disk.init.path
    }
  }
}

# 5) Domaine (VM) - Syntaxe 0.9.x avec bloc devices
resource "libvirt_domain" "vm" {
  name   = var.vm_name
  type   = "kvm"                     # Type obligatoire en 0.9.x
  memory = var.memory_mb * 1024      # Attention : en KiB, pas MiB !
  vcpu   = var.vcpu

  # CPU host-passthrough : expose tous les flags CPU de l'hôte (AES-NI,
  # SSE4.x, AVX...). Sans ça, libvirt utilise mode=custom model=qemu64
  # qui n'expose que des instructions x86_64 minimales, et les kernels
  # récents (RHEL/AlmaLinux 10, Fedora ≥ 40) bloquent au chargement
  # des modules crypto.
  cpu = {
    mode = "host-passthrough"
  }

  os = {
    type         = "hvm"
    type_machine = "q35"
    firmware     = "efi"
    # Désactive Secure Boot : libvirt 10+ enrôle par défaut les clés
    # Microsoft (OVMF_CODE_4M.ms.fd) qui rejettent les kernels non
    # signés MS. Les images cloud Linux démarrent puis se bloquent à
    # /init faute de modules virtio chargés.
    # Ordre alphabétique des features OBLIGATOIRE : le provider 0.9.x
    # retourne les features triées et compare strictement avec ce
    # qu'on lui donne (sinon "Provider produced inconsistent result").
    firmware_info = {
      features = [
        { enabled = "no", name = "enrolled-keys" },
        { enabled = "no", name = "secure-boot" },
      ]
    }
  }

  features = {
    acpi = true
  }

  # Bloc devices : structure obligatoire en 0.9.x
  devices = {
    # Disque OS
    disks = [
      {
        # Driver explicite obligatoire pour qcow2 !
        driver = {
          name = "qemu"
          type = "qcow2"
        }
        source = {
          volume = {
            pool   = var.pool_name
            volume = libvirt_volume.os_disk.name
          }
        }
        target = {
          dev = "vda"
          bus = "virtio"
        }
      },
      # Disque Cloud-Init (CDROM)
      {
        device = "cdrom"
        driver = {
          name = "qemu"
          type = "raw"
        }
        source = {
          volume = {
            pool   = var.pool_name
            volume = libvirt_volume.cloudinit.name
          }
        }
        target = {
          dev = "sda"
          bus = "sata"
        }
      }
    ]

    # Interface réseau
    interfaces = [
      {
        type  = "network"
        model = { type = "virtio" }
        source = {
          network = { network = var.network_name }
        }
      }
    ]

    # Console série (indispensable pour debug)
    serials = [
      {
        type = "pty"
        target = {
          port = 0
          type = "isa-serial"
        }
      }
    ]

    # Support graphique (optionnel, pour virt-manager)
    graphics = [
      {
        spice = {
          autoport = "yes"
        }
      }
    ]
  }

  running = true
}

Driver qcow2 obligatoire

En provider 0.9.x, le driver n'est pas auto-détecté. Sans driver = { name = "qemu", type = "qcow2" }, le disque sera traité comme raw et la VM ne bootera pas.

Configuration Cloud-Init

Cloud-Init est le standard pour configurer les VMs cloud au premier démarrage. Il gère : hostname, utilisateurs, clés SSH, packages, commandes.

Créez cloudinit/user-data.yaml :

cloudinit/user-data.yaml

#cloud-config

# Hostname de la VM
hostname: ${hostname}
fqdn: ${hostname}.local
manage_etc_hosts: true

# Utilisateur par défaut
users:
  - name: ubuntu
    groups: [adm, sudo, docker]
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    lock_passwd: true  # Désactive le mot de passe (SSH key only)
    ssh_authorized_keys:
      - ${public_key}

# Paquets à installer
packages:
  - qemu-guest-agent  # Indispensable pour récupérer l'IP
  - curl
  - vim
  - htop

# Activer l'agent QEMU au démarrage
runcmd:
  - systemctl enable --now qemu-guest-agent

# Autoriser SSH par clé uniquement
ssh_pwauth: false

# Mise à jour des paquets au premier boot
package_update: true
package_upgrade: false  # Évite les surprises de temps

# Message final
final_message: |
  Cloud-init terminé après $UPTIME secondes.
  Hostname: ${hostname}
  Connectez-vous avec: ssh ubuntu@<IP>

Créez cloudinit/network-config.yaml :

cloudinit/network-config.yaml

version: 2
ethernets:
  default:
    match:
      driver: virtio*   # Match n'importe quelle interface virtio
    dhcp4: true
    dhcp6: false

Pourquoi match: driver au lieu de eth0 ?

Les images cloud Ubuntu modernes utilisent des noms d'interfaces prédictibles (enp*, ens*), pas eth0. En utilisant match: { driver: virtio* }, vous ciblez toutes les interfaces virtio, quelle que soit leur nom.

Sécurité : pas de mot de passe root

Dans l'exemple ci-dessus, lock_passwd: true désactive l'authentification par mot de passe. C'est la bonne pratique : SSH key only.

Si vous avez absolument besoin d'un mot de passe (debug ponctuel), utilisez un hash :

# À éviter en production !
password: $6$rounds=4096$...  # Généré avec mkpasswd
chpasswd:
  expire: false

Fichier outputs.tf, Récupérer les informations

En provider 0.9.x, l'IP n'est plus accessible directement via network_interface[0].addresses. On utilise un data source dédié :

Créez outputs.tf :

outputs.tf

# Data source pour récupérer les IPs via DHCP leases
data "libvirt_domain_interface_addresses" "vm" {
  domain = libvirt_domain.vm.name
  source = "lease"  # Utilise le serveur DHCP de libvirt

  depends_on = [libvirt_domain.vm]
}

output "vm_name" {
  description = "Nom de la VM"
  value       = libvirt_domain.vm.name
}

output "vm_id" {
  description = "ID libvirt de la VM"
  value       = libvirt_domain.vm.id
}

output "vm_uuid" {
  description = "UUID de la VM"
  value       = libvirt_domain.vm.uuid
}

# Toutes les IPs (format 0.9.x : interfaces[].addrs[].addr)
output "ip_addresses" {
  description = "Adresses IP de la VM"
  value = [
    for iface in data.libvirt_domain_interface_addresses.vm.interfaces :
    [for a in iface.addrs : a.addr]
  ]
}

# IP principale pour faciliter l'usage
output "primary_ip" {
  description = "Adresse IP principale de la VM"
  value = try(
    data.libvirt_domain_interface_addresses.vm.interfaces[0].addrs[0].addr,
    "Non disponible"
  )
}

output "ssh_command" {
  description = "Commande SSH pour se connecter"
  value = try(
    "ssh ubuntu@${data.libvirt_domain_interface_addresses.vm.interfaces[0].addrs[0].addr}",
    "IP non disponible - attendre cloud-init puis: tofu refresh"
  )
}

IP vide au premier apply ?

C'est normal ! Cloud-init et l'agent QEMU mettent quelques secondes à démarrer. Attendez 30-60 secondes, puis :

terraform refresh
terraform output primary_ip

Ou directement avec virsh :

virsh net-dhcp-leases default

Partie 3 : Déployer la VM

Initialiser et appliquer

1. Initialiser Terraform

   cd ~/terraform-kvm
   terraform init

   Sortie attendue :

   Initializing the backend...
   Initializing provider plugins...
   - Finding dmacvicar/libvirt versions matching "~> 0.8"...
   - Installing dmacvicar/libvirt v0.8.1...
   
   Terraform has been successfully initialized!

2. Valider la configuration

   terraform validate

   Sortie attendue : Success! The configuration is valid.

3. Prévisualiser les changements

   terraform plan

   Vérifiez que 3 ressources seront créées :

   • libvirt_volume.os_disk
   • libvirt_cloudinit_disk.init
   • libvirt_domain.vm

4. Appliquer

   terraform apply

   Tapez yes pour confirmer.

5. Récupérer l'IP

   terraform output ip_addresses

   L'IP est vide au premier apply ?

   C'est normal ! L'agent QEMU met quelques secondes à démarrer. Attendez 30 secondes, puis :

   terraform refresh
   terraform output ip_addresses

   Ou directement avec virsh :

   virsh domifaddr tf-kvm-01 --source agent

Vérifier la VM

# État de la VM
virsh list --all

# Détails
virsh dominfo tf-kvm-01

# IP via l'agent QEMU
virsh domifaddr tf-kvm-01 --source agent

Se connecter en SSH

# Récupérer la commande SSH
terraform output ssh_command

# Ou directement (remplacez l'IP)
ssh ubuntu@192.168.122.xxx

Partie 4 : Debug et dépannage

Console série (sans réseau)

Si la VM ne démarre pas ou n'obtient pas d'IP, la console série est votre meilleur ami :

virsh console tf-kvm-01

Pour quitter : Ctrl + ]

Vérifier Cloud-Init

Depuis la console ou SSH :

# Statut global
cloud-init status --long

# Logs détaillés
sudo cat /var/log/cloud-init-output.log

# Configuration appliquée
sudo cat /var/lib/cloud/instance/user-data.txt

Statut	Signification
status: done	Cloud-Init terminé avec succès
status: running	Encore en cours (patience)
status: error	Erreur, consultez les logs

Glissez pour voir

Problèmes courants

Symptôme	Cause probable	Solution
Error: virsh: command not found	libvirt non installé	Guide installation
failed to connect to the hypervisor	libvirtd arrêté ou permissions	sudo systemctl start libvirtd + vérifier groupe
IP vide même après 1 minute	qemu-guest-agent non installé	Vérifier Cloud-Init user-data
Permission denied sur le pool	Droits fichier ou AppArmor	Voir section Sécurité ci-dessous
Disque corrompu après apply	Image source modifiée	Utiliser une image "golden" en lecture seule
Boot bloqué dans /init (AlmaLinux/RHEL 10)	Secure Boot enrôlé par libvirt + clés MS	Ajouter firmware_info.features avec secure-boot=no + enrolled-keys=no
Kernel panic au démarrage (distros récentes)	CPU qemu64 générique sans flags modernes	Ajouter cpu = { mode = "host-passthrough" } au domain
Provider produced inconsistent result sur firmware_info.features	Bug provider 0.9.x : tri alphabétique au retour	Déclarer les features dans l'ordre alphabétique du name

Glissez pour voir

Le piège Secure Boot par défaut sur libvirt 10+

Depuis libvirt 10, l'auto-sélection du firmware UEFI privilégie OVMF_CODE_4M.ms.fd (clés Microsoft enrôlées + Secure Boot actif). Le résultat sur les images cloud Linux : la VM démarre, charge le kernel, puis se bloque dans /init parce que les modules virtio ne sont pas signés Microsoft donc rejetés par Secure Boot.

Diagnostic : virsh dumpxml <vm> | grep -A 3 firmware. Si vous voyez secure='yes' ou OVMF_CODE_4M.ms.fd, c'est ça.

Fix dans le bloc os du libvirt_domain :

firmware_info = {
  features = [
    { enabled = "no", name = "enrolled-keys" },
    { enabled = "no", name = "secure-boot" },
  ]
}

L'ordre alphabétique des name est obligatoire à cause d'un bug du provider 0.9.x qui retourne les features triées et compare strictement.

CPU mode='host-passthrough' obligatoire pour les kernels récents

Sans cpu = { mode = "host-passthrough" }, libvirt expose à la VM un CPU qemu64 générique qui n'a ni AES-NI, ni SSE4, ni AVX. Les kernels AlmaLinux 10, RHEL 10 et Fedora récents font des appels crypto au boot qui exigent ces instructions modernes : la VM se fige silencieusement dans /init au chargement du premier module crypto.

Vérification après apply : virsh dumpxml <vm> | grep cpu doit afficher mode='host-passthrough'. Si vous voyez mode='custom' avec <model>qemu64</model>, c'est la cause.

L'inconvénient de host-passthrough : la VM ne peut pas migrer à chaud vers un hôte avec un CPU différent. Acceptable en homelab et formation, à réfléchir en production multi-hôte.

Logs libvirtd

# Logs en temps réel
journalctl -u libvirtd -f

# Erreurs récentes
journalctl -u libvirtd --since "10 minutes ago" | grep -i error

Partie 5 : Sécurité, Ne pas désactiver les protections

Anti-pattern : security_driver = none

Beaucoup de tutoriels conseillent d'ajouter dans /etc/libvirt/qemu.conf :

security_driver = "none"

C'est une très mauvaise idée. Vous désactivez AppArmor/SELinux/sVirt, perdant une couche d'isolation critique entre les VMs.

Pourquoi les tutoriels le font ?

Quand Terraform (ou vous) crée un fichier dans /var/lib/libvirt/images, il peut avoir les mauvais labels de sécurité. libvirt refuse alors de démarrer la VM avec une erreur de permission.

La solution "facile" (et dangereuse) : désactiver le driver de sécurité.

La vraie solution

Ubuntu/Debian (AppArmor)

1. Vérifier le profil AppArmor

   sudo aa-status | grep libvirt

2. Ajouter le chemin au profil si nécessaire

   Si vous utilisez un pool personnalisé (ex: /data/vms), modifiez :

   sudo nano /etc/apparmor.d/local/usr.sbin.libvirtd

   Ajoutez :

   /data/vms/** rwk,

3. Recharger AppArmor

   sudo systemctl reload apparmor
   sudo systemctl restart libvirtd

RHEL/Rocky (SELinux)

1. Vérifier le contexte des fichiers

   ls -Z /var/lib/libvirt/images/

   Les fichiers doivent avoir le contexte svirt_image_t.

2. Restaurer le contexte si incorrect

   sudo restorecon -Rv /var/lib/libvirt/images/

3. Pour un chemin personnalisé

   sudo semanage fcontext -a -t svirt_image_t "/data/vms(/.*)?"
   sudo restorecon -Rv /data/vms/

Permissions du pool par défaut

# Vérifier le propriétaire
ls -la /var/lib/libvirt/images/

# Doit appartenir à root:root ou libvirt-qemu selon la distro
# Avec les permissions 711 sur le dossier

Migration 0.8 → 0.9

Si vous avez des configurations existantes avec le provider 0.7 ou 0.8, voici les changements à appliquer.

Tableau récapitulatif des changements

Élément	Provider 0.8.x	Provider 0.9.x
libvirt_volume	source, format	create.content.url, target.format.type
backing file	base_volume_id	backing_store = { path, format }
libvirt_cloudinit_disk	meta_data optionnel	meta_data obligatoire
libvirt_domain	blocs disk {}, network_interface {}	devices = { disks = [...], interfaces = [...] }
memory	en MiB	en KiB (multiplier par 1024)
driver qcow2	auto-détecté	explicite obligatoire
récupération IP	network_interface[0].addresses	data.libvirt_domain_interface_addresses
CPU pour distros récentes	implicite	cpu = { mode = "host-passthrough" } souvent obligatoire
Secure Boot UEFI	non auto-enrôlé	auto-enrôlé sur libvirt 10+ → firmware_info.features à désactiver

Glissez pour voir

Exemple de migration : libvirt_volume

Avant (0.8.x)

resource "libvirt_volume" "os_disk" {
  name   = "vm.qcow2"
  pool   = "default"
  source = "/var/lib/libvirt/images/base.img"
  format = "qcow2"
  size   = 20 * 1024 * 1024 * 1024
}

Après (0.9.x)

# Image de base (nouvelle ressource séparée)
resource "libvirt_volume" "base" {
  name = "base.qcow2"
  pool = "default"

  target = {
    format = { type = "qcow2" }
  }

  create = {
    content = {
      url = "/var/lib/libvirt/images/base.img"
    }
  }
}

# Disque VM avec backing store
resource "libvirt_volume" "os_disk" {
  name     = "vm.qcow2"
  pool     = "default"
  capacity = 20 * 1024 * 1024 * 1024

  target = {
    format = { type = "qcow2" }
  }

  backing_store = {
    path   = libvirt_volume.base.path
    format = { type = "qcow2" }
  }
}

Exemple de migration : libvirt_domain

Avant (0.8.x)

resource "libvirt_domain" "vm" {
  name   = "my-vm"
  memory = 2048
  vcpu   = 2

  disk {
    volume_id = libvirt_volume.os_disk.id
  }

  network_interface {
    network_name   = "default"
    wait_for_lease = true
  }

  cloudinit = libvirt_cloudinit_disk.init.id

  console {
    type        = "pty"
    target_port = "0"
    target_type = "serial"
  }

  qemu_agent = true
}

Après (0.9.x)

resource "libvirt_domain" "vm" {
  name   = "my-vm"
  type   = "kvm"
  memory = 2048 * 1024  # KiB !
  vcpu   = 2

  os = { type = "hvm" }
  features = { acpi = true }

  devices = {
    disks = [
      {
        driver = { name = "qemu", type = "qcow2" }
        source = {
          volume = {
            pool   = "default"
            volume = libvirt_volume.os_disk.name
          }
        }
        target = { dev = "vda", bus = "virtio" }
      },
      {
        device = "cdrom"
        driver = { name = "qemu", type = "raw" }
        source = {
          volume = {
            pool   = "default"
            volume = libvirt_volume.cloudinit.name
          }
        }
        target = { dev = "sda", bus = "sata" }
      }
    ]

    interfaces = [
      {
        type  = "network"
        model = { type = "virtio" }
        source = {
          network = { network = "default" }
        }
      }
    ]

    serials = [
      {
        type = "pty"
        target = { port = 0, type = "isa-serial" }
      }
    ]

    graphics = [{ spice = { autoport = "yes" } }]
  }

  running = true
}

Migration de l'état Terraform

Lors d'une migration 0.8 → 0.9, vous devrez probablement :

1. Détruire les ressources existantes : terraform destroy
2. Mettre à jour les fichiers .tf
3. Supprimer le state : rm terraform.tfstate*
4. Recréer : terraform init && terraform apply

La structure des ressources est trop différente pour une migration in-place.

Partie 6 : Créer plusieurs VMs

Avec count

Pour créer 3 VMs identiques, modifiez variables.tf :

variable "vm_count" {
  description = "Nombre de VMs à créer"
  type        = number
  default     = 3
}

Et adaptez main.tf (syntaxe 0.9.x) :

# Volume de base (partagé par toutes les VMs)
resource "libvirt_volume" "base" {
  name = "ubuntu-24.04-base.qcow2"
  pool = var.pool_name

  target = {
    format = { type = "qcow2" }
  }

  create = {
    content = {
      url = var.base_image_path
    }
  }
}

# Volumes OS pour chaque VM (overlay CoW)
resource "libvirt_volume" "os_disk" {
  count    = var.vm_count
  name     = "${var.vm_name}-${count.index + 1}.qcow2"
  pool     = var.pool_name
  capacity = var.disk_size_gb * 1024 * 1024 * 1024

  target = {
    format = { type = "qcow2" }
  }

  backing_store = {
    path   = libvirt_volume.base.path
    format = { type = "qcow2" }
  }
}

# Cloud-init pour chaque VM
resource "libvirt_cloudinit_disk" "init" {
  count = var.vm_count
  name  = "${var.vm_name}-${count.index + 1}-cloudinit"

  user_data = templatefile("${path.module}/cloudinit/user-data.yaml", {
    hostname   = "${var.vm_name}-${count.index + 1}"
    public_key = file(pathexpand(var.ssh_public_key_path))
  })

  meta_data = yamlencode({
    instance-id    = "${var.vm_name}-${count.index + 1}"
    local-hostname = "${var.vm_name}-${count.index + 1}"
  })

  network_config = file("${path.module}/cloudinit/network-config.yaml")
}

# Volumes cloud-init
resource "libvirt_volume" "cloudinit" {
  count = var.vm_count
  name  = "${var.vm_name}-${count.index + 1}-cloudinit.iso"
  pool  = var.pool_name

  create = {
    content = {
      url = libvirt_cloudinit_disk.init[count.index].path
    }
  }
}

# Domaines (VMs)
resource "libvirt_domain" "vm" {
  count  = var.vm_count
  name   = "${var.vm_name}-${count.index + 1}"
  type   = "kvm"
  memory = var.memory_mb * 1024
  vcpu   = var.vcpu

  os = { type = "hvm" }
  features = { acpi = true }

  devices = {
    disks = [
      {
        driver = { name = "qemu", type = "qcow2" }
        source = {
          volume = {
            pool   = var.pool_name
            volume = libvirt_volume.os_disk[count.index].name
          }
        }
        target = { dev = "vda", bus = "virtio" }
      },
      {
        device = "cdrom"
        driver = { name = "qemu", type = "raw" }
        source = {
          volume = {
            pool   = var.pool_name
            volume = libvirt_volume.cloudinit[count.index].name
          }
        }
        target = { dev = "sda", bus = "sata" }
      }
    ]
    interfaces = [
      {
        type  = "network"
        model = { type = "virtio" }
        source = { network = { network = var.network_name } }
      }
    ]
    serials = [{ type = "pty", target = { port = 0, type = "isa-serial" } }]
    graphics = [{ spice = { autoport = "yes" } }]
  }

  running = true
}

Adaptez outputs.tf :

# Data source pour chaque VM
data "libvirt_domain_interface_addresses" "vm" {
  count  = var.vm_count
  domain = libvirt_domain.vm[count.index].name
  source = "lease"

  depends_on = [libvirt_domain.vm]
}

output "vms" {
  description = "Informations sur les VMs créées"
  value = {
    for i, vm in libvirt_domain.vm : vm.name => {
      id  = vm.id
      ip  = try(data.libvirt_domain_interface_addresses.vm[i].interfaces[0].addrs[0].addr, "Non disponible")
    }
  }
}

Avec for_each (VMs différentes)

Pour des VMs avec des specs différentes :

variable "vms" {
  description = "Map des VMs à créer"
  type = map(object({
    memory = number
    vcpu   = number
    disk   = number
  }))
  default = {
    "master" = { memory = 4096, vcpu = 2, disk = 40 }
    "worker1" = { memory = 2048, vcpu = 2, disk = 20 }
    "worker2" = { memory = 2048, vcpu = 2, disk = 20 }
  }
}

Partie 7 : Lifecycle et bonnes pratiques

Éviter les chaînes QCOW2 incontrôlées

Quand vous faites terraform apply plusieurs fois avec des modifications de disque, vous pouvez créer des chaînes de snapshots involontaires.

Règle : si vous voulez une VM "propre", faites un terraform destroy puis terraform apply, pas des apply successifs.

Re-exécuter Cloud-Init

Cloud-Init ne s'exécute qu'une fois par instance. Pour le rejouer :

# Option 1 : Supprimer l'état Cloud-Init (VM existante)
sudo cloud-init clean
sudo rm /etc/machine-id
sudo reboot

# Option 2 : Recréer la VM (recommandé avec Terraform)
terraform destroy
terraform apply

Sauvegarder le state

Le fichier terraform.tfstate contient l'état de votre infrastructure. Sauvegardez-le :

# Sauvegarder localement
cp terraform.tfstate terraform.tfstate.backup

# Ou utilisez un backend distant (S3, GitLab, etc.)

Snapshot ≠ Backup Terraform

Un snapshot libvirt ne sauvegarde pas votre configuration Terraform. Pour une vraie sauvegarde :

• Versionnez vos fichiers .tf dans Git
• Sauvegardez le terraform.tfstate séparément
• Voir notre guide snapshots et backups

Partie 8 : Variantes

Utiliser un bridge au lieu de NAT

Si vous avez configuré un bridge (voir guide réseaux), modifiez la section interfaces dans le bloc devices :

# Syntaxe 0.9.x pour bridge
interfaces = [
  {
    type  = "bridge"
    model = { type = "virtio" }
    source = {
      bridge = { bridge = "br0" }
    }
  }
]

Ajouter un disque de données

# Volume de données (syntaxe 0.9.x)
resource "libvirt_volume" "data_disk" {
  name     = "${var.vm_name}-data.qcow2"
  pool     = var.pool_name
  capacity = 50 * 1024 * 1024 * 1024  # 50 Go

  target = {
    format = { type = "qcow2" }
  }
}

# Dans libvirt_domain, ajouter le disque dans devices.disks :
devices = {
  disks = [
    # ... disque OS existant ...
    {
      driver = { name = "qemu", type = "qcow2" }
      source = {
        volume = {
          pool   = var.pool_name
          volume = libvirt_volume.data_disk.name
        }
      }
      target = {
        dev = "vdb"   # Second disque
        bus = "virtio"
      }
    }
  ]
  # ... reste de la config ...
}

Utiliser OpenTofu

OpenTofu est un fork open source de Terraform, compatible avec les configurations existantes.

# Remplacer terraform par tofu
tofu init
tofu plan
tofu apply

Compatibilité OpenTofu

Le provider dmacvicar/libvirt 0.9.x fonctionne parfaitement avec OpenTofu 1.6+. C'est la combinaison testée et validée dans ce guide.

Nettoyage

Pour supprimer toutes les ressources créées :

terraform destroy

Vérifiez que tout est supprimé :

virsh list --all
virsh vol-list default

À retenir

1. Provider 0.9.x : structure complètement différente de 0.8.x, consultez la section Migration
2. Driver qcow2 explicite : sans driver = { name = "qemu", type = "qcow2" }, la VM ne boot pas
3. Memory en KiB : memory = 2048 * 1024 pour 2 Go (pas MiB)
4. meta_data obligatoire : libvirt_cloudinit_disk requiert meta_data = yamlencode({...})
5. Cloud-Init réseau : utilisez match: { driver: virtio* } au lieu de eth0
6. Récupération IP : data source libvirt_domain_interface_addresses avec source = "lease"
7. Sécurité : ne désactivez jamais security_driver, corrigez les permissions
8. CPU host-passthrough : obligatoire pour AlmaLinux/RHEL 10 et Fedora récents, sinon stuck dans /init au boot
9. Secure Boot UEFI : auto-enrôlé sur libvirt 10+ → désactiver via firmware_info.features pour les images cloud Linux non signées MS
10. Debug : virsh console + cloud-init status --long + virsh net-dhcp-leases default

Prochaines étapes

Snapshots et backups Protéger vos VMs et comprendre la différence snapshot vs backup

Réseaux libvirt NAT, bridge, et réseaux isolés pour vos labs

Terraform avancé Modules, workspaces et bonnes pratiques IaC

Accès distant libvirt Gérer vos VMs KVM depuis un autre poste via SSH

×

📖 Voir la documentation →