Les prérequis du README sont incomplets sur cinq points : un débutant ne peut pas provisionner en les suivant

[stephrobert]

Contexte

Audit du parcours d'installation joué sur une VM Ubuntu 24.04.4 LTS réellement neuve, avec dsoxlab 0.1.40 installé depuis PyPI et ce catalogue cloné depuis GitHub. Consigne stricte : ne jamais installer un paquet que la documentation ou l'outil n'a pas nommé, et noter chaque écart.

Résultat : six interventions non documentées sont nécessaires entre le dsoxlab doctor vert de l'étape 4 et le premier lab VM jouable. Un débutant s'arrête à l'étape 7.

#	Étape	Source	Résultat
1	Installer uv	README.fr.md:36	OK
2	uv tool install dsoxlab	README.fr.md:49	OK, 0.1.40, 18 Mo
3	git clone	README.fr.md:52	OK, 84 labs
4	dsoxlab doctor	README.fr.md:56	Vert, mais trompeur
5	dsoxlab use l1 + cycle shell	README.fr.md:62-79	OK
6	dsoxlab use --provider kvm	README.fr.md:93	OK
7	dsoxlab provision	README.fr.md:94	Échec : clé SSH absente
8	dsoxlab instructor bootstrap	nulle part dans la doc	Clé créée
9	Installer Terraform	nulle part dans la doc	OK
10	Installer libvirt/KVM	remédiation de doctor	OK
11	dsoxlab provision		Échec : Pool Not Found
12	Créer le pool default à la main	nulle part dans la doc	OK
13	dsoxlab provision		Échec : Permission denied (AppArmor)
14	Override AppArmor à la main	nulle part dans la doc	OK
15	dsoxlab provision		Échec : domain already exists
16	virsh undefine les orphelins	nulle part dans la doc	OK
17	dsoxlab provision		Succès, 122 s, 3 hôtes prêts
18	dsoxlab run <lab vm>	README.fr.md:74	Échec : rc=127
19	uv tool install ansible-core	nulle part dans la doc	OK
20	dsoxlab run + dsoxlab check		Succès

La voie Incus demande une septième intervention non documentée (genisoimage), après quoi elle fonctionne de bout en bout.

Une partie de ces frictions relève du moteur et est traitée là-bas : dsoxlab#107 (domaines orphelins), #105 (ansible-core), #102 (Terraform), #99 (instructor bootstrap), #98 (classement de doctor), #94 (pool libvirt), #93 (AppArmor), #106 (genisoimage). Mais la documentation de ce dépôt peut débloquer l'apprenant tout de suite, sans attendre aucune de ces corrections.

Les cinq manques

Le bloc de prérequis actuel (README.fr.md:34-40 et README.md:34-40) nomme Python, uv, git et un provider. Il manque :

1. Terraform, qui provisionne les machines. Cité nulle part comme prérequis.
2. ansible-core, qui joue le setup.yaml de chaque lab. dsoxlab ne l'embarque pas, contrairement à ce que son pyproject.toml affirme.
3. Les prérequis matériels, absents alors qu'ils décident du succès.
4. La préparation du provider : pool libvirt default et override AppArmor sur Ubuntu et Debian, genisoimage sur Incus.
5. dsoxlab instructor bootstrap, obligatoire et cité nulle part : le dépôt ne contient pas de répertoire ssh/ (ignoré par .gitignore:221), et sans clé, provision s'arrête.

Prérequis matériels mesurés

Relevés sur la machine d'audit, provider KVM, les trois hôtes du meta.yml en fonctionnement.

Ressource	Mesure
RAM allouée aux 3 VM	5120 Mio (2048 + 1536 + 1536)
RAM réellement utilisée, hôte compris	3893 Mo sur 11959
Disque, pool libvirt	3,2 Go (2 images de base + 3 overlays)
Disque total / (OS + outils + labs)	5,9 Go
Durée d'un provision KVM réussi	122 s
Durée d'un provision Incus réussi	119 s

Recommandation étayée :

