Vagrant — comprendre, installer, écrire son premier Vagrantfile

1. C’est quoi, Vagrant ?

Vagrant décrit une machine virtuelle dans un fichier texte — le Vagrantfile — au lieu de la cliquer dans VirtualBox. Vous écrivez « une Ubuntu 22.04, 4 Go de RAM, un réseau privé, installe Docker », et vagrant up fabrique cette VM à l’identique, à chaque fois, sur n’importe quel poste. C’est de l’infrastructure as code : la VM devient reproductible, partageable, versionnable dans Git.

	Sans Vagrant	Avec Vagrant
Créer une VM	Cliquer dans l’interface, configurer à la main	Une commande : vagrant up
Reproductibilité	« Ça marche sur ma machine »	Le même environnement pour toute la promo
Documentation	Une procédure à suivre	Le Vagrantfile EST la documentation
Versioning	Impossible	Le Vagrantfile vit dans Git

Trois concepts suffisent pour tout comprendre :

Concept	C’est…	Dans le module
La box	Une image système de base, téléchargée une fois puis réutilisée (bento/ubuntu-22.04 = Ubuntu 22.04 prête à l’emploi)	bento/ubuntu-22.04
Le provider	L’hyperviseur que Vagrant pilote pour créer la VM — il ne crée rien lui-même	VirtualBox (x86) · QEMU (Apple Silicon)
Le Vagrantfile	Le fichier texte qui décrit la ou les VMs : box, nom, réseau, RAM, scripts d’installation	server/manual/Vagrantfile

flowchart LR
  VF["📄 Vagrantfile<br/>(ce que vous écrivez)"] -->|"vagrant up"| V["Vagrant"]
  BOX["📦 Box<br/>bento/ubuntu-22.04<br/>(téléchargée une fois)"] --> V
  V -->|"pilote"| P["VirtualBox<br/>(provider)"]
  P --> VM["🖥️ VM<br/>créée, démarrée,<br/>provisionnée"]
  V -->|"vagrant ssh"| VM

Vagrant est écrit en Ruby et le Vagrantfile aussi — vous n’avez pas besoin de connaître Ruby : 95 % d’un Vagrantfile, ce sont des lignes config.vm.xxx = valeur.

---

2. Installer

Windows (la majorité des postes) — installer côté Windows, piloter depuis WSL

1. Installez VirtualBox 7 puis Vagrant (installeur .msi) — côté Windows. Redémarrez si demandé.

2. Dans votre terminal WSL (Ubuntu), ajoutez à ~/.bashrc (ou ~/.zshrc) :

   alias vagrant='vagrant.exe'
   alias VBoxManage='VBoxManage.exe'
   export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"

   puis source ~/.bashrc. Si vagrant.exe n’est pas trouvé, utilisez le chemin complet : alias vagrant='"/mnt/c/Program Files/Vagrant/bin/vagrant.exe"'.

3. Travaillez toujours sous /mnt/c/… (le disque Windows) : vagrant.exe tourne côté Windows et ne voit pas le système de fichiers Linux de WSL.

Un seul Vagrant

N’installez jamais Vagrant aussi dans WSL (apt install vagrant). Deux Vagrant = deux états des VMs = plus rien ne se comprend. Le Vagrant de Windows, piloté par l’alias, suffit.

macOS Intel · Linux

OS	Vagrant	Provider
macOS Intel	brew install vagrant	brew install --cask virtualbox
Linux (Debian/Ubuntu)	sudo apt install vagrant	sudo apt install virtualbox

macOS Apple Silicon

VirtualBox ne convient pas : QEMU + plugin vagrant-qemu, avec une limite importante (pas de réseau entre VMs). Tout est dans la page Acte 0 · Setup.

Vérifier

vagrant --version      # Vagrant 2.4.x
VBoxManage --version   # 7.x

---

3. Votre premier Vagrantfile — en dix minutes

Faites-le une fois, sur un dossier jetable, avant de toucher aux VMs du module : vous saurez ensuite exactement ce que vagrant up fait pour vous.

mkdir -p /mnt/c/taaf/essai && cd /mnt/c/taaf/essai   # sous Windows/WSL ; ailleurs : ~/essai
vagrant init bento/ubuntu-22.04

vagrant init a créé un Vagrantfile de ~70 lignes — presque toutes sont des commentaires. Ouvrez-le et remplacez tout par ceci :

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-22.04"
end

Trois lignes : « je veux une VM basée sur la box Ubuntu 22.04 ». Le "2" est la version du format de configuration (toujours 2). Puis :

vagrant up        # 1ʳᵉ fois : télécharge la box (~700 Mo), crée la VM, la démarre
vagrant ssh       # vous êtes DANS la VM (utilisateur vagrant, sudo sans mot de passe)
hostname -I       # son adresse
exit              # retour sur votre poste
vagrant halt      # éteindre (la VM existe toujours)
vagrant destroy -f  # supprimer la VM (la box téléchargée, elle, reste)

