432 lines
11 KiB
Markdown
432 lines
11 KiB
Markdown
---
|
||
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>
|
||
|
||
|
||
## 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](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.
|
||
|
||
|
||
## 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
|
||
|
||
~~~{.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
|
||
~~~
|
||
|
||
|
||
## 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](#gestion-des-environnements-et-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` :
|
||
|
||
~~~{.bash}
|
||
$ 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](https://developer.hashicorp.com/vagrant/docs/synced-folders/rsync).
|