wiki/HowtoVagrant.md

title	categories
Howto Vagrant	virtualisation dev

• 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

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

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

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.

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.

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