Vagrant plugin : héberger vos plugins sur Nexus 3 et installer depuis une source interne

Vagrant plugin : la réponse rapide

Les plugins Vagrant sont des gems Ruby. Pour empêcher Vagrant d’aller chercher ses dépendances directement sur Internet, le plus robuste consiste à créer dans Nexus 3 un group RubyGems qui agrège au minimum gems.hashicorp.com et rubygems.org, puis à forcer Vagrant à utiliser uniquement cette source interne avec --plugin-source et --plugin-clean-sources.

vagrant plugin install vagrant-vbguest \
  --plugin-version 0.32.0 \
  --plugin-clean-sources \
  --plugin-source https://artifacts.example.com/repository/rubygems-vagrant-group/

Deux points cassent souvent ce flux en entreprise : le certificat interne Nexus non reconnu par le Ruby embarqué de Vagrant, et une source Nexus incomplète qui ne proxy que gems.hashicorp.com sans inclure rubygems.org.

Pourquoi centraliser les plugins Vagrant via Nexus 3

Quand tu lances vagrant plugin install vagrant-vbguest, Vagrant résout un gem Ruby principal puis ses dépendances. Selon la version de Vagrant et du plugin, les téléchargements peuvent partir vers https://gems.hashicorp.com/ et vers https://rubygems.org/. Il n’existe donc pas forcément un dépôt unique “officiel Vagrant” à proxifier.

Dans un contexte corporate, laisser chaque machine sortir directement vers Internet pose vite problème : filtrage egress, proxy TLS interne, manque de traçabilité, dépendances non maîtrisées, variabilité des builds et difficulté d’audit. En interposant Nexus 3, tu centralises les accès, tu bénéficies d’un cache local et tu rends le comportement de Vagrant beaucoup plus prévisible.

Architecture Nexus 3 recommandée

La structure la plus robuste dans Nexus 3 est la suivante :

1. gems-hashicorp-proxy : proxy vers https://gems.hashicorp.com/
2. rubygems-org-proxy : proxy vers https://rubygems.org/
3. rubygems-hosted : dépôt hosted optionnel pour des gems internes
4. rubygems-vagrant-group : group qui agrège les trois précédents

Le point critique est d’utiliser le group comme source Vagrant finale :

https://artifacts.example.com/repository/rubygems-vagrant-group/

Ce group couvre à la fois le plugin principal et ses dépendances, même si elles ne viennent pas toutes de la même origine.

Ordre conseillé des membres du group

• rubygems-hosted
• gems-hashicorp-proxy
• rubygems-org-proxy

Tu gardes ainsi la priorité sur d’éventuels gems internes, puis tu laisses Nexus résoudre les besoins externes de manière contrôlée.

Commande Vagrant pour installer un plugin depuis Nexus

La commande recommandée est la suivante :

vagrant plugin install vagrant-vbguest \
  --plugin-version 0.32.0 \
  --plugin-clean-sources \
  --plugin-source https://artifacts.example.com/repository/rubygems-vagrant-group/

Rôle des options :

• --plugin-source : ajoute une source RubyGems spécifique
• --plugin-clean-sources : retire les sources par défaut pour éviter des appels directs à Internet
• --plugin-version : épingle une version précise du plugin

Problème rencontré 1 : erreur SSL avec le certificat interne Nexus

Erreur typique :

SSL verification error at depth 1:
unable to get local issuer certificate

Vagrant failed to load a configured plugin source.

Cette erreur apparaît même quand ton certificat d’autorité interne est déjà installé dans Linux. La raison est que Vagrant peut utiliser son propre Ruby embarqué et son propre bundle CA. Il ne lit donc pas forcément /etc/ssl/certs/ca-certificates.crt.

Pour identifier le fichier CA réellement utilisé :

/opt/vagrant/embedded/bin/ruby -ropenssl -e 'puts OpenSSL::X509::DEFAULT_CERT_FILE'

Dans ce scénario, la solution retenue consiste à sauvegarder le bundle embarqué puis à le remplacer par le bundle système :

VAGRANT_CERT_FILE="$('/opt/vagrant/embedded/bin/ruby' -ropenssl -e 'puts OpenSSL::X509::DEFAULT_CERT_FILE')"

sudo cp -a "$VAGRANT_CERT_FILE" "${VAGRANT_CERT_FILE}.bak.$(date +%Y%m%d%H%M%S)"
sudo cp /etc/ssl/certs/ca-certificates.crt "$VAGRANT_CERT_FILE"
sudo chmod 0644 "$VAGRANT_CERT_FILE"

Important : une mise à jour de Vagrant peut réécrire ce fichier. Il faut donc rejouer cette étape après installation ou upgrade.

Problème rencontré 2 : erreur de dépendance

Erreur observée :

Unable to resolve dependency:
user requested 'vagrant-vbguest (= 0.32.0)'

Ici, le certificat n’est plus le problème. La cause est une source Nexus incomplète. Si tu pointes Vagrant uniquement vers un proxy HashiCorp, il peut manquer le plugin lui-même ou l’une de ses dépendances si elle vit côté RubyGems.org.

Mauvais exemple :

vagrant plugin install vagrant-vbguest \
  --plugin-version 0.32.0 \
  --plugin-clean-sources \
  --plugin-source https://artifacts.example.com/repository/gems-hashicorp-proxy/

Bon exemple :

