Howto Vagrant

• Documentation : https://www.vagrantup.com/docs/

Vagrant 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

Quickstart

Prérequis : libvirt, DHCP

Créer un fichier Vagrantfile dans un répertoire dédié :

Vagrant.configure("2") do |config|
  config.vm.provider :libvirt do |libvirt|
    libvirt.memory = 1024
    libvirt.cpus = 2
    libvirt.keymap = "fr"
  end

  config.vm.box = "debian/bookworm64"

  config.vm.define :test_vagrant do |node|
    node.vm.hostname = "test-vagrant"
  end

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

Lancer la box :

$ vagrant up test_vagrant

Se connecter à la box :

$ vagrant ssh test_vagrant
vagrant@test-vagrant:~$ 

Stopper la box :

$ vagrant halt test_vagrant

Fonctionnement

Boxes

Vagrant utilise des 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.

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.

Syntaxe de Vagrant

On configure un environnement Vagrant, constitué d’une ou plusieurs boxes, avec un fichier Vagrantfile.

On peut avoir autant d’environnements qu’on souhaite, tant qu’ils sont dans des répertoires distincts.

Le Vagrantfile peut notamment être partagé dans le dépôt d’un projet et permet d’avoir un environnement de test reproductible pour tous les usagers du dépôt.

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

Vérifier la validité d’un Vagrantfile

Se positionner dans le répertoire où se trouve le Vagrantfile :

$ vagrant validate

Exemple de Vagrantfile avec VirtualBox et provisionnement Ansible

# -*- 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 permet d’utiliser les services supportés par l’API libvirt, notamment KVM.

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

# -*- 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.

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

# -*- 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

Utilisation du CLI

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 toutes les box :

$ vagrant box update

Note : pour la commandes suivantes, l’option --provider n’est nécessaire que s’il y a des boxes du même nom sur plusieurs providers.

Mettre-à-jour une box en particulier :

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

Supprimer une box :

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

Pour supprimer les boxes qui ne sont plus à jour, il faut d’abord faire un vagrant destroy [<VM_ID|NAME>] (voir plus bas la gestion des VMs) sur les VMs qui les utilisent.

Puis (ajouter -n pour un dry-run) :

$ vagrant box prune [--provider=libvirt]

Si on lance la commande sans supprimer les VMs au préalable, elle demandera une confirmation pour les boxes qui sont encore utilisées.

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 [<VM_ID|NAME>]

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 [<VM_ID|NAME>]

Éteindre la VM :

$ vagrant halt [<VM_ID|NAME>]

Sortir de veille ou mettre en veille la VM :

$ vagrant resume|suspend [<VM_ID|NAME>]

Supprimer la VM (extinction + suppression des ressources) :

$ vagrant destroy [<VM_ID|NAME>]

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

Pré-requis : le paquet libguestfs-tools doit être installé.

La commande vagrant package permet de créer une “box” d’une VM (allumée ou éteinte).

Depuis le dossier contenant le Vagrantfile :

$ vagrant package jessie --output test-jessie-1.box

Le fichier box est une archive tar contenant un fichier .img et des métadonnées.

Remarque : Vagrant enlève les clefs SSH de l’hôte

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] [<VM_ID|NAME>]

Provisionnement des environnements / VMs

Documentation à venir

vagrant provision

FAQ

Désactiver le partage NFS

Pour éviter que Vagrant ne crée par défaut un partage NFS, le Vagrantfile doit contenir :

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

Sinon, au lancement, 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.

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.

Répertoire avec Plusieurs Vagrantfiles

On peut utiliser la variable d’environnement VAGRANT_VAGRANTFILE pour spécifier le nom (et non le chemin) du Vagrantfile à utiliser.