---
title: Howto Vagrant
categories: virtualisation dev
---

* Documentation : <https://www.vagrantup.com/docs/>

[Vagrant](https://www.vagrantup.com) est un logiciel qui permet de configurer et démarrer des environnements virtuels légers, portables et reproductibles.

À travers son fichier de configuration nommé **Vagrantfile**, il permet d'orchestrer l'installation et la configuration de VMs ou de conteneurs variés (Libvirt, LXC, VirtualBox, VMWare, Docker, Amazon EC2...).


## Installation

~~~
apt install vagrant
~~~

Des paquets Debian officiels (maintenus par Hashicorp) sont aussi disponibles pour des versions plus récentes, mais sans dépôt : <https://www.vagrantup.com/downloads.html>


## Configuration d'un environnement avec le `Vagrantfile`

Le `Vagrantfile` est unique à un projet et doit être situé dans le répertoire racine de ce dernier.

Il est écrit en Ruby et décrit le type de machine à démarrer, leurs spécifications et leur configuration initiale (provision).

Pour vérifier la validité de votre `Vagrantfile` :

~~~
$ vagrant validate
~~~

Pour éviter que Vagrant crée par défaut un partage NFS, la configuration doit contenir :

~~~
config.vm.synced_folder "./", "/vagrant", disabled: true
~~~

Sinon, on rencontre l'erreur :

~~~
It appears your machine doesn't support NFS, or there is not an adapter to enable NFS on this machine for Vagrant. Please verify that `nfsd` is installed on your machine, and try again. If you're on Windows, NFS isn't supported. If the problem persists, please contact Vagrant support.
~~~


### Exemple de `Vagrantfile` avec VirtualBox et provisionnement Ansible

~~~{.ruby}
# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure('2') do |config|
  # Image de base de la machine virtuelle
  config.vm.box = "debian/bookworm64"

  # Désactiver le partage et la synchronisation via NFS (activé par défaut)
  config.vm.synced_folder "./", "/vagrant", disabled: true

  # Spécification du provider et caractéristiques des VM.
  config.vm.provider :virtualbox do |v|
    v.memory = 1024
    v.cpus = 2
    v.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
    v.customize ["modifyvm", :id, "--ioapic", "on"]
  end

  # Définition de la machine virtuelle qui sera lancée.
  config.vm.define :default do |default|
    default.vm.hostname = "default"
    default.vm.network :private_network, ip: "192.168.33.33"
    default.vm.provision :ansible do |ansible|
          ansible.limit = "default"
          ansible.playbook = "provisioning/vagrant.yml"
          ansible.raw_arguments = ["-b"]
    end
  end

  # Configuration permettant de distribuer l'image dans le Vagrant Atlas
  config.push.define "atlas" do |push|
    push.app = "evolix/evolinux"
    push.vcs = false
  end

end
~~~


#### Providers

##### Libvirt

Le [provider libvirt](https://github.com/vagrant-libvirt/vagrant-libvirt/blob/master/README.md) permet d'utiliser les services supportés par l'API [libvirt](https://libvirt.org/), notamment [KVM](HowtoKVM).

Voici un exemple d'utilisation d'un serveur KVM distant :

~~~{.ruby}
# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure('2') do |config|
    config.vm.provider :libvirt do |libvirt, override|
        libvirt.host = "kvm-host.example.com"
        libvirt.connect_via_ssh = 'yes'
        libvirt.memory = 1024
        libvirt.cpus = 2
        libvirt.cpu_mode = "host-passthrough"
        libvirt.random :model => 'random'
        override.ssh.proxy_command = "ssh kvm-host.example.com nc -N %h %p"
    end
end
~~~


##### Virtualbox

Le provider originel et par défaut de Vagrant est [Virtualbox](https://www.virtualbox.org/).

Il a l'avantage de pouvoir tourner sur Linux, Windows et Mac OS :

~~~{.ruby}
# -*- mode: ruby -*-
# vi: set ft=ruby :

config.vm.provider :virtualbox do |v|
    v.memory = 1024
    v.cpus = 2
    v.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
    v.customize ["modifyvm", :id, "--ioapic", "on"]
  end
~~~


#### Configurer localement le provider par défaut

Si le `Vagrantfile` de l'environnement est partagé entre plusieurs utilisateurs, ceux-ci peuvent souhaiter utiliser différents providers.

Pour cela, on peut créer un fichier `~/.Vagrantfile` local, configurant le provider par défaut de l'utilisateur. Par exemple, pour utiliser par défaut le provider `libvirt` :

~~~
Vagrant.configure("2") do |config|
  config.vm.provider "libvirt"
end
~~~

Ensuite, il faut mettre dans le `Vagrantfile` de chaque environnement cet en-tête :

~~~
# Load ~/.Vagrantfile if exist, permit local config provider
vagrantfile = File.join("#{Dir.home}", '.Vagrantfile')
load File.expand_path(vagrantfile) if File.exists?(vagrantfile)
~~~

Si `~/.Vagrantfile` n'existe pas et qu'aucun provider n'est défini, le provider par défaut du système sera utilisé.


### Synchroniser un répertoire entre l'hôte et l'invité 

<https://developer.hashicorp.com/vagrant/docs/synced-folders>


#### Avec Rsync

*Documentation à venir*

<https://developer.hashicorp.com/vagrant/docs/synced-folders/rsync>

Synchroniser automatiquement le répertoire :

~~~
vagrant rsync-auto
~~~

Voir la [documentation](https://developer.hashicorp.com/vagrant/docs/synced-folders/rsync).



## Fonctionnement

### Boxes

Vagrant utilise des [boxes](https://developer.hashicorp.com/vagrant/docs/boxes) pour créer des VMs ou des conteneurs.

Ce sont des images de systèmes pré-installés.

On peut trouver des boxes dans le [catalogue public de son éditeur HashCorp](https://vagrantcloud.com/boxes/search).

Les boxes sont nommées par fournisseurs, par exemple :

* `debian/bullseye64`
* `debian/bookworm64`

On peut aussi les récupérer en spécifiant une URL plutôt à la place du nom de la box.


### Providers

Vagrant permet de lancer et configurer des boxes dans VirtualBox, Libvirt, LXC, VMware, Docker, Amazon EC2 et autres.

Ces providers peuvent être locaux ou situés sur des serveurs distants.


#### Libvirt

Les boxes et les images `QCOW2` du provider `libvirt` sont stockées par défaut dans `/var/lib/libvirt/images/`.

Par défaut, le volume de stockage est une image au format `QCOW2`, ce qui éviter d'avoir à réserver de l'espace disque.


## Utilisation

### Gestion des boxes

Ajouter une nouvelle box Debian Bookworm pour `libvirt` aux boxes disponibles localement :

~~~
$ vagrant box add --provider=libvirt debian/bookworm64
~~~

Lister les boxes disponibles localement :

~~~
$ vagrant box list
debian/bookworm64 (libvirt, 12.20230723.1)
debian/bullseye64 (libvirt, 11.20210829.1)
~~~

Lister les boxes locales à mettre à jour :

~~~
$ vagrant box outdated --global
* 'debian/bullseye64' for 'libvirt' is outdated! Current: 11.20210829.1. Latest: 11.20230615.1
* 'debian/bookworm64' for 'libvirt' (v12.20230723.1) is up to date
~~~

Mettre-à-jour une box :

~~~
$ vagrant box update [--provider=libvirt] --box debian/bullseye64
~~~

Supprimer une box :

~~~
$ vagrant box remove [--provider=libvirt] debian/bullseye64
~~~

Note : l'option `--provider` n'est nécessaire que s'il y a des boxes du même nom pour plusieurs providers.


### Gestion des environnements et des VMs

Notes : 

* Pour simplifier, on utilise le terme « VM » mais en fonction du provider ce peut aussi être un conteneur.
* **La plupart de ces commandes doivent être jouées dans le répertoire de l'environnement concerné.**
* Un environnement peut contenir plusieurs VMs. Dans ce cas, il faut préciser le nom ou l'id de l'instance dans la commande.

Lister toutes les VMs Vagrant présentes sur l'hôte (utile pour retrouver les répertoires, les ids...) :

~~~
$ vagrant global-status
~~~

Indiquer le statut de la ou les VMs :

~~~
$ vagrant status
~~~

Créer une instance de VM par défaut avec la box `debian/bookworm64` :

~~~
$ vagrant init debian/bookworm64
~~~

Cette commande crée un fichier `Vagrantfile` (à modifier) qui contient la configuration de la VM.

Alternativement, on peut créer soi-même le `Vagrantfile` pour configurer plusieurs VMs dans le même environnement ou configurer plus finement la VM.

Démarrer ou redémarrer la VM :

~~~
vagrant up|reload
~~~

Éteindre la VM :

~~~
$ vagrant halt
~~~

Sortir de veille ou mettre en veille la VM :

~~~
$ vagrant resume|suspend
~~~

Supprimer la VM (extinction + suppression des ressources) :

~~~
$ vagrant destroy
~~~

Attention : cette commande est différente de `virsh destroy`, qui ne fait qu'éteindre une VM sans supprimer les ressources ! `vagrant destroy` équivaut plutôt à `virsh destroy && virsh undefine`.


### Snapshots des environnements / VMs

*Documentation à venir*


### Interaction avec les environnements / VMs

Lister les ports mappés de l'invité vers l'hôte (fonctionnalité non supportée par le provider `libvirt`) :

~~~
$ vagrant port
    22 (guest) => 2222 (host)
    80 (guest) => 8080 (host)
~~~

Se connecter en SSH à une VM :

~~~
$ vagrant ssh
~~~

On peut aussi demander à Vagrant de produire une configuration SSH à ajouter dans notre `.ssh/config` :

~~~
$ vagrant ssh-config
~~~

Uploader un fichier dans la VM :

~~~
$ vagrant upload source [destination]
~~~


### Provisionnement des environnements / VMs

*Documentation à venir*

~~~
vagrant provision
~~~