🚀

Vagrant-libvirt on WSLでWindows上に高速仮想マシン開発環境を作る!

に公開
Vagrant
WSL
WSL 2
libvirt
tech

Vagrant-libvirt on WSLでできること

WindowsのWSL2内に完結する仮想マシンの開発環境・テスト環境を手に入れることができる

  • WSL(Windows Subsystem for Linux)2内部でVagrantを使用したKVMの仮想マシン作成
  • 複数仮想マシンの作成・破棄・再作成も容易 (Vagrantfileとvagrantコマンド一発)
  • 複数ネットワーク構成も可能 (linux bridgeを使って簡単に構成)

前提技術の整理

本記事で利用する技術を簡単に説明(詳細は脚注のリンクを参照)

必要な知識・スキル

  • Linuxの基本的なコマンド操作
  • WSLの基本的な使用経験
  • Vagrantの基礎的な知識

WSL(Windows Subsystem for Linux)[1]とは

  • Windows上でLinux環境を実行できるWindowsの標準機能、Ubuntu、AlmaLinuxなどのディストリビューションが選択可能
  • WSL2 (WSLのデフォルト、本記事ではWSLはWSL2のことを指す)では、Hyper-Vの仮想化テクノロジを使用してLinuxを実行

Vagrant[2]とは

  • 仮想マシンの作成・管理を簡単に行うためのツール
  • 主にローカルのPC上で開発環境・テスト環境を素早く構築するために使用

Libvirt[3]とは

  • 仮想化(OSの提供する仮想化マシン機能やコンテナなど)管理の共通APIを提供するオープンソースのライブラリ及びツールセット
  • Linux KVMの管理機能としては事実上の標準

Vagrant-libvirt[4]とは

  • VagrantにLibvirtプロバイダーを追加するプラグイン
    • Vagrantは標準でVirtualBox、Hyper-V、Dockerをサポート
    • VagrantからKVMを利用するにはvagrant-libvirtが必要

Nested Virtualization[5]とは

  • Nested Virtualizationは、仮想マシンの中でさらに仮想マシンを入れ子で動かす技術
  • 最近(2010年代以降)のほとんどのIntel/AMD CPUはサポート済み

セットアップ

要件

  • WSL2をサポートするWindows (Windows 10 バージョン 2004以降、Windows 11)
  • Nested VirtualizationをサポートするIntel VT-x/AMD-V 対応CPU
  • メモリ容量: 16GB以上推奨 (通常のWindowsのメモリ消費に加えて、WSL及びVagrantの仮想マシン用メモリが必要)

動作確認済み環境

本記事作成時の環境は下記の通り

  • OS: Windows 11 24H2 Professional
  • WSLバージョン
    > wsl --version
WSL バージョン: 2.5.9.0
カーネル バージョン: 6.6.87.2-1
WSLg バージョン: 1.0.66
MSRDC バージョン: 1.2.6074
Direct3D バージョン: 1.611.1-81528511
DXCore バージョン: 10.0.26100.1-240331-1435.ge-release
Windows バージョン: 10.0.26100.4652

セットアップ手順

  • Ansible Playbook化しGitHubで公開(AlmaLinux-9及びUbuntu-24.04をサポート)

https://github.com/r0ckpine/vagrant-libvirt-wsl

  • 以降、LinuxディストリビューションとしてAlmaLinux-9を利用したコマンドラインでのセットアップ手順を示す

WSLのインストールと初期設定

WSLのインストール

  • 公式手順を参照
  • PowerShellを管理者モードで開き下記コマンドを実行、コンピューターの再起動が必要
wsl --install

Linuxディストリビューションのインストール

PowerShellから実行

  • WSLのLinuxディストリビューションを一覧表示

    wsl.exe --list --online

  • AlmaLinux-9を選択してインストール

    wsl.exe --install AlmaLinux-9

    プロンプトに従い、Linuxのユーザー名とパスワードを設定

初期セットアップ

