Forem: Zoltan Toma

Implementing Missing Integration Tests: Provisioners and Docker

Zoltan Toma — Sat, 22 Nov 2025 00:00:00 +0000

Finishing What We Started

The Vagrant WSL2 provider had a test/integration_old/todos/ folder with unimplemented tests. Two big ones: test_provisioners.ps1 and test_docker.ps1. Both just had TODO comments saying what they should test.

We’d already migrated the working tests to Pester 5.x format. The old homegrown PowerShell scripts worked fine - they just weren’t using a framework. Now we needed to implement these missing tests using the same Pester patterns.

Provisioners: One Monolith, Five Tests

The examples/provisioners/ directory had one massive Vagrantfile testing shell, file, ansible, chef, and salt provisioners all at once. To test them individually, we needed to split them up.

Created a subfolder for each provisioner:

examples/provisioners/
├── shell/
│ └── Vagrantfile
├── file/
│ ├── Vagrantfile
│ └── test-file.txt
├── ansible/
│ ├── Vagrantfile
│ └── test-playbook.yml
├── chef/
│ ├── Vagrantfile
│ └── cookbooks/
└── salt/
    ├── Vagrantfile
    └── states/

Each subfolder has its own self-contained Vagrantfile that demonstrates one provisioner. This makes them usable as examples and testable individually.

Provisioners.Tests.ps1

The Pester test defines separate Describe blocks for each provisioner:

# Provisioners.Tests.ps1
param([switch]$Full)

Describe "Vagrant WSL2 Provider - Shell Provisioner" {
    BeforeAll {
        $script:ExampleDir = Join-Path $PSScriptRoot "..\..\examples\provisioners\shell"
        $script:DistributionName = "vagrant-wsl2-shell-test"
        Push-Location $script:ExampleDir
        vagrant destroy -f 2>$null | Out-Null
    }

    AfterAll {
        vagrant destroy -f 2>$null | Out-Null
        Pop-Location
    }

    Context "When provisioning with shell scripts" {
        It "Should successfully run 'vagrant up --provider=wsl2'" {
            vagrant up --provider=wsl2
            $LASTEXITCODE | Should -Be 0
        }

        It "Should have created shell-test.txt file" {
            $result = vagrant ssh -c "test -f /home/vagrant/shell-test.txt && echo 'exists'" 2>&1
            $result -join "`n" | Should -Match "exists"
        }
    }
}

# Separate Describe blocks for file, ansible, chef, salt...

Quick mode runs shell, file, and ansible (the working provisioners). Full mode adds chef and salt, which have known issues:

Describe "Vagrant WSL2 Provider - Chef Solo Provisioner" -Tag "KnownIssue" -Skip:(-not $Full) {
    # Tests that we expect to fail due to chef symlink issues
}

Describe "Vagrant WSL2 Provider - SaltStack Provisioner" -Tag "KnownIssue" -Skip:(-not $Full) {
    # Tests that we expect to fail due to bootstrap URL changes
}

The -Skip:(-not $Full) means these only run when you pass -Full. Chef and Salt are documented to fail, but the tests are there to track the issues.

Rakefile tasks:

rake test_provisioners # Test shell, file, and ansible
rake test_provisioners_full # Test all including chef and salt

Docker: 22 Distributions, Individual Machines

The Docker test validates that Docker installs and runs on different WSL distributions. The old examples/docker-test/Vagrantfile used a loop that auto-created all VMs:

# Old approach
DISTRIBUTIONS.each do |distro|
  config.vm.define "docker-#{distro}" do |node|
    # auto-created on vagrant up
  end
end

This doesn’t work for selective testing. We refactored to individual machine definitions with autostart: false:

# New approach
config.vm.define "ubuntu2404", autostart: false do |node|
  node.vm.box = "Ubuntu-24.04"
  node.vm.provider "wsl2" do |wsl|
    wsl.distribution_name = "vagrant-docker-ubuntu2404"
    wsl.version = 2
    wsl.systemd = true
  end
  node.vm.provision "ansible_local" do |ansible|
    ansible.playbook = "provisioning/docker-debian.yml"
  end
end

config.vm.define "debian", autostart: false do |node|
  # ...
end

# ... 22 machines total

Now you can run vagrant up ubuntu2404 to test just one, or the Pester test can selectively spin up what it needs.

The test uses the same quick/full pattern:

# Docker.Tests.ps1
param([switch]$Full)

BeforeAll {
    $script:QuickMachines = @(
        @{ Name = "ubuntu2404"; Distro = "vagrant-docker-ubuntu2404" },
        @{ Name = "debian"; Distro = "vagrant-docker-debian" },
        @{ Name = "almalinux8"; Distro = "vagrant-docker-almalinux8" }
    )

    $script:AllMachines = @(
        # All 22 distributions
    )

    $script:TestMachines = if ($Full) {
        Write-Host "Running FULL Docker test (all $($script:AllMachines.Count) distributions)"
        $script:AllMachines
    } else {
        Write-Host "Running QUICK Docker test ($($script:QuickMachines.Count) distributions)"
        $script:QuickMachines
    }
}

Describe "Vagrant WSL2 Provider - Docker Support" {
    Context "When testing Docker installation across distributions" {
        It "Should successfully bring up <Name> with Docker" -ForEach $script:TestMachines {
            vagrant up $Name --provider=wsl2
            $LASTEXITCODE | Should -Be 0
        }
    }
}

Rakefile tasks:

rake test_docker # 3 distros
rake test_docker_full # 22 distros

The Parameter Passing Bug

To pass the -Full parameter from Invoke-PesterTests.ps1 to the test scripts, we had broken code:

# This doesn't work - ContainerParameters doesn't exist in Pester 5.x
$config.Run.ContainerParameters = @{ Full = $true }

The fix uses New-PesterContainer:

# Invoke-PesterTests.ps1
if ($Full) {
    $container = New-PesterContainer -Path $TestPath -Data @{ Full = $true }
    $config.Run.Container = $container
} else {
    $config.Run.Path = $TestPath
}

This is the correct way to pass parameters to Pester 5.x test scripts. Works for AllDistributions, Provisioners, and Docker tests.

What’s Still Broken

The Docker test isn’t discovering tests yet:

Discovery found 0 tests in 211ms.

The -ForEach $script:TestMachines parameter binding isn’t working. Something’s wrong with how we’re structuring the test data or the Describe block. That’s next session’s problem - we’re out of context.

What We Shipped

Provisioners.Tests.ps1 - Tests all 5 provisioners (shell, file, ansible, chef, salt)
Refactored provisioner examples - Individual Vagrantfiles for each provisioner
Docker.Tests.ps1 - Tests Docker across distributions
Refactored docker-test Vagrantfile - Individual machine definitions
Fixed parameter passing - Invoke-PesterTests.ps1 now uses New-PesterContainer properly
Updated Rakefile - New test tasks
Updated CLAUDE.md - Documented the new tests and structure

The TODO tests are no longer TODO. They’re implemented - just need to fix the Docker test discovery issue.

Vagrant WSL2 Provider is an MIT-licensed open source project. Check it out on GitHub.

Migrating Integration Tests to Pester: A PowerShell Testing Journey

Zoltan Toma — Sat, 22 Nov 2025 00:00:00 +0000

The Testing Problem

The vagrant-wsl2-provider had integration tests. They worked. They ran actual Vagrant commands and verified WSL2 distributions got created properly. But they were all custom PowerShell scripts with manual error handling, inconsistent output, and no real test framework.

Here’s what a typical test looked like:

try {
    Write-Host "Test: Starting VM..." -ForegroundColor Yellow
    vagrant up
    if ($LASTEXITCODE -ne 0) {
        throw "vagrant up failed"
    }
    Write-Host "[PASS] VM started" -ForegroundColor Green
} catch {
    Write-Host "[FAIL] Test failed" -ForegroundColor Red
    exit 1
}

It worked, but it was painful to maintain. Each test file had its own error handling, cleanup logic, and output formatting. And when something failed, you got a wall of red text with no clear indication of which specific assertion broke.

Time to modernize.

Why Pester?

Pester is PowerShell’s native testing framework. It’s been around since 2011, and version 5.x brought major improvements. More importantly, it’s what PowerShell developers actually use.

The benefits were clear:

Structured tests - Describe, Context, It blocks instead of ad-hoc scripts
Better assertions - Should -Be instead of manual if ($LASTEXITCODE -ne 0)
Proper output - Test results with timing, pass/fail counts, and detailed failure info
BeforeAll/AfterAll - Consistent setup and cleanup
Skip support - Conditionally skip tests (critical for admin-required tests)

Plus, Pester integrates with CI/CD tools, has good VS Code support, and produces JUnit XML reports if you need them.

The Migration Strategy

I didn’t want to rewrite everything from scratch. The existing tests worked and covered real functionality. So the plan was:

Move to test/pester/ directory - Keep legacy tests in test/integration/ for reference
Convert one test at a time - Start simple, learn patterns, iterate
Keep the same examples/ structure - Tests still run against actual Vagrantfiles
Add proper cleanup - BeforeAll/AfterAll for consistent environment
Handle Windows quirks - Admin privileges, path issues, PowerShell redirection

Test Structure: The Pester Way

Here’s what the basic test structure looked like after conversion:

BeforeAll {
    $script:ExampleDir = Join-Path $PSScriptRoot "..\..\examples\basic"
    Push-Location $script:ExampleDir

    # Cleanup before tests
    vagrant destroy -f 2>$null | Out-Null
}

AfterAll {
    # Cleanup after all tests
    vagrant destroy -f 2>$null | Out-Null
    Pop-Location
}

Describe "Vagrant WSL2 Provider - Basic Operations" {
    Context "When creating a new VM" {
        It "Should successfully run 'vagrant up --provider=wsl2'" {
            vagrant up --provider=wsl2
            $LASTEXITCODE | Should -Be 0
        }

        It "Should create WSL distribution" {
            $wslList = (wsl -l -v | Out-String) -replace '\0', ''
            $wslList | Should -Match "vagrant-wsl2-basic"
        }
    }

    Context "When destroying the VM" {
        It "Should successfully run 'vagrant destroy -f'" {
            vagrant destroy -f
            $LASTEXITCODE | Should -Be 0
        }
    }
}

Clean. Readable. Each It block is a single assertion. Context blocks group related tests. And BeforeAll/AfterAll handle setup and cleanup.

Challenge 1: Administrator Privileges

Several tests require administrator privileges - creating VHDs for data disks, configuring network adapters, mounting disks in WSL2. The old tests just checked permissions and exited with a message:

if (-not $isAdmin) {
    Write-Host "SKIPPED: Administrator required"
    exit 0
}

But with Pester, you want the tests to show up in the results, not just silently exit. The solution was Pester’s -Skip parameter:

# Check admin rights early for informative message
$isAdminCheck = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $isAdminCheck) {
    Write-Host ""
    Write-Host "=== Data Disk Test SKIPPED ===" -ForegroundColor Yellow
    Write-Host "Reason: Administrator privileges required" -ForegroundColor Yellow
    Write-Host ""
    Write-Host "Data disk features require:" -ForegroundColor Gray
    Write-Host " - VHD creation (New-VHD cmdlet)" -ForegroundColor Gray
    Write-Host " - WSL disk mounting (wsl --mount)" -ForegroundColor Gray
    Write-Host ""
    Write-Host "To run this test, please restart PowerShell as Administrator" -ForegroundColor Cyan
    Write-Host ""
}

Describe "Vagrant WSL2 Provider - Data Disk" -Skip:(-not $isAdminCheck) -Tag @('RequiresAdmin') {
    # Tests run only if admin
}

This way:

Non-admin users see a clear message explaining why tests are skipped
Tests appear in Pester output as skipped (not hidden)
The -Tag @('RequiresAdmin') lets you filter tests by privilege level
Running as admin? Tests execute normally

Claude: The admin check happens at file scope before Pester even loads, so the message appears immediately. Then Pester sees the -Skip flag and marks all tests as skipped. Best of both worlds.

Challenge 2: Directory Management Hell

This one was subtle. The tests need to run in the example directory (where the Vagrantfile lives). Easy enough:

BeforeAll {
    Push-Location $script:ExampleDir
}

But here’s the trap: if the test is skipped due to admin privileges, BeforeAll still runs. And if you put the Push-Location after the admin check with an early return, the directory never changes, but the tests try to run anyway.