• CPU : 4 vCPU est un plancher, 8 vCPU confortable. C'est le facteur qui décide du respect du délai de 180 s au démarrage parallèle, et la seule cause reproduite du symptôme de Retour d'expérience : migration KVM → Incus, fix cloud-init AlmaLinux inclus #36.
• RAM : 8 Go strict minimum (5,1 Go pour les VM, plus l'hôte), 12 Go confortable. 4 Go ne peuvent pas fonctionner, les VM seules n'y tiennent pas.
• Disque : 20 Go suffisent, 40 Go confortables.
• Virtualisation imbriquée obligatoire si la machine de l'apprenant est elle-même une VM. C'est le seul prérequis matériel irréductible : sans vmx ou svm exposé, aucun provider local ne fonctionne.

Correctif proposé

--- a/README.fr.md
+++ b/README.fr.md
@@
 ## Prérequis

 - Python 3.11+ et [`uv`](https://docs.astral.sh/uv/)
 - `git`
-- Pour les labs L2+ (VM : systemd, pare-feu, SELinux, stockage), un provider
-  parmi **KVM/libvirt**, **Incus** ou un cloud supporté (Outscale). Les labs
-  shell (L1) ne demandent qu'un terminal.
+- Les labs shell (L1) ne demandent qu'un terminal : rien d'autre à installer.
+- Pour les labs L2+ (VM : systemd, pare-feu, SELinux, stockage) :
+  - **[Terraform](https://developer.hashicorp.com/terraform/install)**, qui
+    provisionne les machines ;
+  - **`ansible-core`** (`uv tool install ansible-core`), qui joue le `setup.yaml`
+    de chaque lab. `dsoxlab` ne l'embarque pas ;
+  - un provider parmi **KVM/libvirt**, **Incus** ou un cloud supporté (Outscale) ;
+  - **4 vCPU, 8 Go de RAM et 20 Go de disque** au minimum : les trois machines du
+    lab en réservent 5 Go à elles seules, et c'est le nombre de vCPU qui décide
+    du respect du délai d'attente au démarrage ;
+  - si ton poste est lui-même une VM, la **virtualisation imbriquée** doit être
+    active (`cat /sys/module/kvm_intel/parameters/nested` doit répondre `Y`).
+
+### Préparer le provider KVM
+
+```bash
+sudo apt install libvirt-clients libvirt-daemon-system qemu-kvm
+sudo usermod -aG libvirt "$USER"      # puis se reconnecter
+
+# Le pool de stockage `default` n'existe pas sur une installation fraîche,
+# alors que dsoxlab y écrit ses volumes.
+sudo virsh pool-define-as default dir --target /var/lib/libvirt/images
+sudo virsh pool-build default && sudo virsh pool-start default
+sudo virsh pool-autostart default
+
+# Ubuntu/Debian uniquement. virt-aa-helper ne sait pas résoudre les disques
+# que Terraform déclare par référence de pool : sans cette ligne, AppArmor
+# refuse TOUS les disques et `dsoxlab provision` échoue sur « Permission denied ».
+echo '  /var/lib/libvirt/images/** rwk,' \
+  | sudo tee /etc/apparmor.d/local/abstractions/libvirt-qemu
+sudo systemctl restart libvirtd
+```
+
+### Préparer le provider Incus
+
+```bash
+sudo apt install incus genisoimage   # genisoimage : Incus fabrique le CD-ROM
+                                     # `agent:config` sur l'hôte
+sudo systemctl enable --now incus.service
+sudo incus admin init --auto
+sudo usermod -aG incus,incus-admin "$USER"   # puis se reconnecter
+```

Et l'étape manquante dans la section Installation :

@@
 # 3. Vérifier que tout est en place
 dsoxlab doctor
+
+# 4. Générer la clé SSH des machines de lab (le dépôt ne la contient pas :
+#    elle est ignorée par git, et sans elle `dsoxlab provision` s'arrête).
+dsoxlab instructor bootstrap

Enfin, la procédure de récupération (`README.fr.md:205-225`) documente `dsoxlab destroy --yes` puis `dsoxlab provision` comme **la** voie de sortie. Elle ne récupère rien quand un `provision` a échoué après avoir défini les domaines : ceux-ci ne sont pas dans le state, `destroy` ne les voit pas et sort en succès. Tant que [dsoxlab#107](https://github.com/stephrobert/dsoxlab/issues/107) n'est pas corrigé, il faut le dire :

```diff
 dsoxlab destroy --yes     # environ 6 s
 dsoxlab provision         # environ 4 min, les 3 hôtes reviennent prêts
+
+# Si `provision` répond « domain already exists » : un provisionnement
+# précédent a échoué APRÈS avoir défini les machines, qui ne sont donc pas
+# dans le state Terraform. `destroy` ne peut pas les voir. Les retirer à la main :
+for h in alma-rhcsa-1.lab alma-rhcsa-2.lab ubuntu-lfcs-1.lab; do
+  virsh -c qemu:///system destroy "$h" 2>/dev/null
+  virsh -c qemu:///system undefine --nvram "$h" 2>/dev/null
+done

Critères d'acceptation

• Les prérequis nomment Terraform et ansible-core, avec la commande d'installation.
• Les prérequis matériels sont chiffrés (vCPU, RAM, disque) et la virtualisation imbriquée mentionnée avec sa commande de vérification.
• La préparation du pool libvirt et de l'override AppArmor est documentée, avec la raison de chacune : un apprenant doit comprendre pourquoi, pas seulement copier.
• La préparation d'Incus mentionne genisoimage.
• dsoxlab instructor bootstrap figure dans la section Installation.
• La procédure de récupération couvre le cas des domaines orphelins, avec un renvoi vers l'issue du moteur.
• Parité EN / FR : README.md reçoit les mêmes ajouts que README.fr.md.
• Le parcours est rejoué sur une machine neuve en suivant uniquement le README, sans intervention non documentée, jusqu'à un dsoxlab check vert sur un lab VM.

Le dernier critère est le seul qui prouve quelque chose : c'est exactement ce que cet audit a fait échouer.

Périmètre

Mesuré sur Ubuntu 24.04 uniquement. Sur Fedora ou AlmaLinux, le pool default existe généralement et SELinux remplace AppArmor : ces deux points de préparation y sont probablement inutiles, et le diagnostic reste à établir avant de l'écrire.

---

Issue issue d'un audit du setup à froid joué sur une machine neuve, dont chaque affirmation a été vérifiée par exécution ou confrontée au code publié.