WSL特有の設定を行うため、下記初期セットアップを実施

systemdの有効化を確認

  • 最近のWSL及びLinuxディストリビューションではデフォルトで有効化済なので(恐らく)不要
  • /etc/wsl.confに下記行が含まれることを確認
    /etc/wsl.conf
    [boot]
systemd=true
  • なければファイルを作成または既存ファイルに追記し、wsl.exe --shutdownでWSLを停止
  • Windowsターミナルの再起動などによりWSLセッションを再開
  • systemctl statusコマンドでサービスの状態が表示されればOK

NetworkManagerの有効化

  • NetworkManagerがインストールされていない場合はインストール

    sudo dnf -y install NetworkManager

  • NetworkManagerサービスはデフォルトではmaskされているため、unmaskと有効化後、サービスを開始

    sudo systemctl unmask NetworkManager
sudo systemctl enable NetworkManager
sudo systemctl start NetworkManager

    これにより、libvirtによるLinuxブリッジの作成が可能になる

Vagrant一式のインストール

詳細はInstallation Guidesを参照

Vagrantインストール

  • HashiCorpのレポジトリからVagrantをインストール
    sudo dnf -y install dnf-plugins-core
sudo dnf -y config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo dnf -y install vagrant

Libvirt及びvagrant-libvirt pluginのインストール

  • CRBレポジトリを有効化(libvirt-develをインストールするため)

    sudo dnf config-manager --set-enabled crb

  • 仮想化・開発ツール関連をまとめてインストール

    sudo dnf -y install '@Virtualization Hypervisor' '@Virtualization Tools' '@Development Tools' libvirt-devel

  • vagrantコマンドでpluginをインストール

    vagrant plugin install vagrant-libvirt

WSLのユーザーをlibvirtグループに追加

  • ユーザー権限でvagrantからlibvirtを使えるようにする
    sudo usermod -a -G libvirt <username>
    グループにユーザー追加後、変更を反映するにはログアウトと再ログインが必要

環境変数の設定

  • Vagrantのデフォルトプロバイダをlibvirtに設定
    # ~/.bashrc や ~/.zshrc などに追記
export VAGRANT_DEFAULT_PROVIDER="libvirt"
    • VagrantはWSL上で動いていることを検出する
    • WSL上のVagrantはデフォルトでWindows上のVirtualBox, Hyper-Vを想定しており、上記設定がないとエラーする

インストール後の確認

実行例を示す

  • Vagrant
    $ vagrant version
Installed Version: 2.4.7
Latest Version: 2.4.7

    $ vagrant plugin list
vagrant-libvirt (0.12.2, global)
  • KVMモジュールのロード
    $ lsmod | grep kvm
kvm_intel             356352  0
kvm                   970752  1 kvm_intel
irqbypass              12288  1 kvm
    ロードされていなければ、vagrant実行前にmodprobe kvm_intel (or kvm_amd)を実行
  • /dev/kvmのパーミッション (オーナーroot:kvmでグループの書き込み権限あり)
    $ ls -l /dev/kvm
crw-rw-rw- 1 root kvm 10, 232 Jul 18 09:33 /dev/kvm

使ってみる

Vagrantfileの作成

  • サンプルのVagrantファイルをGitHubで公開

https://github.com/r0ckpine/vagrant-libvirt-wsl/blob/main/vagrant/minimal/Vagrantfile

  • Vagrant-libvirt固有設定箇所のチューニングポイント

    Vagrantfile
    cpu_mode = "host-passthrough" # 仮想マシンにホストCPUをパススルーし性能を最大化
nested = true # Nested Virtualizationを有効化し、仮想マシン内でさらに仮想マシンを作成可能に
disk_bus = "scsi" # Virtio SCSIを利用し性能を最大化
disk_driver :cache => "writeback", :discard => "unmap" # Writeキャッシュを利用
libvirt.machine_type = "q35" # マシンタイプはよりモダンなIntel Q35チップセットを指定

  • 注意点

    • vagrant-libvirtはパーティションサイズの自動拡張に未対応
    • 上記Vagrantfileでは、プロビジョニングスクリプト内でcloud-initをインストールし、リサイズを実行

  • Vagrant-libvirtの詳細設定は公式サイトを参照