Result? vagrant commands fail with “A Vagrant environment or target machine is required” because you’re in the wrong directory.

The fix was to always Push-Location, even for skipped tests:

BeforeAll {
    $script:ExampleDir = Join-Path $PSScriptRoot "..\..\examples\data-disk"

    # Store admin status for skip condition
    $script:isAdmin = $isAdminCheck

    # Always push location, even if skipping (for proper cleanup)
    Push-Location $script:ExampleDir

    if (-not $script:isAdmin) {
        return # Skip setup, but directory is already changed
    }

    # Cleanup before tests (only if admin)
    vagrant destroy -f 2>$null
}

AfterAll {
    if ($script:isAdmin) {
        # Cleanup after all tests
        vagrant destroy -f 2>$null
    }

    # Always pop location
    Pop-Location
}

Now the directory state is always consistent, whether tests run or not.

Challenge 3: PowerShell Output Redirection

I’ve been writing PowerShell for years and I still get this wrong.

The old tests had things like:

$output = vagrant up --provider=wsl2 2>&1

Looks reasonable, right? Redirect stderr to stdout, capture everything. Except in PowerShell, 2>&1 at the end of a command doesn’t work the way Bash users expect.

For cleanup commands piped to Out-Null, you need:

vagrant destroy -f 2>$null | Out-Null

Not:

vagrant destroy -f 2>&1 | Out-Null # Wrong!

The 2>$null redirects stderr to null, and | Out-Null discards stdout. Together they suppress all output.

And for capturing multi-line output to match against patterns:

$ipCheck = (wsl -d vagrant-wsl2-networking-demo -- ip addr show eth0) -join "`n"
$ipCheck | Should -Match "192.168.33.10"

The -join "n"` is critical. Without it, you’re matching against an array, and Pester only shows the first element in error messages. With the join, you get a single string with all lines, and regex matching works across the entire output.

Claude: We spent a solid 20 minutes debugging why IP address checks were failing, only to discover the output was there, just on line 4 instead of line 1. Classic PowerShell array behavior.

The Fast/Slow Distribution Test

The AllDistributions test validates which WSL distributions work with the provider. There are 22 distributions available from wsl -l -o. Testing all of them takes forever.

So I added a parameter to control test scope:

`
param(
[switch]$Full
)

BeforeAll {
# Quick subset for fast testing (different distro families)
$script:QuickDistributions = @(
"Ubuntu-24.04", # Debian-based
"Debian", # Pure Debian
"AlmaLinux-8" # RHEL-based
)

# All distributions
$script:AllDistributions = @(
    "Ubuntu-24.04",
    "Debian",
    "AlmaLinux-8",
    # ... 19 more distributions
)

# Select which to test based on parameter
$script:WslDistributions = if ($Full) {
    $script:AllDistributions
} else {
    $script:QuickDistributions
}

}

Now you can run:

`
rake test_all_distributions # Quick: 3 distributions
rake test_all_distributions_full # Full: 22 distributions

The quick test covers the major distro families (Debian, Ubuntu, RHEL) and runs in minutes. The full test is for pre-release validation.

The Invoke-PesterTests Runner

To make all this work, I needed a centralized test runner that could pass parameters through:

`
param(
[string]$TestFile = $null,
[ValidateSet('Detailed', 'Normal', 'Minimal')]
[string]$Output = 'Detailed',
[switch]$Full # For AllDistributions: run all distributions
)

$ErrorActionPreference = "Stop"

Ensure Pester 5.x is imported

Import-Module Pester -MinimumVersion 5.0 -ErrorAction Stop

$TestPath = $PSScriptRoot

if ($TestFile) {
$TestPath = Join-Path $TestPath "$TestFile.Tests.ps1"
}

Build Pester configuration

$config = New-PesterConfiguration
$config.Run.Path = $TestPath
$config.Output.Verbosity = $Output
$config.Run.PassThru = $true

Pass parameters to test scripts

if ($Full) {
$config.Run.ContainerParameters = @{ Full = $true }
}

Run tests

$result = Invoke-Pester -Configuration $config
exit $result.FailedCount

This runner:

Loads Pester 5.x (ensuring compatibility)
Accepts a -TestFile parameter to run specific tests
Passes the -Full flag through to the test script
Returns proper exit codes for CI/CD

What Got Converted

All the integration tests are now Pester-based:

Basic.Tests.ps1 - vagrant up, ssh, destroy (11 tests)
DataDisk.Tests.ps1 - VHD creation, mounting, persistence (15 tests, requires admin)
Snapshot.Tests.ps1 - save, restore, list, delete, push/pop (10 tests)
Networking.Tests.ps1 - static IPs, port forwarding (4 tests, requires admin)
MultiVmNetwork.Tests.ps1 - multi-VM networking, VM isolation (9 tests, requires admin)
AllDistributions.Tests.ps1 - distribution compatibility (3 quick / 22 full)

Total: 62 test cases (quick mode) or 81 test cases (full mode).

The legacy tests are still in test/integration/ for reference, but all new work uses Pester.

Lessons Learned

Windows testing is different. Admin privileges, path handling, output encoding - you can’t just port Unix testing patterns. PowerShell has its own quirks, and fighting them is pointless. Learn the PowerShell way.

Pester’s skip functionality is crucial. Tests that require specific conditions (admin rights, specific OS, etc.) should show up as skipped, not silently disappear. It makes it clear what’s being tested and what’s not.

Always cleanup, even on failure. The AfterAll block runs even if tests fail. Use it. Clean up VMs, delete temp files, reset state. Future you will thank present you.

Parameters make tests flexible. The fast/slow distribution test pattern could apply to other scenarios - integration vs. smoke tests, with/without network, etc. Parameters let you control test scope without duplicating code.

Real output matters. Pester’s output shows you exactly what failed, with timing information and clear pass/fail counts. It’s a huge improvement over custom Write-Host messages.

What’s Next

The tests are working, but there’s cleanup to do:

Remove the legacy test/integration/test_*.ps1 files (keeping only run_all_tests.ps1 for compatibility)
Add more Pester tests for edge cases (network failures, disk full, WSL2 not installed)
Integrate with GitHub Actions for automated testing on commits
Maybe add performance benchmarks using Pester’s timing data

But for now, the integration tests are solid. They run fast (quick mode), cover all major functionality, and produce clear results.

And they’re actually maintainable, which is the whole point.

The vagrant-wsl2-provider is open source on GitHub. If you’re working on Windows tooling and need inspiration for testing WSL2 integrations, the Pester tests might help.

Testing 22 WSL Distributions Live on Twitch (13 Passed, 9 Failed)

Zoltan Toma — Sun, 16 Nov 2025 00:00:00 +0000

The Question Nobody Asked

Which WSL distributions from the Windows Store actually work with the Vagrant WSL2 Provider?

I didn’t know. And I realized - that’s a problem.

The provider uses wsl --install --distribution <name> to download and install distributions directly from the Windows Store. But there are 22 distributions available, and I’d only tested Ubuntu-24.04.

Time to find out what works and what doesn’t.

Building the Test

The goal was simple: iterate through every distribution from wsl -l -o, try to create a Vagrant environment with it, and document what fails.

This is a sanity check, not a certification test. We expect failures. We want to know which distributions fail and why.

The Test Structure

Pester makes this straightforward:

BeforeAll {
    # WSL distributions available from Windows Store
    $script:WslDistributions = @(
        "AlmaLinux-8",
        "AlmaLinux-9",
        "Debian",
        "Ubuntu-24.04",
        # ... 22 total
    )

    $script:TestBaseDir = Join-Path $PSScriptRoot "..\..\examples\test-distributions"
    $script:TestResults = @{}
}

Describe "WSL Distribution Compatibility Tests" {
    Context "Testing each distribution" {
        It "Should test all distributions" {
            foreach ($distribution in $script:WslDistributions) {
                # Step 1: vagrant init
                vagrant init $distribution

                # Step 2: Configure WSL2 provider
                # (modify Vagrantfile to add wsl2 provider config)

                # Step 3: vagrant up --provider=wsl2
                $upOutput = vagrant up --provider=wsl2 2>&1

                # Step 4: vagrant destroy -f
                vagrant destroy -f

                # Track results
                $script:TestResults[$distribution] = @{
                    Success = ($LASTEXITCODE -eq 0)
                    Error = $errorMsg
                }
            }
        }
    }
}

Each distribution gets its own folder in examples/test-distributions/, runs through the full lifecycle (vagrant init, up, destroy), and gets cleaned up afterward.

The test runs to completion even if distributions fail. We capture all the errors and display a summary at the end.

Claude: Fun fact - we initially tried using Pester’s -TestCases with dynamic distribution lists, but Pester evaluates test cases at discovery time, not runtime. So we went with a single test that loops through distributions manually.

Streaming the Run

I ran this live on Twitch. Because why not? Watching 22 distributions install, provision, and clean up takes time. Might as well make it public.

Each test took anywhere from 30 seconds (for distributions that failed fast) to 2-3 minutes (for successful ones that needed to download, install, and configure systemd).

Total runtime: 17 minutes, 33 seconds (1053.89s reported by Pester).

The Results

=== Distribution Compatibility Summary ===

Supported Distributions (13):
  [PASS] AlmaLinux-8
  [PASS] AlmaLinux-9
  [PASS] AlmaLinux-Kitten-10
  [PASS] AlmaLinux-10
  [PASS] Debian
  [PASS] FedoraLinux-43
  [PASS] FedoraLinux-42
  [PASS] SUSE-Linux-Enterprise-16.0
  [PASS] Ubuntu
  [PASS] Ubuntu-24.04
  [PASS] kali-linux
  [PASS] openSUSE-Tumbleweed
  [PASS] openSUSE-Leap-16.0

Unsupported/Failed Distributions (9):
  [FAIL] archlinux
         Error: tee: /etc/sudoers.d/vagrant: No such file or directory

  [FAIL] SUSE-Linux-Enterprise-15-SP7
         Error: chown: invalid group: 'vagrant:vagrant'

  [FAIL] Ubuntu-20.04
  [FAIL] OracleLinux_7_9
  [FAIL] OracleLinux_8_10
  [FAIL] OracleLinux_9_5
         Error: Distribution not found after installation completed

  [FAIL] Ubuntu-22.04
  [FAIL] openSUSE-Leap-15.6
  [FAIL] SUSE-Linux-Enterprise-15-SP6
         Error: Using legacy distribution registration

Total: 22 distributions tested
Success Rate: 13/22 (59.1%)

What Worked

The AlmaLinux family (all 4 versions), Fedora, Debian, current Ubuntu versions, Kali Linux, and openSUSE’s latest releases all passed.

That’s 13 distributions spanning multiple Linux families. Not bad for a provider that started as “let’s just get Ubuntu working.”

What Failed - And Why

The failures break down into 4 categories:

1. Legacy Distribution Registration (4 distros)

Error: Using legacy distribution registration.
Consider using a tar based distribution instead.

Ubuntu-22.04, openSUSE-Leap-15.6, and SUSE Linux Enterprise 15-SP6 all hit this. WSL is warning that these distributions use an older registration format.

The provider handles tar-based imports fine (that’s how we clone distributions for snapshots). But wsl --install for these specific distributions triggers the legacy path, and something in our provisioning flow doesn’t handle it.

2. Distribution Not Found After Installation (4 distros)

Error: Distribution 'Ubuntu-20.04' not found after installation completed.
Check if installation was successful.

Ubuntu-20.04 and all three OracleLinux versions hit this. The wsl --install command completes, reports success, but when we check wsl -l -v to verify the distribution is there, it’s not listed.

This could be a timing issue (installation takes longer than we expect), a naming mismatch (we search for the exact distribution name but it registers under a different one), or these distributions genuinely fail to install.

3. Missing /etc/sudoers.d/ Directory (1 distro)

Error: tee: /etc/sudoers.d/vagrant: No such file or directory

Arch Linux doesn’t have /etc/sudoers.d/ by default. Our provisioning script tries to add the vagrant user’s sudo config there and fails.

This is a simple fix - check if the directory exists first, or fall back to appending directly to /etc/sudoers.

4. Invalid Group Error (1 distro)

Error: chown: invalid group: 'vagrant:vagrant'