Ce qui vient de se passer : Vagrant a téléchargé la box dans ~/.vagrant.d/boxes/ (une seule fois — les vagrant up suivants prennent 30 secondes), a demandé à VirtualBox de créer une VM depuis cette image, a configuré un accès SSH par clé, et a noté l’état de la VM dans un dossier .vagrant/ à côté du Vagrantfile. Ouvrez VirtualBox : votre VM y est, comme si vous l’aviez cliquée.

.vagrant/ ne se versionne pas

Ce dossier contient l’état local de VOS VMs (identifiants VirtualBox, clé SSH). Il va dans .gitignore, jamais dans Git. Le Vagrantfile, lui, oui.

---

4. Le cycle de vie — les commandes que vous taperez tous les jours

Commande	Effet	Quand
vagrant up [vm]	Crée (si besoin) et démarre ; joue le provisioning au premier up	Début de séance
vagrant ssh [vm]	Entre dans la VM	Tout le temps
vagrant status	Qui tourne, qui est éteint	Avant de douter du réseau
vagrant halt [vm]	Éteint proprement (état conservé)	Fin de séance
vagrant reload [vm]	Redémarre (relit le Vagrantfile — réseau, RAM)	Après modification du Vagrantfile
vagrant provision [vm]	Rejoue les scripts de provisioning sans redémarrer	Après modification d’un script
vagrant destroy -f [vm]	Supprime la VM — disque compris	Repartir de zéro
vagrant box list	Les boxes téléchargées	Vérifier un téléchargement
vagrant global-status --prune	Toutes les VMs Vagrant du poste, tous dossiers confondus	Retrouver une VM oubliée

Avec plusieurs VMs dans un Vagrantfile, nommez toujours la cible : vagrant up monitoring, vagrant ssh soc. Un vagrant up nu démarre tout — rarement ce que vous voulez.

---

5. Anatomie d’un Vagrantfile

Tout se configure dans le bloc Vagrant.configure("2") do |config| … end. Les sections que vous utiliserez :

Section	Ce qu’elle fait
config.vm.box	L’image de base
config.vm.hostname	Le nom de la machine (celui que hostname affiche dans la VM)
config.vm.network	Le réseau : privé, ports redirigés, pont
config.vm.provider	Les ressources : RAM, CPU — spécifiques à l’hyperviseur
config.vm.provision	Les scripts joués après le premier démarrage
config.vm.synced_folder	Un dossier de votre poste visible dans la VM

Une VM complète, commentée ligne à ligne :

Vagrant.configure("2") do |config|
  config.vm.box      = "bento/ubuntu-22.04"
  config.vm.hostname = "taaf-monitoring-001"     # nom de la machine dans la VM

  # Réseau privé : la VM obtient une adresse sur un réseau partagé avec
  # votre poste et les autres VMs du même type. C'est par cette adresse
  # que vous joindrez Grafana depuis votre navigateur.
  config.vm.network "private_network", type: "dhcp"

  # Ressources — dans le bloc du provider, car chaque hyperviseur a sa syntaxe
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 4096
    vb.cpus   = 2
  end

  # Provisioning : joué UNE fois, au premier `vagrant up`
  # (ou à la demande : `vagrant provision`)
  config.vm.provision "shell", inline: <<~SH
    apt-get update -qq
    apt-get install -y -qq git curl
  SH
end

Le réseau — les trois cas

Déclaration	Ce que ça donne	Quand
(rien)	NAT : la VM sort vers Internet, personne ne la joint — sauf vagrant ssh	Toujours présent, c’est la carte n°1
"private_network", type: "dhcp" (ou ip: "192.168.56.10")	Un réseau entre votre poste et vos VMs : elles se voient entre elles	Dès que deux VMs doivent se parler — les Actes du module
"forwarded_port", guest: 3000, host: 3000	localhost:3000 sur votre poste → port 3000 de la VM	Accès navigateur sans réseau privé
"public_network"	Pont sur votre carte réseau : la VM est sur le LAN de la salle	Interconnexion entre postes (TP3 ingénieurs)

localhost n’est jamais « l’autre VM »

Depuis la VM soc, localhost c’est… la VM soc. Pour joindre monitoring, il faut son adresse sur le réseau privé (hostname -I dans monitoring). L’erreur la plus fréquente de l’Acte 2.

Le provisioning — les trois règles

1. Il se joue au premier up, pas aux suivants. Pour le rejouer : vagrant provision.
2. Il doit être idempotent : lancé deux fois, il ne casse rien et ne change rien la seconde fois (id taaf || useradd taaf, jamais useradd taaf seul). C’est un critère de notation dans les TP ingénieurs.
3. Un script peut être déclaré mais pas joué : run: "never" + vagrant provision --provision-with <nom>. Le module s’en sert pour les gestes qui doivent rester explicites (basculer une route vers le pare-feu, par exemple).

config.vm.provision "zone-route", type: "shell", run: "never",
                    path: "provision/zone-route.sh", args: ["10.3.40.1"]

---

6. Plusieurs VMs dans un seul Vagrantfile