Vagrant Boxの選択

LibvirtをサポートしているBoxを選択

セットアップから仮想マシン起動まで

GitHubで公開中のAnsible Playbookを利用したセットアップ例

# WSLの初期設定、Ansible, git のインストール後、レポジトリをクローン
git clone https://github.com/r0ckpine/vagrant-libvirt-wsl
cd vagrant-libvirt-wsl
# Ansibleプレイブックによるセットアップ (環境により5-15分程度)
ansible-playbook -i inventory/local setup-vagrant-libvirt.yml
# 必要に応じてログアウト 再ログイン

最小構成の仮想マシンを起動

# 環境変数を設定
export VAGRANT_DEFAULT_PROVIDER="libvirt"
cd vagrant-libvirt-wsl/vagrant/minimal
# 必要に応じてVagrantfile編集
# 仮想マシン起動
vagrant up
# 仮想マシンにSSHログイン
vagrant ssh
# 終わったら仮想マシンを破棄
vagrant destroy

よくある問題と対処法

CPUの仮想化機能が利用できない場合

  • BIOS/UEFIでIntel VT-x/AMD-Vが有効化されているか確認
  • lscpu | grep VirtualizationでCPU対応を確認

WSLへのメモリ割り当て不足

  • デフォルトのWSLメモリサイズはWindowsのメモリの50% (メモリ8GBなら4GBまで)
    • Vagrantで仮想マシンに割り当てるメモリが不足しないよう十分なメモリ割り当てが必要
    • .wslconfigで設定を変更

SystemD, Networkデーモンの起動

  • systemctl --versionの表示
  • RHEL系ではsystemctl status NetworkManager、Ubuntu系ではsystemctl status systemd-networkdの確認

環境変数の設定

  • export VAGRANT_DEFAULT_PROVIDER="libvirt"を設定、設定されていないと下記エラーが発生
    Vagrant failed to initialize at a very early stage:

Vagrant is unable to use the VirtualBox provider from the Windows Subsystem for
Linux without access to the Windows environment. Enabling this access must be
done with caution and an understanding of the implications. For more information
on enabling Windows access and using VirtualBox from the Windows Subsystem for
Linux, please refer to the Vagrant documentation:

https://www.vagrantup.com/docs/other/wsl.html

初回起動時の注意点

  • 初回vagrant up時は、Boxのダウンロードに時間がかかる
    • 事前にvagrant box add <box name>しておくとよい
  • 多段のNested Virtualizationを利用すると、通常より時間が大幅にかかる場合がある

vagrant upでエラーが発生する場合

  • libvirtサービスの状態確認: systemctl status libvirtd
  • ユーザーのlibvirtグループ所属確認: groupsコマンドで確認
  • /dev/kvmのパーミッション確認: /dev/kvmのオーナーがroot:kvmかつモードが0660以上
  • vagrantの作成するブリッジネットワークが既存ネットワークと競合
    • Vagrantfileでmanagement_network_address, private_networkなどのアドレスを変更

パフォーマンスに関する補足

  • Nested VirtualizationによるCPU性能オーバーヘッドは通常10-20%程度
  • WSL上での仮想マシン(Nested level 1)は十分実用的で、さらにその上での仮想マシン(Nested level 2)までは許容範囲内

謝辞

本記事は、Cloud Operator Days Tokyo 2025 (CODT2025)のオンラインセッション「Windowsで爆速クラウド基盤開発！Vagrant＋Libvirt+WSL2でOpenStackを動かす」を基にしています。
是非、CODT2025に登録して、ご視聴ください！

脚注
  1. ↩︎
  2. ↩︎
  3. ↩︎
  4. ↩︎
  5. ↩︎

Discussion