SUSE Linux Enterprise 15-SP7 doesn’t let us create the vagrant:vagrant group the way we expect. Could be SELinux, could be enterprise defaults, needs investigation.

Bugs We Found Along the Way

While building and running this test, we discovered some provider bugs that needed documenting:

Documentation vs Reality

The CLAUDE.md file listed memory, cpus, gui_support, swap, and kernel_command_line as supported configuration options. Turns out they’re only defined in config.rb but never actually implemented in the provider.

Fixed the docs to be honest: “Additional configuration options are defined but not yet implemented.”

Naming Convention Bug

The provider uses distribution_name for the WSL distribution name, but doesn’t follow Vagrant’s standard naming conventions. If the box isn’t named correctly, vagrant destroy won’t remove it from WSL distributions.

This leaves orphaned WSL distributions sitting around after you think you’ve cleaned up. Added to the bug list.

These aren’t critical (the provider works), but they’re the kind of rough edges you find when you actually test things properly.

What This Means

We have a 59% success rate across all available WSL distributions. That’s higher than I expected, honestly.

The failures aren’t random. They fall into clear categories:

Legacy formats - Need to handle older distribution registration
Installation timing - Verify distributions exist before proceeding
Filesystem assumptions - Stop assuming /etc/sudoers.d/ exists
Group creation - Handle enterprise distributions differently

None of these are dealbreakers. They’re just edge cases we haven’t coded for yet.

Why This Matters

This test doesn’t just tell us what works. It tells us what to fix next.

Before this, I had no idea which distributions were broken or why. Now I have a reproducible test that documents exactly which features fail on which distributions.

More importantly: This test runs fast (17 minutes for 22 distributions). I can run it after every major change to catch regressions.

And when someone opens an issue saying “Provider doesn’t work with OracleLinux,” I can point to the test results and say: “Yeah, I know. Here’s the error. Want to help fix it?”

Claude: Also worth noting - we caught a documentation bug during this session. CLAUDE.md listed memory and cpus as supported configuration options, but they’re only defined in the config, not actually implemented. Fixed that too.

What’s Next

The test is in. The results are documented. Now comes the fun part: fixing the failures.

Priority targets:

Arch Linux - Should be a 5-minute fix (check if directory exists)
Legacy distributions - Figure out what “tar based distribution” actually means for our flow
Oracle/Ubuntu older versions - Debug why installations report success but don’t register

The test stays in the repo. Future releases will include updated compatibility matrices.

And yeah, I’ll probably stream the fixes too.

Try It Yourself

The test is in the repo:

git clone https://github.com/LeeShan87/vagrant-wsl2-provider
cd vagrant-wsl2-provider
rake test_all_distributions

Note: This will download and test 22 WSL distributions. Budget ~20 minutes and some bandwidth.

Results will vary based on your Windows version, WSL version, and what distributions you already have installed.

If you find different results, open an issue. This is how we make the provider better.

Lessons from this session:

Sanity checks are worth the time investment
Live streaming makes long test runs more tolerable
59% success rate beats 0% knowledge
Document what’s broken before trying to fix it
Pester makes it easy to iterate through test cases cleanly

Next post: Actually fixing the failures. Stay tuned.

Why I Chose Pester Over Custom Test Scripts (And Why Now)

Zoltan Toma — Mon, 10 Nov 2025 00:00:00 +0000

The Testing Journey So Far

When I started this Vagrant WSL2 Provider project, I knew unit tests would be a waste of tokens. My requirements change daily. AI pair programming with Claude means rapid iteration, constant refactoring, and features that evolve as I discover what WSL2 can and can’t do.

So I skipped unit tests entirely and went straight to integration tests. Simple PowerShell scripts that do the real thing:

vagrant up --provider=wsl2
if ($LASTEXITCODE -ne 0) { throw "failed" }
Write-Host "[PASS] vagrant up succeeded" -ForegroundColor Green

It worked. It was fast to write. And for a while, it was enough.

When the Custom Framework Started Hurting

The project grew. We shipped v0.3.0 with snapshot support and data disks. Then came networking support, and that’s where things got interesting (read: broken).

I started noticing weird behavior:

vagrant status always showed “running” even after vagrant halt
SSH commands with background processes didn’t work
The & character in vagrant ssh -c "python3 -m http.server &" just… disappeared

The networking feature needed these to work. Start a web server on one VM, connect to it from another. Basic stuff. Except it didn’t work.

And I had no tests for it.

The Real Problem

I could write more custom PowerShell test scripts. That wasn’t the issue. The issue was:

Token waste - Claude and I were spending time debugging test output formatting instead of fixing bugs
No structure - Every test script had its own cleanup logic, error handling, and output style
Missing coverage - We had tests for features that worked, not for bugs we needed to fix
Manual everything - Want better output? Write more Write-Host calls

I started thinking: “What if this custom testing framework became an open-source project?”

Then I realized: Nobody would use it. Because Pester already exists.

Claude: Can confirm. We literally googled “PowerShell testing framework” and found Pester in about 10 seconds.

Why Pester, Why Now

Pester is the standard PowerShell testing framework. It’s:

Built into Windows 10/11 (though we needed to upgrade to 5.x)
BDD-style syntax (Describe, Context, It)
Proper assertions (Should -Be, Should -Match)
Automatic setup/teardown (BeforeAll, AfterAll)
Better reporting (colored output, timing, clear pass/fail)

More importantly: I’m about to write tests that document bugs. Not tests that pass. Tests that fail, on purpose, to show exactly what’s broken.

For that, I need a real framework.

The Migration

The old way (119 lines):

try {
    Push-Location $ExampleDir
    vagrant destroy -f 2>$null

    vagrant up --provider=wsl2
    if ($LASTEXITCODE -ne 0) {
        throw "vagrant up failed with exit code $LASTEXITCODE"
    }
    Write-Host "[PASS] vagrant up succeeded" -ForegroundColor Green

    # ... more tests ...

    exit 0
} catch {
    Write-Host "=== Test FAILED ===" -ForegroundColor Red
    vagrant destroy -f 2>$null
    exit 1
} finally {
    Pop-Location
}

The new way (67 lines):

BeforeAll {
    $script:ExampleDir = Join-Path $PSScriptRoot "..\..\examples\basic"
    Push-Location $script:ExampleDir
    vagrant destroy -f 2>$null | Out-Null
}

AfterAll {
    vagrant destroy -f 2>$null | Out-Null
    Pop-Location
}

Describe "Vagrant WSL2 Provider - Basic Operations" {
    Context "When creating a new VM" {
        It "Should successfully run 'vagrant up --provider=wsl2'" {
            vagrant up --provider=wsl2
            $LASTEXITCODE | Should -Be 0
        }
    }
}

Cleaner. More structure. Automatic cleanup. And when something fails, I get this:

[-] Should show correct state after halt (not running) 6.27s (6.27s|1ms)
    Expected regular expression 'running' to not match
    'Current machine states:

    default running (wsl2)

    The WSL2 distribution is running', but it did match.

That’s way better than parsing my custom [PASS] / [FAIL] output.

Documenting Bugs with Tests

Here’s the important part. I didn’t just migrate existing tests. I added new ones that fail on purpose :

Context "When managing VM state" {
    It "Should successfully halt the VM" {
        vagrant halt
        $LASTEXITCODE | Should -Be 0
    }

    It "Should show correct state after halt (not running)" {
        Start-Sleep -Seconds 2
        $status = (vagrant status) -join "`n"

        # After halt, should NOT show "running"
        $status | Should -Not -Match "running"
    }
}

This test fails. As it should. Because vagrant halt doesn’t actually change the status output. That’s the bug.

Another one:

It "Should start a background process (Python web server)" {
    $output = vagrant ssh -c "python3 -m http.server 8888 > /dev/null 2>&1 &" 2>&1
    $LASTEXITCODE | Should -Be 0

    Start-Sleep -Seconds 2

    $psOutput = vagrant ssh -c "ps aux | grep 'http.server' | grep -v grep" 2>&1
    $psOutput | Should -Match "http.server"
}

Also fails. The background process doesn’t start. SSH command escaping is broken.

Test Results

After the migration:

Tests Passed: 11, Failed: 3

11 passing tests - The features that work
3 failing tests - The bugs I need to fix

That’s the state of the project right now. Green for confidence, red for work to do.

Why This Matters

I’m not writing tests for test coverage. I’m writing tests because I don’t want to pull my hair out debugging regressions.

When someone opens a PR, I want them to run rake test_pester and see what they broke (or fixed). When I refactor the SSH action, I want to know immediately if I broke ansible provisioner support.

Unit tests wouldn’t catch that. Integration tests do.

When This Approach Works

This testing strategy isn’t universal. It works specifically because:

The context is right:

Hobbyist/MVP project with changing requirements
AI-assisted development (not wasting tokens on test boilerplate)
Open source (contributors need to understand what’s safe to change)

The motivation is right:

Not “we need tests because best practices say so”
But “I found bugs, I need to document them, and I don’t want to break working features while fixing them”

The migration is pragmatic:

Not “throw away all tests and rewrite”
But “keep legacy tests running, migrate gradually, remove old ones when confident”

This is the opposite of cargo cult programming. No testing pyramids, no TDD dogma, no “you must have 80% coverage” rules. Just: what does this project actually need right now?

And right now, it needs:

Confidence that basic features work (11 green tests)
Documentation of known bugs (3 red tests)
A framework that won’t waste our time when we add more tests

Pester gives us that. A custom framework wouldn’t scale. Unit tests would miss the real issues.

The Setup

Getting Pester working was surprisingly smooth:

# Rakefile
desc "Ensure Pester 5.x is installed (>= 5.0, < 6.0)"
task :ensure_pester do
  pester_check = <<~POWERSHELL
    $pester = Get-Module -ListAvailable -Name Pester |
      Where-Object { $_.Version -ge '5.0' -and $_.Version -lt '6.0' } |
      Select-Object -First 1
    if (-not $pester) {
      Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
      Install-Module -Name Pester -RequiredVersion 5.7.1 -Force -Scope CurrentUser
    }
  POWERSHELL
  sh "powershell -Command \"#{pester_check.gsub("\n", "; ")}\""
end

Now rake test_pester automatically checks for Pester 5.x and installs it if needed. Version locked to avoid the 6.x alpha. One less thing to think about.

What’s Next

Now comes the fun part: fixing the bugs.

The vagrant halt status issue is probably in the state tracking logic. The SSH background process issue is definitely in how we escape shell commands. Both have tests that document exactly what should happen.

This is reverse TDD. Write the tests after you find the bugs, then fix the code until the tests pass.

Not ideal, but way better than:

Fixing a bug
Manually testing it
Breaking it again three commits later
Discovering it broke when trying to demo the feature

Been there. Done that. Got the T-shirt.

Try It Yourself

The Vagrant WSL2 Provider is on GitHub. The Pester tests are in test/integration/. If you want to see a real-world example of integration testing a Vagrant provider, check it out:

git clone https://github.com/LeeShan87/vagrant-wsl2-provider.git
cd vagrant-wsl2-provider
rake ensure_pester
rake test_pester

You’ll see the same 11 passing, 3 failing tests I see. And when I fix those bugs, you’ll see 14 passing tests.

That’s the plan, anyway.

Claude: Bold of you to assume the fixes won’t reveal more bugs.

Fair point.

When Your Quick Sunday Feature Takes All Day: WSL2 Multi-VM Networking

Zoltan Toma — Mon, 10 Nov 2025 00:00:00 +0000

“This Should Be Quick”

Famous last words.

After implementing basic networking support and learning about WSL2’s shared network architecture, I wanted to make it work reliably across multiple distributions. The plan: add integration tests, support more distros (Debian, Fedora, AlmaLinux, Kali, openSUSE), and document the limitations properly.

What I thought would be a quick Sunday afternoon turned into a deep dive into systemd services, DNS resolution, and why background processes in SSH are surprisingly hard.

Claude: Can confirm. We went from “let’s add a test” to “why is DNS broken on Debian” to “let’s refactor everything to use systemd services” in about 4 hours.

The Multi-Distro Challenge

Ubuntu was easy - it has netplan. But what about:

Debian - Uses systemd-networkd
Fedora/AlmaLinux/Kali - Use NetworkManager
openSUSE - Uses wicked

Each has its own network configuration system. My first instinct: support each one natively.