C’est ce que fait le module : vagrant up monitoring, vagrant up soc, vagrant up audit — trois machines décrites dans un fichier, avec config.vm.define :

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-22.04"           # commun à toutes

  config.vm.define "monitoring", autostart: false do |node|
    node.vm.hostname = "taaf-monitoring-001"
    node.vm.network "private_network", type: "dhcp"
    node.vm.provider("virtualbox") { |vb| vb.memory = 6144 }
  end

  config.vm.define "soc", autostart: false do |node|
    node.vm.hostname = "taaf-soc-001"
    node.vm.network "private_network", type: "dhcp"
    node.vm.provider("virtualbox") { |vb| vb.memory = 3072 }
  end
end

autostart: false = rien ne démarre tout seul ; on allume ce dont l’acte a besoin. Quand les machines se ressemblent, on décrit les différences dans une table et on boucle — c’est exactement la forme de server/manual/Vagrantfile, et celle que les ingénieurs écrivent au TP1 :

VMS = {
  "monitoring" => { hostname: "taaf-monitoring-001", mem: 6144, cpus: 2 },
  "soc"        => { hostname: "taaf-soc-001",        mem: 3072, cpus: 2 },
  "audit"      => { hostname: "taaf-audit-001",      mem: 2048, cpus: 2 },
}

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-22.04"
  VMS.each do |name, m|
    config.vm.define name, autostart: false do |node|
      node.vm.hostname = m[:hostname]
      node.vm.network "private_network", type: "dhcp"
      node.vm.provider "virtualbox" do |vb|
        vb.memory = m[:mem]
        vb.cpus   = m[:cpus]
      end
    end
  end
end

Lisez cette boucle en français : « pour chaque ligne de la table, définis une VM de ce nom, avec ce hostname, cette RAM ». Ajouter une VM = ajouter une ligne. C’est tout le Ruby dont vous aurez besoin.

Lisez le vrai

Ouvrez server/manual/Vagrantfile : vous y retrouverez cette structure, plus le bootstrap (création de l’utilisateur taaf-engineer, installation de Docker) et la détection de l’architecture. Tout y est commenté. Un Vagrantfile qu’on sait lire est un Vagrantfile qu’on saura écrire.

---

7. Les pièges classiques

Symptôme	Cause	Remède
box 'bento/ubuntu-22.04' could not be found	Box pas téléchargée, ou pas de réseau	vagrant box add bento/ubuntu-22.04 (ou depuis un fichier .box fourni sur clé)
VT-x is not available / VM qui ne boote pas	Virtualisation désactivée au BIOS	Activer VT-x / AMD-V — voir le dépannage de l’Acte 0
Tout est lent, timeouts partout	Trop de VMs allumées → le poste swappe	vagrant status, vagrant halt ce qui ne sert pas — avant de chercher un bug réseau
port collision	Le port redirigé est déjà pris sur le poste	Vagrant le corrige seul ; sinon fermez l’application qui l’occupe
Un service « ne répond pas » depuis une autre VM	localhost utilisé au lieu de l’IP de la VM cible	hostname -I dans la VM cible, utiliser cette adresse
Script de provisioning qui échoue avec \r ou ^M	Fins de ligne Windows (CRLF) dans un script édité côté Windows	git config --global core.autocrlf input dans WSL, et sed -i 's/\r$//' script.sh
vagrant.exe introuvable dans WSL	Alias absent ou chemin différent	§2 — alias avec le chemin complet
Une VM « fantôme » dans VirtualBox	Dossier .vagrant/ supprimé à la main	vagrant global-status --prune, puis supprimer la VM dans VirtualBox

---

8. Pour aller plus loin

• Stéphane Robert — Vagrant : la référence francophone, claire et à jour — cette page en reprend la progression. Tout son cours « Infrastructure as Code » vaut le détour.
• Xavki — playlist Vagrant : tutoriels vidéo en français, du premier vagrant up au multi-machines.
• Documentation officielle — developer.hashicorp.com/vagrant : la référence du Vagrantfile.
• Boxes — bento : les images utilisées par le module.

Dans le module : la page Acte 0 · Setup (installation pas à pas, dépannage), et pour les ingénieurs le TP1, où le Vagrantfile devient un livrable.

---

Annexe — VMware Workstation (poste de développement)

Pour un poste de développement sous Windows avec VMware Workstation (plutôt que VirtualBox) — c’est la configuration utilisée pour Dokploy et DNS & SSL local :

Outil	Installation
VMware Workstation 17+	vmware.com
Plugin Vagrant	vagrant plugin install vagrant-vmware-desktop
VMware Utility	vagrant-vmware-utility (service Windows)

Le bloc provider change, le reste du Vagrantfile est identique :

config.vm.provider "vmware_desktop" do |v|
  v.gui = false
  v.allowlist_verified = true
  v.vmx["memsize"]     = "4096"
  v.vmx["numvcpus"]    = "2"
  v.vmx["displayName"] = "TAAF-Dev-Local"
end
config.vm.network "private_network", ip: "192.168.56.10"

Dépannage : si la VM ne démarre pas, réinstaller le plugin (vagrant plugin uninstall vagrant-vmware-desktop puis install) et vérifier que le service VMware Utility tourne dans services.msc. Permissions WSL : [automount] options = "metadata" dans /etc/wsl.conf.