vagrant plugin install vagrant-vbguest \
  --plugin-version 0.32.0 \
  --plugin-clean-sources \
  --plugin-source https://artifacts.example.com/repository/rubygems-vagrant-group/

La leçon à retenir est simple : pour Vagrant, il faut raisonner en chaîne complète de dépendances Ruby, pas uniquement en plugin principal.

Exemples Ansible : ordre correct et implémentation finale

L’ordre des tâches est important :

1. Installer le certificat d’autorité interne dans le système
2. Lancer update-ca-certificates
3. Installer Vagrant
4. Corriger le bundle CA embarqué de Vagrant
5. Installer les plugins Vagrant depuis Nexus

Exemple pour sauvegarder puis remplacer le bundle CA de Vagrant :

- name: Get Vagrant embedded Ruby default cert file
  ansible.builtin.command: >
    /opt/vagrant/embedded/bin/ruby -ropenssl -e 'puts OpenSSL::X509::DEFAULT_CERT_FILE'
  register: vagrant_cert_file
  changed_when: false

- name: Backup Vagrant CA bundle
  ansible.builtin.copy:
    remote_src: true
    src: "{{ vagrant_cert_file.stdout }}"
    dest: "{{ vagrant_cert_file.stdout }}.bak"
    owner: root
    group: root
    mode: "0644"
    force: false

- name: Replace Vagrant CA bundle with system CA bundle
  ansible.builtin.copy:
    remote_src: true
    src: /etc/ssl/certs/ca-certificates.crt
    dest: "{{ vagrant_cert_file.stdout }}"
    owner: root
    group: root
    mode: "0644"

Variables pour l’installation du plugin :

vagrant_plugin_source: "https://artifacts.example.com/repository/rubygems-vagrant-group/"
vagrant_plugin_version: "0.32.0"
vagrant_plugin_user: "mon_user"

Tâche finale :

- name: Install Vagrant plugin
  ansible.builtin.command: >
    vagrant plugin install vagrant-vbguest
    --plugin-version {{ vagrant_plugin_version }}
    --plugin-clean-sources
    --plugin-source {{ vagrant_plugin_source }}
  become_user: "{{ vagrant_plugin_user }}"

Alternative si tu ne veux pas écraser le bundle CA embarqué :

- name: Install Vagrant plugin
  ansible.builtin.command: >
    vagrant plugin install vagrant-vbguest
    --plugin-version {{ vagrant_plugin_version }}
    --plugin-clean-sources
    --plugin-source {{ vagrant_plugin_source }}
  become_user: "{{ vagrant_plugin_user }}"
  environment:
    SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt

Dans la plupart des environnements d’entreprise, la solution la plus simple à maintenir reste le remplacement du bundle CA Vagrant par le bundle système.

Commandes de test utiles

Avant de relancer Vagrant, valide les briques séparément :

curl -I https://artifacts.example.com/repository/rubygems-vagrant-group/specs.4.8.gz
curl -I https://artifacts.example.com/repository/rubygems-vagrant-group/gems/vagrant-vbguest-0.32.0.gem

Pour obtenir des logs détaillés côté Vagrant :

VAGRANT_LOG=debug vagrant plugin install vagrant-vbguest \
  --plugin-version 0.32.0 \
  --plugin-clean-sources \
  --plugin-source https://artifacts.example.com/repository/rubygems-vagrant-group/

Si l’installation échoue encore, tu peux isoler le diagnostic en vérifiant séparément :

• la résolution DNS de Nexus
• la chaîne TLS présentée par Nexus
• le contenu réel du dépôt group
• le bundle CA utilisé par le Ruby embarqué de Vagrant
• la présence du gem et de ses dépendances dans les proxys du group

Checklist de mise en production

• Créer les dépôts RubyGems proxy nécessaires dans Nexus 3
• Créer un dépôt group unique pour Vagrant
• Pointer Vagrant vers le group et pas vers un proxy isolé
• Utiliser --plugin-clean-sources dans les automatisations
• Épingler les versions de plugins critiques
• Déployer et valider l’autorité interne côté Linux
• Vérifier le bundle CA du Ruby embarqué de Vagrant
• Rejouer la correction CA après chaque mise à jour de Vagrant
• Tester l’accès au group Nexus avec curl avant les installs Vagrant

FAQ

Pourquoi un seul proxy HashiCorp ne suffit pas ?

Parce qu’un plugin Vagrant et ses dépendances peuvent être résolus depuis plusieurs sources RubyGems. Sans proxy RubyGems.org dans le group, certaines dépendances resteront introuvables.

Pourquoi installer le certificat dans Linux ne suffit pas toujours ?

Parce que Vagrant peut embarquer son propre Ruby et utiliser un bundle CA distinct du système. Le binaire Vagrant et le système n’ont donc pas toujours la même chaîne de confiance.

Faut-il utiliser SSL_CERT_FILE ou remplacer le bundle Vagrant ?

Les deux approches peuvent marcher. Si tu veux une solution stable pour tous les usages de Vagrant sur la machine, remplacer le bundle CA embarqué est souvent plus prévisible. Si tu veux une approche plus ciblée, passe SSL_CERT_FILE dans l’environnement d’exécution.

Quel est le point clé à retenir ?

La solution finale consiste à utiliser un dépôt group Nexus RubyGems comme source unique pour Vagrant et à s’assurer que le Ruby embarqué de Vagrant fait confiance au certificat interne Nexus.