def write_netplan_config
  # Ubuntu with netplan
  netplan_config = <<~YAML
    network:
      version: 2
      ethernets:
        eth0:
          dhcp4: true
          addresses:
            - #{ip}/#{prefix}
  YAML

  @machine.communicate.sudo("netplan apply")
end

def write_networkmanager_config
  # Fedora/AlmaLinux/Kali
  @machine.communicate.sudo(
    "nmcli connection modify 'eth0' +ipv4.addresses #{ip}/#{prefix}"
  )
  @machine.communicate.sudo("nmcli connection up 'eth0'")
end

def write_systemd_networkd_config
  # Debian
  # ... and so on
end

Seemed reasonable, right?

The DNS Problem

Debian was the first to break.

vm2: Warning: Failed to fetch http://deb.debian.org/debian/dists/trixie/InRelease
vm2: Temporary failure resolving 'deb.debian.org'

The static IP was configured, but DNS stopped working after the provision script ran. Why?

After some debugging:

vagrant ssh vm2 -c "ip a show eth0"
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500
    inet 192.168.50.11/24 scope global eth0
    # Where's the WSL2 DHCP IP (172.x.x.x)?

Oh. The systemd-networkd restart command wiped out the WSL2 DHCP IP, which also provides DNS resolution and the default route. No DHCP IP = no DNS = broken apt.

Claude: This is the WSL2 version of “I deleted production.” Except you’re deleting your own network stack.

Ubuntu Wasn’t Better

Tried Ubuntu with netplan:

==> vm1: Netplan configuration written with 1 static IP(s)
systemd-networkd is not running, output might be incomplete.
Failed to reload network settings: Unit dbus-org.freedesktop.network1.service not found.
Falling back to a hard restart of systemd-networkd.service

Same problem. netplan apply tries to restart systemd-networkd, which breaks WSL2’s network management.

NetworkManager: Different Problem

Fedora seemed promising - NetworkManager should handle multiple IPs gracefully, right?

Error: Connection activation failed: No suitable device found for this connection
(device eth0 not available because profile is not compatible with device
(permanent MAC address doesn't match)).

Ah. WSL2’s MAC address changes on every restart. NetworkManager stores the MAC in the connection profile and refuses to work when it doesn’t match.

Great.

The Systemd Service Revelation

At this point I had three different broken approaches for three different distros. Time to step back.

What do we actually need?

Add static IP to eth0
Keep WSL2’s DHCP IP intact (for DNS/routing)
Persist across reboots
Work on all distros

What if… we just don’t touch the native network config systems at all?

def write_systemd_static_ip_service(after_services, distro_name)
  # Universal method for ALL distros
  ip_commands = @static_ips.map { |ip_info|
    "ip addr add #{ip_info[:ip]}/#{ip_info[:prefix]} dev eth0 || true"
  }.join("\n")

  service_config = <<~SERVICE
    [Unit]
    Description=Vagrant Static IP Configuration
    After=#{after_services}
    Wants=network-online.target

    [Service]
    Type=oneshot
    RemainAfterExit=yes
    ExecStart=/bin/bash -c '#{ip_commands}'

    [Install]
    WantedBy=multi-user.target
  SERVICE

  # Write service file
  @machine.communicate.sudo("mv #{service_path} /etc/systemd/system/vagrant-static-ip.service")
  @machine.communicate.sudo("systemctl daemon-reload")
  @machine.communicate.sudo("systemctl enable vagrant-static-ip.service")
  @machine.communicate.sudo("systemctl start vagrant-static-ip.service")
end

A systemd oneshot service that:

Runs after network is up
Adds static IPs with ip addr add
Uses || true so it’s idempotent
Doesn’t restart anything
Doesn’t touch WSL2’s DHCP configuration

And here’s the beautiful part - it works on every distro because they all use systemd.

The Refactor

Wait, why are we even detecting distros? The whole point of the systemd service is that it’s universal. And network-online.target works on all of them.

def write_netplan_config
  # Universal solution for all distros - systemd service
  # No need to detect distro or network manager
  write_systemd_static_ip_service
end

That’s it. No detection. No branching. One implementation.

From ~160 lines of distro-specific code to ~45 lines of universal code. DRY for the win.

Testing: The SSH Background Process Bug

Integration test time. Need to test VM-to-VM communication. Python HTTP server seems perfect:

# Start HTTP server on vm1
vagrant ssh vm1 -c "python3 -m http.server 8080 --bind 192.168.50.10 > /dev/null 2>&1 &"

# Test from vm2
vagrant ssh vm2 -c "curl http://192.168.50.10:8080/"

Except… it doesn’t work. The & background process never starts.

Why? Because of how we encode commands:

def encode_command(command)
  encoded = Base64.strict_encode64(command)
  "echo '#{encoded}' | base64 -d | bash"
end

That pipe to bash is blocking. Even with & at the end of the command, the SSH session waits for bash to finish. And bash waits for the backgrounded process because… pipes.

Tried eval instead:

"eval \"$(echo '#{encoded}' | base64 -d)\""

But that breaks redirect parsing because of the double quotes.

Solution: Leave it as a known bug for now, use PowerShell jobs in the test to work around it:

$serverJob = Start-Job -ScriptBlock {
    vagrant ssh vm1 -c "python3 -m http.server 8080 --bind 192.168.50.10"
}
Start-Sleep -Seconds 3
$http_result = vagrant ssh vm2 -c "curl http://192.168.50.10:8080/"
Stop-Job $serverJob

Not elegant, but it works. The SSH command encoding is a problem for another day.

Claude: Translation: “I’ll fix this later” = “This will ship as-is”

The README: Managing Expectations

After all this, I wrote probably the most important documentation - the limitations README. Because this feature works , but it has constraints:

## WSL2 Networking Limitations

⚠️ **Important:** Private network support in WSL2 is experimental.

### Shared Network Infrastructure
- All WSL2 VMs share the same virtual network switch
- Same MAC address - every VM gets the same MAC on each WSL restart
- Shared base IP - all VMs share the same WSL2 DHCP IP
- IP visibility - you may see other VMs' static IPs on a single VM

### What This Means
**VM-to-VM Communication:** ⚠️ LIMITED
- VMs share the same physical NIC and MAC address
- Ping between VMs using static IPs does not work reliably
- TCP/UDP application traffic may work if routing is configured correctly

**Windows Host Access:** ❌ LIMITED
- Use port forwarding instead

**Process Isolation:** ✅ WORKS
- Each distribution runs in its own PID namespace

Being honest about limitations is better than users discovering them the hard way.

Lessons Learned

1. Don’t Fight the Platform

My first instinct was to use each distro’s native network config system. But WSL2 isn’t a traditional VM - it has its own quirks. Fighting those quirks with netplan/NetworkManager/etc. just created more problems.

The systemd service approach works with WSL2’s design instead of against it.

2. Sometimes “Good Enough” Is the Win

Perfect VM-to-VM networking in WSL2? Not possible. The architecture doesn’t support it.

But adding static IPs that survive reboots and work across distros? That’s achievable. And for development/testing use cases, it’s useful.

3. Documentation > Implementation

The most important code I wrote today was the README explaining why things don’t work perfectly. Setting expectations upfront saves everyone frustration later.

4. Integration Tests Reveal Real Problems

Writing the test exposed the SSH background process bug, the DNS issues, and the MAC address problem. All things that wouldn’t show up in manual testing.

Even though the test needed workarounds, it was still valuable.

What’s Next

The networking feature works across 6 distributions (Ubuntu, Debian, Fedora, AlmaLinux, Kali, openSUSE). It’s documented. It has tests (mostly).

But there are TODOs:

Fix the SSH command encoding for background processes
Maybe explore WSL2 mirrored networking mode (Windows 11 22H2+)
Test with more complex network scenarios

For now though, it’s good enough. Users can run multi-VM setups for testing, the limitations are clear, and the code is maintainable.

That’s a win.

Claude: Started the session thinking “quick feature add.” Ended it having refactored the entire networking implementation and written a philosophical README about WSL2’s limitations. Classic Sunday.

Try It

The multi-VM networking example is in the repo:

git clone https://github.com/LeeShan87/vagrant-wsl2-provider
cd examples/multi-vm-network
vagrant up

Check the README for the full list of limitations and workarounds. And maybe don’t expect VirtualBox-level networking - this is WSL2, after all.

Actual time spent: 4+ hours Lines of code written: ~300 Lines of code deleted: ~100 Times I questioned my life choices: Several Would I do it again: Probably

Vagrant WSL2 Networking: A Reality Check

Zoltan Toma — Sat, 08 Nov 2025 00:00:00 +0000

Starting with High Hopes

After adding Docker support, snapshots, and data disk management to the Vagrant WSL2 Provider, networking felt like the obvious next step. The goal was simple: make config.vm.network work just like it does in VirtualBox.

config.vm.network "private_network", ip: "192.168.33.10"
config.vm.network "forwarded_port", guest: 80, host: 8080

How hard could it be?

Claude: Narrator: It was harder than expected.

The VirtualBox Mental Model

When you use VirtualBox, each VM gets its own network interfaces. Private networks create host-only adapters, each VM has its own IP, and everything just works. I assumed WSL2 would be similar - after all, it’s running on Hyper-V, right?

Wrong.

Reality: WSL2’s Architecture

Here’s what I learned (painfully) about WSL2 networking:

All WSL2 distributions run on a SINGLE Hyper-V VM.

Not separate VMs - one VM running multiple distributions in separate namespaces. This means:

Every distribution shares the same base IP address (something like 172.26.143.58)
Each distribution has its own network namespace
They all use the same eth0 interface in the WSL utility VM

When I created two test VMs:

config.vm.define "vm1" do |vm1|
  vm1.vm.network "private_network", ip: "192.168.50.10"
end

config.vm.define "vm2" do |vm2|
  vm2.vm.network "private_network", ip: "192.168.50.11"
end

Both got configured with their static IPs. Both showed up in ip addr. But when I checked from Windows - both had the same WSL base IP: 172.26.143.58.

The IP Alias Disaster

My first approach: “I’ll just add the static IP as an alias to the Windows WSL network adapter!”

# Add IP to Windows WSL adapter
cmd = "New-NetIPAddress -InterfaceAlias 'vEthernet (WSL)' " +
      "-IPAddress #{ip_address} -PrefixLength 24"

This kind of worked. The IP showed up on Windows. But then:

PS> Get-NetIPAddress -InterfaceAlias "vEthernet (WSL)"

IPAddress : 192.168.33.10
AddressState : Duplicate # OH NO

Duplicate Address Detection kicked in. Why? Because:

WSL VM’s eth0 has 192.168.33.10
Windows adapter also has 192.168.33.10
Same L2 network segment
Two different MAC addresses claiming the same IP
Windows: “Nope, that’s a duplicate, shutting it down”

The IP went into “Duplicate” state and stopped working.

Windows Routing to the Rescue

Instead of trying to put the same IP in two places, use routing:

def add_windows_route(static_ip, wsl_ip)
  cmd = "route add #{static_ip} mask 255.255.255.255 #{wsl_ip}"
  result = Vagrant::Util::Subprocess.execute("powershell", "-Command", cmd)
end

This tells Windows: “When you see traffic for 192.168.33.10, send it to 172.26.143.58 (the actual WSL IP).”

No duplicate IPs, no conflicts, just routing.

Admin Privileges Required

Of course, route add requires administrator privileges. So I added a check:

def has_admin_privileges?
  cmd = "([Security.Principal.WindowsPrincipal]" +
        "[Security.Principal.WindowsIdentity]::GetCurrent())" +
        ".IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)"

  result = Vagrant::Util::Subprocess.execute("powershell", "-Command", cmd)
  result.exit_code == 0 && result.stdout.strip.downcase == "true"
end

If you’re not running as admin, you get a clear warning and network configuration is skipped. The VM still starts, you just don’t get the fancy networking features.

Persistence Problem

Network configuration in Linux needs to survive reboots. The ip addr add command is immediate but temporary. I needed to write actual config files.

Plot twist: Different distributions use different network managers.

Ubuntu : Uses netplan
Debian : Uses systemd-networkd (no netplan)

Solution: Detect which one is available and write the appropriate config:

def write_netplan_config
  has_netplan = @machine.communicate.test("command -v netplan")

  if has_netplan
    write_ubuntu_netplan_config
  else
    write_systemd_networkd_config
  end
end

Ubuntu netplan config:

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: true
      addresses:
        - 192.168.33.10/24
        - 1.2.3.4/24

Debian systemd-networkd config:

[Match]
Name=eth0

[Network]
DHCP=yes
Address=192.168.33.10/24
Address=1.2.3.4/24

The Multi-VM Reality

Here’s the part that took me longest to accept: Windows host cannot distinguish between multiple WSL2 VMs using only their static IPs.

Why? Because they all share the same underlying WSL IP. When you add routes:

route add 192.168.50.10 -> 172.26.143.58 # vm1
route add 192.168.50.11 -> 172.26.143.58 # vm2 - same target!

Both routes point to the same WSL IP. Windows can’t tell them apart.

What DOES work:

VM-to-VM communication via static IPs (they’re in separate namespaces)
Process isolation (completely separate PID spaces)
Different services listening on the same ports in different VMs

What DOESN’T work:

Windows host accessing VMs via their static IPs
Each VM having a truly independent IP from Windows perspective

The solution: Use port forwarding for Windows host access:

config.vm.define "web" do |web|
  web.vm.network "forwarded_port", guest: 80, host: 8080
end

config.vm.define "api" do |api|
  api.vm.network "forwarded_port", guest: 80, host: 8081
end

Different ports on localhost, clear separation, works perfectly.

Port Forwarding Implementation

Port forwarding uses Windows netsh portproxy:

def setup_port_forward(listen_address, listen_port, connect_address, connect_port)
  listen_addresses = listen_address == "0.0.0.0" ? ["127.0.0.1"] : [listen_address]

  listen_addresses.each do |addr|
    cmd = "netsh interface portproxy add v4tov4 " +
          "listenaddress=#{addr} listenport=#{listen_port} " +
          "connectaddress=#{connect_address} connectport=#{connect_port}"

    Vagrant::Util::Subprocess.execute("powershell", "-Command", cmd)
  end
end

This creates a proper TCP proxy on Windows that forwards traffic to the WSL VM.

Testing the Reality

I created a multi-VM example to document the behavior:

From vm1:

vagrant ssh vm1
sudo python3 -m http.server 80 --bind 192.168.50.10

From vm2:

vagrant ssh vm2
curl 192.168.50.10 # Works! Returns directory listing

VM-to-VM communication via static IPs works perfectly. Each VM is isolated, has its own processes, its own network namespace.

From Windows:

curl 192.168.50.10 # Timeout - can't distinguish which VM

Doesn’t work. The route points to the shared WSL IP, and Windows can’t tell which VM should handle the request.

Documentation Over Pretending

Instead of trying to make WSL2 behave like VirtualBox (impossible), I documented the reality in the README:

WSL2 has a unique networking architecture that differs from traditional hypervisors. All distributions run on a single Hyper-V VM with shared networking. Static IPs work for inter-VM communication but not for Windows host access. Use port forwarding for host-to-VM connectivity.

No marketing speak. No “it’s a feature not a bug.” Just: here’s how it works, here’s what you can do with it, here are the limitations.

What’s Next

The networking implementation is done and working within WSL2’s constraints:

✅ Static IP configuration (Ubuntu netplan + Debian systemd-networkd)
✅ Port forwarding via netsh portproxy
✅ Admin privilege checking
✅ Multi-VM inter-VM communication
✅ Clear documentation of limitations

Next up: Cleaning up error handling, writing integration tests, and preparing for v0.4.0 release.

Try It Yourself

The networking support is in the feature/networking-support branch:

# Clone the repo
git clone https://github.com/LeeShan87/vagrant-wsl2-provider
cd vagrant-wsl2-provider
git checkout feature/networking-support

# Install locally (requires admin)
rake install_local

# Try the networking example
cd examples/networking
vagrant up # Requires administrator privileges

Check out examples/multi-vm-network/README.md for the full explanation of WSL2 networking behavior and limitations.

Lesson learned: Sometimes you start building a feature and discover the platform doesn’t work the way you thought. Instead of fighting reality, document it honestly and work within the constraints. The result might not match your original vision, but it’s better than pretending limitations don’t exist.

Three VM Crashes Later, I Built Data Disk Support

Zoltan Toma — Sat, 01 Nov 2025 00:00:00 +0000

Three Times

My colleague lost his VM three times. Not in a year - in the last few months we’ve been working together.

Each time it happened, we’d shrug it off. That’s what Vagrant is for, right? Just run vagrant up and you’re back in business. The development environment is code - it’s reproducible.

Except it wasn’t.

All three times, he had uncommitted work on that VM. Database migrations half-done. Configuration files tweaked just right but not yet committed. Local test data. You know, the stuff you’re “definitely going to commit tomorrow.”

Why Everything Lives on the VM

We work on Windows with VirtualBox VMs. But here’s the thing - we clone everything into the VM, not to shared folders. Why?

Linux filesystem compatibility. Case-sensitive paths. Symlinks that actually work. File permissions that make sense. Performance that doesn’t crawl to a halt when node_modules has 50,000 files.

So yeah, everything lives inside the VM. Which means when the VM dies, everything dies with it.

After the third time, I decided: data disk support isn’t a nice-to-have. It’s more important than networking, more important than fancy features. My colleague shouldn’t lose work because we didn’t have a way to separate persistent data from ephemeral VMs.

The Plan

I’d been building a Vagrant provider for WSL2 (because VirtualBox and WSL2 don’t play nice together, but that’s another story). Version 0.2.0 had snapshots and Docker support. Version 0.3.0 was going to be data disks.

The idea was simple: mount a VHD as a data disk, store your code there, blow away the VM whenever you want. The data persists.

Looked at how VirtualBox and VMware do it. Both support multiple data disks, VHD and VHDX formats. WSL2 has wsl --mount --vhd for mounting VHD files. Should be straightforward, right?

The First Problem: VHD Format

Started implementing. First disk worked - created a VHDX, mounted it, formatted it. Great.

Then I tried VHD format (for VirtualBox compatibility) and hit this:

New-VHD : A parameter cannot be found that matches parameter name 'VHDType'

Wait, what? The PowerShell docs said… oh. The format isn’t determined by a parameter. It’s determined by the file extension. .vhd vs .vhdx. The -VHDType Dynamic parameter doesn’t exist.

Fixed it. Removed the parameter, let the extension do the work. Both formats working.

The Second Problem: Provisioning Ate Everything

Got multiple disks working. Example Vagrantfile had three disks - two default, one persistent. Ran vagrant up.

Checked inside the VM:

ls -la /mnt/

Four data directories. /mnt/data1, /mnt/data2, /mnt/data3, /mnt/data4.

What? I only configured three disks.

The provisioning script was mounting every /dev/sd[b-z] device it found. Turns out WSL2 has some system disks (sda-sdd), and then our data disks start at sde. My script was finding an extra disk somewhere and mounting it.

Quick fix: change the loop to only process /dev/sd[e-z] and limit it to the expected number of disks.

EXPECTED_DISKS=3
disk_count=0
for device in /dev/sd[e-z]; do
  if [$disk_count -ge $EXPECTED_DISKS]; then
    break
  fi
  # ... rest of the mounting logic
done

Now we have exactly three disks. No more, no less.

The Third Problem: Admin Rights

Ran the tests. Green across the board when running as admin. Great.

Then tried vagrant up as a regular user. Boom:

Failed to mount VHD. Administrator privileges are required.

Of course. Both New-VHD (creating VHD files) and wsl --mount (mounting them) need admin rights. That’s… annoying.

But wait. After vagrant halt, if you run vagrant up again as a regular user, does it work?

Tested it. The VM started fine. No errors.

Looked closer. When the VM halts, the VHD files stay mounted at the host level (the /dev/sde, /dev/sdf devices are still there). When the VM starts again, those devices are already present. No need to re-mount. No need for admin rights.

Added a check: before trying to mount, count how many /dev/sd[e-z] devices are already in the distribution. If we have enough, skip the mounting step entirely.

def data_disk_already_mounted?(expected_disk_count)
  result = Vagrant::Util::Subprocess.execute(
    "wsl", "-d", @config.distribution_name, "--", "lsblk", "-nd", "-o", "NAME"
  )
  device_count = result.stdout.lines.count { |line| line.match?(/^sd[e-z]$/) }
  device_count >= expected_disk_count
end

Now the workflow is:

First vagrant up (admin required) - creates and mounts VHDs
vagrant halt - VM stops, VHDs stay mounted
Second vagrant up (no admin required) - disks already there, just start the VM

Perfect for my use case. You only need admin once to set things up.

The Fourth Problem: Integration Tests

Integration tests need admin rights too. But what if someone runs the test suite without admin?

Added a check at the start of the data disk test:

$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $isAdmin) {
    Write-Host "=== $TestName Test SKIPPED ===" -ForegroundColor Yellow
    Write-Host "Reason: Administrator privileges required for data disk tests"
    exit 0
}

Now the test gracefully skips instead of failing with cryptic errors.

What Actually Works Now

Version 0.3.0 ships with:

Multiple data disks per VM:

wsl.data_disk do |disk|
  disk.size = 10
  disk.format = 'vhdx'
end

wsl.data_disk do |disk|
  disk.size = 5
  disk.format = 'vhd'
end

wsl.data_disk do |disk|
  disk.path = '../persistent-data.vhdx' # Custom path, survives destroy
end

Smart mounting:

Checks if disks are already accessible before trying to mount
Skips admin-requiring operations when possible
Clear error messages when admin is actually needed

Persistence:

Default disks (in .vagrant/ directory) get cleaned up on vagrant destroy
Custom-path disks survive destroy - your data is safe
After destroy/up cycle, data on the persistent disk is intact

Testing:

Integration tests verify all scenarios
Graceful skip when admin rights aren’t available
Tests cover VHD/VHDX formats, persistence, cleanup

PowerShell Integration Tests

Since this is Windows-only functionality, I wrote PowerShell-based integration tests. Each test creates a real Vagrant environment, performs operations, and verifies the results.

The data disk test verifies:

# Test 1: Creating VM with data disks
vagrant up --provider=wsl2

# Test 2: Verifying VHD files exist
# Checks for 2 default + 1 persistent disk

# Test 3-6: Mount verification and data writes
# Writing test data to each disk

# Test 7: VHD cleanup on destroy
vagrant destroy
# Default VHDs should be deleted
# Persistent VHD should survive

# Test 8: VM recreation
vagrant up
# New default disks (clean, no old data)
# Persistent disk retained data

Running the full test suite:

> rake test

Running: test_data_disk.ps1

Test 1: Creating VM with data disks
[PASS] VM created with data disks

Test 2: Verifying VHD files exist
[PASS] All VHD files created (2 default + 1 persistent)
  - data-disk-0.vhdx: 516 MB (default)
  - data-disk-1.vhd: 56.06 MB (default)
  - test-data-disk.vhdx: 740 MB (persistent)

Test 3: Verifying data disks are mounted
[PASS] Data disks are mounted

Test 4-6: Writing data to disks
[PASS] Data written to first disk
[PASS] Data written to second disk
[PASS] Data written to persistent disk

Test 7: Testing VHD cleanup on destroy
[PASS] Default VHD files cleaned up after destroy
[PASS] Persistent VHD survived destroy

Test 8: Testing VM recreation
[PASS] New default VHD files created on up
[PASS] New default disks are clean (no old data)
[PASS] Persistent disk retained data across destroy/up cycle

=== DataDisk Test PASSED ===

Test Summary
Passed: 6
Failed: 0

OVERALL: PASSED

The tests run the actual Vagrant commands, create real VHD files, mount them in WSL2, write data, destroy the VM, and verify persistence. No mocks. Real integration testing.

Claude: Writing these tests caught several bugs before they shipped. The disk counting issue? Found it during test development. The admin rights check? Added after the test failed on a non-admin console. Integration tests are tedious to write but worth it.

The Real Win

My colleague can now put his working directory on a persistent data disk. The VM is ephemeral. The data isn’t.

VM got corrupted? vagrant destroy && vagrant up. Code is still there.

Want to try a different distro? Switch VMs, mount the same data disk. Code is still there.

Accidentally broke the system? Doesn’t matter. The stuff that matters is on a disk that survives.

This is what I should have built first. Not snapshots, not networking, not fancy features. The ability to separate “the environment” from “the work.”

Because losing code sucks. And it shouldn’t happen just because a VM died.

What’s Next

The data disk support is solid. Next up: actually figuring out networking so VMs can talk to each other. But that can wait.

Right now, my colleague’s code is safe. That’s worth more than any feature.

Code’s at github.com/LeeShan87/vagrant-wsl2-provider. Version 0.3.0 is tagged and ready. Admin rights required for setup, but after that you’re good.

Try it. Mount your code on a persistent disk. Stop worrying about losing work.

Publishing My First Vagrant Plugin - v0.2.0 Goes Live

Zoltan Toma — Thu, 30 Oct 2025 00:00:00 +0000

One Star and a Decision

So the Vagrant WSL2 Provider got its first GitHub star. From someone I don’t know. Just one random person finding the project useful enough to click that button.

That’s when I realized - okay, maybe it’s time to actually publish this properly.

Until now, this was just a tool I built for myself and my team. We needed to migrate from VirtualBox to WSL2, and Vagrant’s existing providers didn’t cut it. So I built one. It worked. We used it. End of story.

But that star made me think - if someone else is interested, maybe I should make it actually installable. Not just “clone the repo and build it yourself” but proper vagrant plugin install support.

The Publishing Process

I’ve never published a Vagrant plugin before. Hell, I’ve never published anything to RubyGems.org. So naturally, I asked Claude what the process looks like.

Turns out it’s surprisingly simple:

Make sure your gemspec is correct
Update the CHANGELOG
Register on RubyGems.org
Build the gem
Push it

No approval process. No waiting. No HashiCorp permission needed. Just build and push.

Gemspec Cleanup

The gemspec needed a few tweaks. Nothing major - just adding required_ruby_version to avoid warnings:

spec.required_ruby_version = ">= 2.7.0"

Vagrant 2.2+ needs Ruby 2.7+ anyway, so this is safe.

The metadata was already good:

spec.metadata["allowed_push_host"] = "https://rubygems.org"
spec.metadata["homepage_uri"] = spec.homepage
spec.metadata["source_code_uri"] = spec.homepage
spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"

CHANGELOG for v0.2.0

Updated the CHANGELOG to move everything from [Unreleased] to [0.2.0]:

## [0.2.0] - 2025-10-30

### Added
- Full snapshot support (save, restore, list, delete)
- Support for `vagrant snapshot push/pop` commands
- `vagrant ssh -c` command execution support
- PowerShell-based integration test suite
- Docker support and systemd enablement on distribution start
- Comprehensive testing for various Linux distributions
- wsl.conf configuration support

### Features
- Snapshots stored as `.tar` files
- Complete distribution state preservation and restoration
- Direct command execution via `vagrant ssh -c`
- Automated integration tests
- Docker-in-WSL2 workflows with systemd support

This is a solid release. Snapshot support was the big one - being able to save/restore WSL2 distribution state is huge for development workflows.

RubyGems.org Registration

Went to rubygems.org, signed up. Email, password, done.

And yes, I typo’d my username. Classic. But turns out it doesn’t matter - gem ownership is tied to email, not username. You can rename your profile anytime.

The Push

gem build vagrant-wsl2-provider.gemspec

Got some warnings about URIs being the same (not a problem) and the Ruby version constraint (already fixed). Build succeeded:

Successfully built RubyGem
Name: vagrant-wsl2-provider
Version: 0.2.0

Then the moment of truth:

gem push vagrant-wsl2-provider-0.2.0.gem

First time, so it asked for credentials. Email and password. Then:

Pushing gem to https://rubygems.org...
Successfully registered gem: vagrant-wsl2-provider (0.2.0)

Done. Published. Live.

Now anyone can run:

vagrant plugin install vagrant-wsl2-provider

And it just works.

Adding a Roadmap

While we were at it, we added a roadmap to the README. People should know what’s coming:

v0.3 - Data Disk Support

Mount VirtualBox data disks in WSL2
VHD/VMDK to WSL2 format conversion
Support for development backup workflows

This is the next big thing. Our team has development environments backed up as VirtualBox data disks. We need a way to convert and mount those in WSL2. That’s the migration path.

v0.4 - Legacy Distribution Support

Non-interactive setup for Ubuntu 20.04, 22.04
Support for Oracle Linux distributions

Some WSL distributions use the legacy registration system and require interactive setup. Need to work around that.

v0.5 - Network Configuration

Fixed network support for multiple WSL2 distributions
Network isolation and custom IP configuration

WSL2’s dynamic networking is… interesting. Multiple distributions with predictable networking would be nice.

What This Means

The plugin is now officially public and installable. Version 0.2.0 is solid - snapshot support, SSH command execution, Docker/systemd integration, and comprehensive testing across multiple Linux distributions.

It went from “internal tool” to “published open-source project” in about an hour. RubyGems makes it stupidly easy to publish.

Next up: v0.3 and that VirtualBox data disk conversion. That’s the real migration blocker for our team.

But for now - we’re live. The plugin is out there. And hopefully that one star becomes a few more.

Try It

If you’re on Windows with WSL2 and use Vagrant:

vagrant plugin install vagrant-wsl2-provider

Then create a Vagrantfile:

Vagrant.configure("2") do |config|
  config.vm.box = "Ubuntu-24.04"

  config.vm.provider "wsl2" do |wsl|
    wsl.distribution_name = "my-dev-env"
  end
end

Run:

vagrant up --provider=wsl2
vagrant snapshot save clean-install
vagrant ssh

And you’ve got a WSL2-based Vagrant environment with snapshot support.

Repo: github.com/LeeShan87/vagrant-wsl2-provider

Building Docker Support for Vagrant WSL2 Provider - A Development Journey

Zoltan Toma — Sun, 05 Oct 2025 00:00:00 +0000

Introduction

Over the past few days, I’ve been working on adding Docker support to the vagrant-wsl2-provider plugin. This turned out to be more challenging than expected, but the journey taught me a lot about WSL2’s internals, systemd initialization, and multi-distribution package management.

In this post, I’ll walk through the development process, the challenges we faced, and how we solved them to get Docker running on 8 different Linux distributions in WSL2 through Vagrant.

The Challenge: Docker Needs systemd

The first major hurdle was enabling systemd support in WSL2 distributions. Docker relies on systemd to manage the container daemon, but WSL2 doesn’t enable systemd by default. This is controlled by the /etc/wsl.conf file, which must be created and configured before systemd will start.

Implementing wsl.conf Support

We needed a clean API for users to configure WSL2 distributions. After some experimentation, we settled on a dotted syntax that feels natural:

config.vm.provider "wsl2" do |wsl|
  wsl.systemd = true # Enable systemd
  wsl.default_user = "vagrant" # Set default user
  wsl.hostname = "my-docker-vm" # Set hostname

  # Or use the longer form for advanced options:
  wsl.wsl_conf.boot.command = "service docker start"
  wsl.wsl_conf.network.generate_hosts = false
end

Under the hood, this generates a proper /etc/wsl.conf file:

[boot]
systemd=true

[user]
default=vagrant

[network]
hostname=my-docker-vm

The Restart Problem

Here’s where things got tricky. After writing the wsl.conf file, the distribution must be fully restarted for systemd to initialize. A simple wsl --terminate wasn’t enough - we needed wsl --shutdown, which stops all WSL2 distributions and restarts the entire WSL2 backend.

Initially, I overthought this and added complex systemd polling logic:

# Over-engineered version (don't do this!)
halt
start
sleep 5
max_retries = 30
retry_count = 0
loop do
  result = check_systemd_status
  break if result == "running"
  retry_count += 1
  sleep 1
end

But it turned out we only needed:

# Simple and effective
Vagrant::Util::Subprocess.execute("wsl", "--shutdown")
sleep 2
start

The real issue wasn’t systemd initialization time - it was missing the iptables package!

The Missing iptables Mystery

After getting systemd running, Docker still failed to start with a cryptic error:

failed to start daemon: Error initializing network controller:
failed to register "bridge" driver: failed to create NAT chain DOCKER:
iptables not found

Interestingly, running vagrant reload after the initial vagrant up would make Docker work perfectly. This led us down a rabbit hole trying to fix the “restart problem” when the real issue was simple: iptables wasn’t installed.

Adding iptables to the package list solved it immediately:

- name: Install required packages
  apt:
    name:
      - ca-certificates
      - curl
      - gnupg
      - iptables # This was the missing piece!
    state: present

Multi-Distribution Support: The Right Way

Initially, we tried cramming all distribution support into a single Ansible playbook with numerous conditionals:

- name: Install Docker
  package:
    name: "{{ 'moby-engine' if ansible_os_family == 'Debian' else 'docker' }}"
  when: # complex conditions...

This quickly became unmaintainable. We refactored to use OS-family-specific playbooks :

provisioning/
├── docker-debian.yml # Ubuntu, Debian, Kali (Moby)
├── docker-redhat.yml # AlmaLinux, Fedora (Podman)
└── docker-suse.yml # openSUSE (Docker)

The Vagrantfile automatically selects the right playbook:

playbook = case distro
           when /Ubuntu|Debian|kali/i then "provisioning/docker-debian.yml"
           when /AlmaLinux|Fedora/i then "provisioning/docker-redhat.yml"
           when /openSUSE/i then "provisioning/docker-suse.yml"
           end

node.vm.provision "ansible_local" do |ansible|
  ansible.playbook = playbook
end

Much cleaner! Each playbook focuses on one OS family without conditional spaghetti.

Why Microsoft Moby for Ubuntu?

You might wonder why we use Microsoft’s Moby packages for Ubuntu instead of the standard docker.io:

# Ubuntu: Microsoft Moby
- name: Install Moby Docker
  apt:
    name:
      - moby-engine
      - moby-cli
      - moby-containerd
      - moby-runc

# Debian/Kali: Standard docker.io
- name: Install Docker
  apt:
    name:
      - docker.io
      - containerd

The reason is Docker Desktop licensing. Some enterprises are cautious about using docker.io in WSL2 because of Docker Desktop’s commercial licensing restrictions on Windows. While this likely only applies to the GUI (not the engine itself), using Microsoft’s Moby distribution provides a clearer licensing path for commercial use.

For Debian and Kali, we fall back to docker.io since Microsoft doesn’t provide Moby packages for all Debian versions.

RedHat Family: Podman as Docker

On AlmaLinux and Fedora, installing the docker package actually gives you Podman with Docker CLI compatibility:

- name: Install Podman (Docker compatible)
  dnf:
    name:
      - podman
      - podman-docker # Provides 'docker' command

This is RedHat’s preferred approach - Podman is daemonless and rootless by default, which is more secure. The podman-docker package provides a docker symlink, so users can run docker run hello-world and it “just works” using Podman under the hood.

Testing Across 8 Distributions

The final test suite provisions Docker on 8 different Linux distributions:

$ vagrant status
docker-almalinux8 running (wsl2)
docker-almalinux9 running (wsl2)
docker-debian running (wsl2)
docker-fedoralinux42 running (wsl2)
docker-ubuntu running (wsl2)
docker-ubuntu2404 running (wsl2)
docker-kalilinux running (wsl2)
docker-opensusetumbleweed running (wsl2)

Each one successfully runs the hello-world container:

$ vagrant ssh docker-ubuntu2404 -c "docker run hello-world"

Hello from Docker!
This message shows that your installation appears to be working correctly.

What’s Next for v0.2.0

Docker support is just the beginning. Here are additional features planned for the v0.2.0 release:

WSL Mount Support

Enable mounting Windows directories and VHD/VHDX data disks:

config.vm.provider "wsl2" do |wsl|
  wsl.mount "D:\\data", "/mnt/data"
  wsl.attach_vhdx "D:\\backups\\linux-data.vhdx"
end

This will allow users to:

Share data between Windows and WSL2
Back up Linux data to portable VHDX files
Separate system and data for easier snapshots

Vagrant Snapshot Support

Implement Vagrant’s snapshot functionality:

vagrant snapshot save docker-vm baseline
vagrant snapshot restore docker-vm baseline
vagrant snapshot list

This will leverage WSL2’s export/import functionality to create point-in-time snapshots of entire distributions.

Lessons Learned

Start simple - My complex systemd polling was unnecessary. The real issue was a missing package.
Test early, test often - Running vagrant destroy && vagrant up repeatedly helped identify the iptables issue that only appeared on fresh installations.
Separate concerns - OS-specific playbooks are much easier to maintain than one giant conditional playbook.
Read error messages carefully - “iptables not found” was right there in the logs, but I focused on the wrong problem initially.
WSL2 is not a VM - It has unique behaviors (like needing wsl --shutdown for systemd) that require understanding its architecture.

Try It Yourself

The vagrant-wsl2-provider with Docker support is available on GitHub:

git clone https://github.com/LeeShan87/vagrant-wsl2-provider.git
cd vagrant-wsl2-provider/test/docker-test
vagrant up docker-ubuntu2404
vagrant ssh docker-ubuntu2404 -c "docker run hello-world"

Conclusion

Adding Docker support to the Vagrant WSL2 provider was a journey through WSL2 internals, systemd initialization, and cross-distribution package management. The final solution is elegant: a simple configuration API, clean OS-specific playbooks, and reliable Docker/Podman installation across 8 Linux distributions.

The v0.2.0 release will bring even more functionality with VHD mounting and snapshot support. Stay tuned!

Have questions or suggestions? Open an issue on GitHub or reach out!

Snapshots and Testing: Building Real Tests for a Vagrant Provider

Zoltan Toma — Sun, 05 Oct 2025 00:00:00 +0000

The Testing Problem Nobody Talks About

After getting Docker support working, I wanted to add snapshot functionality to the vagrant-wsl2-provider. But there was a nagging problem I’d been avoiding: how do you actually test a Vagrant provider plugin?

The “proper” way would be to write Ruby unit tests with RSpec, mock all of Vagrant’s internals, and test each component in isolation. But here’s the thing - Vagrant is a massive gem with heavy dependencies. Just getting the test environment set up requires pulling in the entire Vagrant gem, which then requires native extensions, specific Ruby versions, and a whole dependency chain that’s… painful.

I tried. I really did. Created a spec/ directory, added RSpec, started writing tests. Got errors about missing Vagrant classes. Added Vagrant as a dev dependency. Got compilation errors for native extensions. Spent an hour on dependency hell before I stopped and asked myself: what am I actually trying to test here?

Integration Tests: The Pragmatic Choice

I don’t care if my Driver class can be instantiated in isolation. I care if vagrant snapshot save actually works when a user runs it. I care if vagrant ssh -c "command" returns output. I care if vagrant up creates a working WSL2 distribution.

So I made a decision that probably horrifies some people: PowerShell-based integration tests.

# test/integration/test_basic.ps1
vagrant up --provider=wsl2
if ($LASTEXITCODE -eq 0) {
    Write-Host "[PASS] vagrant up succeeded" -ForegroundColor Green
} else {
    throw "vagrant up failed"
}

Dead simple. No mocks. No stubs. Just run the actual command and check if it works.

Why This Makes Sense

Tests real behavior - What users actually experience
No mocking infrastructure - No dependency on Vagrant’s internal APIs
Fast to write - PowerShell is native to Windows where WSL2 runs
Easy to debug - When a test fails, you can literally copy-paste the command
No Ruby dependency hell - Just PowerShell and Vagrant installed

The test suite structure is straightforward:

test/integration/
├── test_basic.ps1 # vagrant up, status, ssh, destroy
├── test_snapshot.ps1 # snapshot lifecycle
└── run_all_tests.ps1 # runs everything

Run it with rake test. That’s it.

The Snapshot Implementation

WSL2 already has everything we need for snapshots: wsl --export and wsl --import. The challenge was wrapping this in Vagrant’s provider capability system.

Driver Methods

The Driver class handles the actual WSL2 operations:

def save_snapshot(snapshot_name)
  snapshot_file = snapshot_path(snapshot_name)

  @machine.ui.info "Saving snapshot: #{snapshot_name}"
  execute("wsl", "--export", @config.distribution_name, snapshot_file)
  @machine.ui.success "Snapshot saved: #{snapshot_name}"
end

def restore_snapshot(snapshot_name)
  snapshot_file = snapshot_path(snapshot_name)

  # Unregister current distribution
  halt if state == :running
  execute("wsl", "--unregister", @config.distribution_name)

  # Import the snapshot
  dist_dir = distribution_path
  execute("wsl", "--import", @config.distribution_name,
          dist_dir, snapshot_file, "--version", @config.version.to_s)
end

Snapshots are just tar files stored in .vagrant/machines/{name}/wsl2/snapshots/. Nothing fancy, which is exactly what we want.

Provider Capabilities

Vagrant expects providers to register capabilities for snapshot operations:

# lib/vagrant-wsl2-provider/plugin.rb
provider_capability "wsl2", "snapshot_list" do
  require_relative "cap/snapshot_list"
  Cap::SnapshotList
end

provider_capability "wsl2", "snapshot_save" do
  require_relative "cap/snapshot_save"
  Cap::SnapshotSave
end

Each capability is just a thin wrapper that calls the driver:

# lib/vagrant-wsl2-provider/cap/snapshot_save.rb
module VagrantPlugins
  module WSL2
    module Cap
      class SnapshotSave
        def self.snapshot_save(machine, snapshot_name)
          driver = machine.provider.instance_variable_get(:@driver)
          driver.save_snapshot(snapshot_name)
        end
      end
    end
  end
end

This gives us full Vagrant snapshot support:

vagrant snapshot save before-experiment
vagrant snapshot restore before-experiment
vagrant snapshot list
vagrant snapshot delete old-snapshot

# Bonus: push/pop work automatically!
vagrant snapshot push
vagrant snapshot pop

The `vagrant ssh -c` Rabbit Hole

While testing snapshots, I noticed vagrant ssh -c "echo test" would execute successfully (exit code 0) but show no output. This was… not great.

The problem was that Vagrant’s built-in SSHRun action wasn’t compatible with the WSL2 communicator. It expected SSH-style communication, but we use direct WSL command execution.

Custom SSHRun Action

The solution was a custom action that properly streams output:

# lib/vagrant-wsl2-provider/action/ssh_run.rb
def call(env)
  command = env[:ssh_run_command]

  if command
    exit_status = env[:machine].communicate.execute(command, error_check: false) do |type, data|
      case type
      when :stdout
        $stdout.print(data)
        $stdout.flush
      when :stderr
        $stderr.print(data)
        $stderr.flush
      end
    end

    env[:ssh_run_exit_status] = exit_status
  end

  @app.call(env)
end

But this required updating the communicator to accept a block parameter:

# lib/vagrant-wsl2-provider/communicator.rb
def execute(command, opts = {}, &block)
  result = Vagrant::Util::Subprocess.execute(
    "wsl", "-d", distribution_name, "-u", "vagrant", "--",
    "bash", "-l", "-c", encoded_command,
    :notify => [:stdin, :stdout, :stderr]
  ) do |type, data|
    # Call the block if provided
    block.call(type, data) if block_given?

    # Default output handling
    puts data if type == :stdout && !block_given?
  end
end

Now vagrant ssh -c works as expected:

$ vagrant ssh -c "uname -a"
Linux vagrant-wsl2-basic 5.15.133.1-microsoft-standard-WSL2 ...

$ vagrant ssh -c "docker ps"
CONTAINER ID IMAGE COMMAND ...

Perfect for scripting!

WSL2 Output Encoding Hell

One weird issue that bit me during testing: WSL commands on Windows return text with null bytes (\0) scattered throughout. This breaks PowerShell’s string matching.

# This doesn't work
$wslList = wsl -l -v
if ($wslList -match "vagrant-wsl2-basic") { # Never matches!

The fix is to strip null bytes:

# This works
$wslList = (wsl -l -v | Out-String) -replace '\0', ''
if ($wslList -match "vagrant-wsl2-basic") { # Works!

This is now documented in the test template so future tests don’t hit this.

Test Infrastructure as Documentation

The test/ directory felt wrong. These weren’t just tests - they were working examples. So I renamed it to examples/:

examples/
├── basic/ # Minimal Vagrantfile
├── snapshot/ # Snapshot demo
├── provisioners/ # Shell/file/ansible examples
├── docker-test/ # Docker with systemd
└── test-distros/ # Various Linux distributions

Each directory has a working Vagrantfile that serves three purposes:

User documentation - “Here’s how to use feature X”
Integration test fixture - Tests use these examples
Manual testing - Quick vagrant up to try something

The integration tests just reference these examples:

$ExampleDir = Join-Path $PSScriptRoot "..\..\examples\snapshot"
Push-Location $ExampleDir

vagrant up --provider=wsl2
vagrant snapshot save test-snapshot
vagrant snapshot restore test-snapshot

No duplication. The docs and tests stay in sync automatically.

Test Results

The test suite validates:

Basic lifecycle: up, status, ssh-config, destroy
WSL distribution creation and cleanup
SSH command execution with output
Snapshot save/restore/list/delete
Snapshot push/pop (auto-generated names)

Current status:

========================================
Test Summary
========================================
Passed: 2
Failed: 0

OVERALL: PASSED

Not a huge test suite, but it covers the core workflows users actually care about.

Lessons Learned

1. Integration tests > Unit tests for infrastructure tools

When you’re wrapping external commands (WSL, Docker, systemd), integration tests give you more confidence. Mock-heavy unit tests just test your mocks.

2. Use the platform’s native tools

PowerShell on Windows is fine. Don’t fight it by trying to force Ruby/RSpec everywhere.

3. Examples should be runnable

If your documentation includes code, make it actual working code that’s tested. “Docs that lie” is worse than no docs.

4. Block parameters are powerful

Ruby blocks for streaming callbacks are elegant. Don’t be afraid to use them.

5. Exit codes matter

Always check $LASTEXITCODE in PowerShell. A command can “succeed” but do nothing.

What’s Next

With snapshots and testing infrastructure in place, v0.2.0 is almost ready. The last major feature is WSL mount support for VHD/VHDX data disks, but that’s for the next iteration.

For now, I’m happy that:

Snapshots work reliably
vagrant ssh -c returns output
Tests actually test real behavior
The code is properly documented

Not bad for a plugin nobody asked for that I’m building because I’m stuck on Windows. 😄

Try It Out

The snapshot support is now merged into main:

git clone https://github.com/LeeShan87/vagrant-wsl2-provider.git
cd vagrant-wsl2-provider
rake install_local

cd examples/snapshot
vagrant up --provider=wsl2
vagrant snapshot save clean
# ... experiment ...
vagrant snapshot restore clean

Run the tests:

rake test # All tests
rake test_basic # Just basic functionality
rake test_snapshot # Just snapshot tests

Questions? Open an issue on GitHub. I’m always curious how people are (or aren’t) using this thing.

Building a Vagrant WSL2 Provider: Testing Journey and Unexpected Discoveries

Zoltan Toma — Mon, 29 Sep 2025 00:00:00 +0000

The Final Push to v0.1.0

After testing the provider on my corporate machine, I discovered a bug related to the missing Windows HOME environment variable. The provider was trying to cache files on a NAS drive (mapped as U:) instead of the local user directory. After fixing this by switching to Vagrant.user_data_path, I felt confident that v0.1.0 was nearly ready.

All that remained was a comprehensive test run across all available WSL distributions.

The –name Flag Mystery

While reading through the WSL help documentation, I noticed the –name flag for wsl –install. I was puzzled - what’s the point of this flag?

I had a distant memory from years ago: WSL would reuse existing VM disks when creating multiple instances. If you didn’t create a clean snapshot immediately after installation, the second VM would inherit changes from the first one. This was exactly why my provider prevents creating distributions from already-in-use WSL instances.

But if that’s true, what does the –name flag actually do?

Testing the –name Flag

Time to test this assumption. I created two Ubuntu 24.04 instances:

# First instance
wsl --install Ubuntu-24.04 --name Ubuntu-First --no-launch
wsl -d Ubuntu-First bash -c "echo 'Test file from first' > ~/testfile.txt"

# Second instance
wsl --install Ubuntu-24.04 --name Ubuntu-Second --no-launch
wsl -d Ubuntu-Second bash -c "ls -la ~/"

Result: The second instance was completely empty. No testfile.txt. Each instance has its own independent virtual disk.

Wow… I remembered wrong?

When Did This Flag Appear?

A quick search revealed the –name flag was added to WSL around 2023 (version 2.4.4), documented in microsoft/WSL#9210. The last time I worked extensively with WSL was around 2021-2022, when this flag didn’t exist yet - and Ubuntu 24.04 wasn’t available either.

Testing Legacy Distributions

But wait - what about older distributions like Ubuntu 20.04 and 22.04?

wsl --install Ubuntu-20.04 --name Ubuntu2004-Test --no-launch
# Result: Installation completes but distribution doesn't appear in wsl -l

wsl --install Ubuntu-20.04 # Interactive installation
# Now it appears in wsl -l

Discovery: Legacy distributions (Ubuntu 20.04/22.04, Oracle Linux) don’t properly register with the –no-launch flag. They require interactive setup with username/password prompts. Only modern distributions support the new registration system.

So I was right - but only for legacy distributions!

The Real Purpose: Caching

Even for modern distributions with the –name flag, there’s still value in caching. While each named instance creates an independent VM, the installation always downloads from the Microsoft Store.

My provider’s clean distribution cache speeds this up significantly - instead of repeated downloads, it creates one clean tar file locally and imports it with different names. Much faster for creating multiple instances.

The Great Multi-Distribution Test

Now for the marathon: testing all available WSL distributions with shell, file, and Ansible provisioners.

Success Stories

8 distributions working flawlessly:

AlmaLinux-8, AlmaLinux-9
Debian
FedoraLinux-42
Ubuntu, Ubuntu-24.04
Kali-Linux
openSUSE-Tumbleweed

The Problem Children

Legacy Distributions:

Ubuntu-20.04, Ubuntu-22.04
OracleLinux (all versions: 7.9, 8.10, 9.5)
Issue: –no-launch flag doesn’t register them properly
Require interactive setup (username/password)

Guest Detection Failures:

SUSE-Linux-Enterprise-15-SP6/SP7
Error: “The guest operating system of the machine could not be detected!”
File provisioner fails without guest capability

Bleeding Edge:

AlmaLinux-10, AlmaLinux-Kitten-10
Ansible provisioner fails: EPEL repositories don’t exist yet for these versions
Error: curl: (22) The requested URL returned error: 404 for EPEL

Minimal Distributions:

archlinux
Missing sudo by default - Ansible provisioner fails
Would need pacman -Sy –noconfirm sudo pre-provisioning

Shared Folder Issues:

openSUSE-Leap-15.6
Silent failure creating shared folders

v0.1.0: Good Enough for a PoC

I think this is sufficient for a proof-of-concept v0.1.0 release.

Working Features:

Create and manage WSL2 distributions through Vagrant
Standard commands: up, status, halt, destroy, ssh
Provisioners: shell, file, ansible_local
Synced folders
Clean distribution caching for faster deployment
8 tested and working distributions

Still Untested:

CPU and memory limit configuration
Docker installation and container execution
Snapshot creation and restore
Network configuration
GUI application support (WSLg)

These would be good scope for v0.2.

Not Production-Ready, But a Solid Foundation

I wouldn’t recommend this for production yet, but it’s already a solid starting point for developers who need Vagrant-like workflows on WSL2.

Why Build This?

I’ll be honest: I’m not a fan of Microsoft-centric solutions. I’m building this plugin because developers - myself included - are increasingly forced to use WSL on Windows. Corporate environments, client requirements, and the Windows ecosystem all push us in this direction.

My hope is that this provider offers a smoother transition path for developers who find themselves in this situation. If you’re used to Vagrant workflows with VirtualBox or VMware, but now need to work with WSL2, this plugin aims to make that transition less painful.

The code is available on GitHub at https://github.com/LeeShan87/vagrant-wsl2-provider. Contributions, bug reports, and feedback welcome.

What’s Next?

v0.2 roadmap:

VirtualBox VM import support (convert existing Vagrant boxes to WSL2)
Resource limit testing (CPU/memory)
Docker-in-WSL2 workflows
Snapshot/restore functionality
Better error handling for legacy distributions

Stay tuned!

Building a Vagrant WSL2 Provider: Clean Development Environments on Windows

Zoltan Toma — Sat, 27 Sep 2025 00:00:00 +0000

Building a Vagrant WSL2 Provider: Clean Development Environments on Windows

Working with development environments on Windows has always been a challenge. While VirtualBox and VMware provide excellent virtualization, they come with resource overhead and performance penalties. Windows Subsystem for Linux 2 (WSL2) offers a compelling alternative with near-native performance, but lacks the standardized workflow that Vagrant provides.

This led me to an interesting project: building a custom Vagrant provider for WSL2 that combines the best of both worlds - the familiar Vagrant workflow with WSL2’s performance benefits.

The Challenge

While traditional virtualization solutions like VirtualBox and VMware remain excellent choices for development, many enterprise Windows environments face significant constraints that make WSL2 the only viable high-performance option.

Enterprise Windows Constraints

Modern corporate Windows deployments often enforce security policies that create development challenges:

Virtualization-Based Security (VBS) - When enabled, VirtualBox becomes unusable or extremely slow
Device Guard/Credential Guard - Prevents traditional hypervisors from accessing hardware virtualization features
Nested virtualization overhead - VMware Workstation suffers significant performance penalties under Hyper-V
Security compliance - Many organizations require these security features, leaving no choice

This creates a forced migration scenario where developers lose access to their familiar Vagrant + VirtualBox/VMware workflows, precisely when they need reproducible development environments most.

WSL2 Technical Challenges

Beyond enterprise constraints, WSL2 distributions behave differently from traditional VMs:

No persistent “running” state - WSL2 distributions automatically sleep when no processes are active
No built-in SSH server - WSL2 uses direct command execution instead of SSH
Different lifecycle management - WSL2 uses wsl.exe commands rather than hypervisor APIs
Contamination risk - Existing WSL2 distributions may have modifications that break reproducibility

The Gap

This leaves Windows enterprise developers in a difficult position: they need the performance and compatibility of WSL2 but lose the standardized workflows and tooling ecosystem that Vagrant provides. The WSL2 provider bridges this gap, restoring familiar development workflows in constrained environments.

Architecture Overview

The WSL2 provider follows Vagrant’s plugin architecture with several key components:

Core Components

Plugin Registration (plugin.rb) - Registers the provider and communicator with Vagrant
Provider Implementation (provider.rb) - Implements Vagrant’s provider interface with WSL2-specific actions
Custom Communicator (communicator.rb) - Handles command execution using native WSL commands instead of SSH
Action Classes - Handle create, destroy, halt, start, and provisioning operations
Configuration (config.rb) - WSL2-specific configuration options

Clean Base Distribution Cache

One of the most critical features is the clean base distribution cache system :

# Check if we have a clean cached version
cached_tar_path = File.join(cache_dir, "#{clean_base_name}.tar")

unless File.exist?(cached_tar_path)
  # Check if the original distribution already exists (dirty)
  if wsl_distribution_installed?(box_name)
    raise Errors::DirtyDistributionExists,
          name: box_name,
          clean_name: clean_base_name,
          cache_path: cache_dir
  end

  # Create clean base distribution
  create_clean_base_distribution(env, box_name, clean_base_name, cached_tar_path, cache_dir)
end

This ensures every vagrant up starts with a pristine environment by:

Detecting dirty distributions - Fails if base distribution already exists with modifications
Creating clean cache - Fresh install → export → cache → remove original
Project isolation - Each project gets its own distribution from clean cache

WSL2 Distribution Lifecycle

WSL2 distributions behave differently from traditional VMs:

### Vagrant Status Meanings
- `stopped` = Distribution exists, no active processes (ready to use)
- `running` = Distribution has active processes
- `not created` = Distribution doesn't exist

### Typical Workflow
vagrant up --provider=wsl2 # Creates distribution (shows "stopped")
vagrant ssh # Starts shell (shows "running")
exit # Shell closes (returns to "stopped")
vagrant status # Shows "stopped" - this is normal!

This automatic sleep behavior is actually beneficial:

Resource efficient - No idle processes consuming memory
Instant wake - Commands execute immediately from “stopped” state
Same experience - vagrant ssh works regardless of state

Native WSL2 Communication

Instead of setting up SSH servers, the provider uses a custom communicator that executes commands directly through WSL:

def execute(command, opts = {})
  distribution_name = @machine.id

  result = Vagrant::Util::Subprocess.execute(
    "wsl", "-d", distribution_name, "-u", "vagrant", "--",
    "bash", "-l", "-c", command
  )

  result.exit_code
end

This provides:

Better performance - No SSH overhead
Native integration - Direct WSL command execution
Simpler setup - No SSH key management required

Vagrant User Setup

For full Vagrant ecosystem compatibility, the provider automatically sets up a standard vagrant user:

def setup_vagrant_user(distribution_name)
  run_in_distribution(distribution_name, [
    "useradd -m -s /bin/bash vagrant",
    "echo 'vagrant:vagrant' | chpasswd",
    "usermod -aG sudo vagrant",
    "echo 'vagrant ALL=(ALL) NOPASSWD:ALL' | tee /etc/sudoers.d/vagrant"
  ])
end

This ensures compatibility with:

Ansible provisioners - Expect vagrant user with sudo access
Shell provisioners - Run as vagrant user by default
Shared folders - Mount to /home/vagrant directory
SSH forwarding - Uses vagrant user’s home directory

Provisioning Support

The provider supports full Vagrant provisioning through the custom communicator:

config.vm.provision "shell", inline: <<-SHELL
  echo "Hello from WSL2 Vagrant provider!"
  apt-get update
  apt-get install -y nginx
SHELL

The provisioning workflow:

Script upload - Vagrant uploads script to /tmp/vagrant-shell
Permission setup - Makes script executable and sets ownership
Execution - Runs script as vagrant user with sudo access
Cleanup - Removes temporary files

Key Benefits

For Developers

Familiar workflow - Same Vagrant commands across platforms
Platform flexibility - Easy switching between VM and WSL2
Reduced resource usage - WSL2 uses fewer system resources than VMs
Corporate environment friendly - WSL2 alternative when VMs are restricted

For Teams

Consistent environments - Same configuration across team members
Platform choice - Teams can choose VM vs WSL2 per member preference
Simplified onboarding - Single setup process regardless of platform
Clean, reproducible environments - Every vagrant up starts fresh

When to Use This Provider

✅ Ideal Use Cases

Enterprise Windows environments with VBS/Device Guard requirements
Security-constrained environments where traditional virtualization is blocked
Resource-limited machines where VMs are too heavy
Mixed teams with both Windows and Linux/macOS developers
Existing Vagrant workflows that need to work on WSL2

⚠️ Consider Alternatives When

You have full OS choice - Native Linux development is still superior
VirtualBox/VMware work fine - Traditional virtualization offers better isolation
Heavy virtualization needs - Multiple concurrent VMs, complex networking
Kernel development - Need direct hardware access
Windows-specific development - Native Windows tooling might be more appropriate

🎯 Sweet Spot

This provider excels in enterprise Windows environments where developers need Linux-compatible development workflows but are constrained by corporate security policies. It’s not necessarily the best development environment overall, but it’s often the best available option in Windows-centric organizations.

Current Status

The provider successfully implements:

✅ Core Vagrant workflow - vagrant up/halt/destroy/ssh/status✅ Clean base distribution cache - Prevents environment contamination ✅ Native WSL2 communication - Direct command execution without SSH ✅ Vagrant user setup - Full ecosystem compatibility ✅ Shell provisioning - Native WSL command execution ✅ Smart default handling - Respects user’s existing WSL configuration

What’s Next

Future development will focus on:

Ansible provisioner support - Testing and optimization for ansible_local
Shared folders implementation - Project directory mounting
Network configuration - Port forwarding and advanced networking
Box conversion pipeline - VirtualBox → WSL2 automatic conversion
Multi-machine support - Multiple WSL2 distributions per project

Conclusion

Building a Vagrant WSL2 provider has been an exciting journey into Vagrant’s plugin architecture and WSL2’s capabilities. The combination provides a powerful development environment solution that bridges the gap between traditional VM-based workflows and modern container-like performance.

The provider demonstrates that with careful architecture and attention to Vagrant’s ecosystem requirements, it’s possible to create native, high-performance alternatives to traditional virtualization while maintaining full compatibility with existing Vagrant workflows and provisioning tools.

For Windows developers seeking reproducible, performant development environments, this WSL2 provider offers a compelling alternative to traditional VM-based solutions.

The vagrant-wsl2-provider project is actively being developed and will be open-sourced once the core features are stable. Stay tuned for the repository announcement!