DEV Community: Ian Packard

Renaming WSL Distributions

Ian Packard — Thu, 19 Feb 2026 00:30:29 +0000

You installed Ubuntu from the Microsoft Store and WSL named it Ubuntu-24.04. You installed another one and got Ubuntu. You imported one from a container and now you have three distributions with names that tell you nothing about what they're for.

Wouldn't it be nice to rename them to something meaningful — DevBox, WebServer, DataScience?

The problem: WSL doesn't have a --rename command. The distribution name is stored in the Windows Registry, and changing it means editing the registry directly. Worse, that name is also referenced by Windows Terminal profiles and Start Menu shortcuts, so renaming isn't just one change — it's several.

How WSL Stores Distribution Names

Each WSL distribution is registered in the Windows Registry under:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\

Inside that path, each distribution has its own subkey identified by a GUID:

Lxss\
  {12345678-abcd-...}\
    DistributionName = "Ubuntu-24.04"
    BasePath = "C:\Users\you\AppData\Local\wsl\..."
    State = 1
    Version = 2

The DistributionName value is what wsl --list shows you. It's also what you use in commands like wsl -d Ubuntu-24.04. Changing this value is the core of a rename operation.

The Manual Approach

Step 1: Find the Distribution's GUID

Open PowerShell and find your distribution's registry key:

Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" |
  ForEach-Object {
    $name = (Get-ItemProperty $_.PSPath).DistributionName
    [PSCustomObject]@{ GUID = $_.PSChildName; Name = $name }
  }

This shows all your distributions and their GUIDs:

GUID                                  Name
----                                  ----
{12345678-abcd-1234-abcd-123456789012} Ubuntu-24.04
{87654321-dcba-4321-dcba-210987654321} Alpine

Step 2: Stop the Distribution

The distribution must be stopped before renaming:

wsl --terminate Ubuntu-24.04

Step 3: Edit the Registry

Open Registry Editor (regedit) and navigate to:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{your-guid}

Double-click DistributionName and change it to your new name.

Or from PowerShell (run as your normal user, not admin):

$guid = "{12345678-abcd-1234-abcd-123456789012}"
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" `
  -Name "DistributionName" -Value "DevBox"

Step 4: Update Windows Terminal

If you use Windows Terminal, it generates profile entries for each WSL distribution. After a registry rename, the Terminal profile still shows the old name.

Windows Terminal stores WSL distribution profiles in a fragment JSON file. The location depends on how Terminal was installed:

Microsoft Store Terminal:

%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\

Preview Terminal:

%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\

You need to update two things:

A. The profile fragment (auto-generated by WSL):

Find the profile matching your distribution's GUID and update the name field.

B. The settings.json file:

Open Terminal's settings.json and find your distribution in the profiles.list array. Update the name field to match:

{
  "profiles": {
    "list": [
      {
        "guid": "{12345678-abcd-1234-abcd-123456789012}",
        "name": "DevBox",
        "source": "Windows.Terminal.Wsl"
      }
    ]
  }
}

The GUID in the Terminal profile matches the GUID in the registry, so you can find the right entry by comparing them (case-insensitive).

Step 5: Rename the Start Menu Shortcut

WSL distributions installed from the Store get a Start Menu shortcut. After renaming, the shortcut still has the old name.

The shortcut is typically at:

%APPDATA%\Microsoft\Windows\Start Menu\Programs\

Find the .lnk file with the old name and rename it to match the new distribution name.

After renaming the file, update the ShortcutPath value in the registry if it exists:

HKCU\...\Lxss\{GUID}\ShortcutPath

Step 6: Verify

Start the distribution with its new name:

wsl -d DevBox

Check Windows Terminal — the profile should now show "DevBox" in the dropdown.

Naming Rules

WSL distribution names have restrictions:

Allowed characters: Letters, numbers, hyphens, underscores, periods
Max length: 64 characters
Cannot start with: A hyphen
Must be unique: Case-insensitive (so "Ubuntu" and "ubuntu" conflict)

Choose names that are meaningful to you. Some patterns that work well:

By purpose: DevBox, WebServer, MLWorkspace
By project: ProjectAlpha, ClientSite, Staging
By distro + purpose: Ubuntu-Dev, Debian-Build, Alpine-Tools

The Easy Way: WSL UI

The manual process is doable but tedious — five separate steps across the registry, Terminal, and file system. Miss one and things are inconsistent.

WSL UI handles all of this with a single rename dialog. Enter the new name and optionally toggle:

Update Windows Terminal profile — updates both the profile fragment and settings.json (both Store and Preview variants)
Rename Start Menu shortcut — renames the .lnk file and updates the registry path

All updates happen atomically. If the Terminal or shortcut update fails (maybe Terminal isn't installed, or the shortcut doesn't exist), the rename still succeeds — those are non-fatal side effects.

The validation is real-time too. As you type, it checks for invalid characters, duplicate names, and length limits before you can submit.

Troubleshooting

"wsl -d NewName" says distribution not found:
Make sure WSL isn't caching the old name. Run wsl --shutdown then try again.

Terminal still shows old name:
Check both the profile fragment JSON and the main settings.json. If you have both Terminal and Terminal Preview installed, both need updating.

Shortcut still shows old name in Start Menu:
The Start Menu may cache the old name. Try unpinning and repinning, or sign out and back in.

Default distribution changed unexpectedly:
If your renamed distro was the default, verify with wsl --list that it's still marked as default. If not, set it again: wsl --set-default DevBox.

Summary

Step	What to Update	Location
Registry	`DistributionName` value	`HKCU\...\Lxss\{GUID}`
Terminal profile	`name` field	Fragment JSON in Terminal LocalState
Terminal settings	`name` in profiles list	`settings.json` in Terminal LocalState
Start Menu	Shortcut filename	`%APPDATA%\...\Start Menu\Programs\`
Registry (shortcut)	`ShortcutPath` value	`HKCU\...\Lxss\{GUID}`

WSL not having a built-in rename command is one of those gaps that's surprisingly annoying in practice. Giving your distributions meaningful names makes everything clearer — from wsl -d DevBox in the terminal to the dropdown in Windows Terminal.

Originally published at https://wsl-ui.octasoft.co.uk/blog/renaming-wsl-distributions

Importing Container Images as WSL Distributions

Ian Packard — Thu, 19 Feb 2026 00:29:50 +0000

Most people install WSL distributions from the Microsoft Store — Ubuntu, Debian, Alpine, the usual suspects. But WSL can run any Linux filesystem. And you know what has a huge catalog of Linux filesystems ready to download? Container registries.

Every Docker image on Docker Hub, GitHub Container Registry, Quay.io, or any OCI-compatible registry is essentially a Linux root filesystem packaged in layers. You can pull any of them and turn them into a WSL distribution.

Want Fedora? Arch Linux? Rocky Linux? A minimal BusyBox environment? A pre-configured development image your team maintains? They're all available.

The Manual Way (With Docker or Podman)

If you already have Docker or Podman installed, the process is straightforward:

Step 1: Pull the Image

docker pull archlinux:latest

Step 2: Create a Container and Export It

docker create --name temp-arch archlinux:latest
docker export temp-arch -o C:\Temp\archlinux-rootfs.tar
docker rm temp-arch

This creates a container from the image (without starting it), exports its filesystem to a tar file, then removes the container.

Step 3: Import into WSL

wsl --import Arch "D:\WSL\Arch" C:\Temp\archlinux-rootfs.tar

Step 4: First Boot Setup

The imported distribution will log in as root. Set up a user account:

wsl -d Arch

# Create a user (varies by distro)
useradd -m -G wheel myuser
passwd myuser

# Set default user in wsl.conf
cat > /etc/wsl.conf << 'EOF'
[user]
default=myuser
EOF
exit

wsl --terminate Arch
wsl -d Arch

The same approach works with Podman — just replace docker with podman in all commands.

Without Docker: The OCI Approach

You don't need Docker or Podman installed to pull container images. OCI (Open Container Initiative) images are just files hosted on HTTP APIs. You can download them directly.

How Container Images Work

A container image consists of:

A manifest — metadata describing the image, including its layers
Layers — gzipped tar files, each containing filesystem changes
A config — runtime settings (environment variables, entry point, etc.)

When you docker pull alpine, Docker fetches the manifest to learn what layers exist, downloads each layer, and stacks them on top of each other. That's all there is to it.

Multi-Architecture Images

Most images on Docker Hub support multiple architectures (amd64, arm64, etc.). The manifest you first receive is actually a manifest list — an index pointing to architecture-specific manifests. For WSL, you want the linux/amd64 variant.

Layer Merging and Whiteouts

Container images use a layered filesystem. Each layer can add, modify, or delete files from the layers below it. Deletions are handled through whiteout files:

.wh.filename — deletes a specific file from lower layers
.wh..wh..opq — marks a directory as opaque, hiding all contents from lower layers

When building a rootfs for WSL, you need to process these whiteouts correctly. Simply extracting all layers on top of each other doesn't work — you'd end up with stale files that should have been deleted.

Why Not Just Extract on Windows?

There's a subtlety that trips people up: you can't extract Linux tar layers to a Windows filesystem and then import them. Linux symlinks, permissions, and special files don't survive the round-trip through NTFS. The layers need to be merged in tar format, keeping the Linux-native metadata intact, and then imported directly by WSL.

Popular Images to Try

Here are some container images that make useful WSL distributions:

Image	Why
`archlinux:latest`	Rolling release, AUR access, cutting-edge packages
`fedora:latest`	Latest Fedora release, good for Red Hat ecosystem
`rockylinux:9`	RHEL-compatible, great for enterprise dev work
`clearlinux:latest`	Intel-optimized, performance-focused
`amazonlinux:2023`	Match your AWS Lambda/EC2 environment locally
`oraclelinux:9`	Oracle database development and testing

Any image with a full Linux userspace works. Minimal images like alpine work too, though they use musl libc which can cause compatibility issues with some software.

Images that DON'T work well as WSL distributions:

scratch — empty image, nothing to run
busybox — too minimal, missing package manager
Application images (like nginx, postgres) — these are designed to run a single process, not be interactive environments

The Easy Way: WSL UI

WSL UI has a built-in OCI client that handles all of this without Docker, Podman, or any command-line work. The "New Distribution" dialog includes a Container tab where you can:

Browse a catalog of pre-configured container images
Enter any custom image reference (e.g., ghcr.io/myorg/myimage:latest)
WSL UI pulls the manifest, downloads layers, handles authentication (Bearer tokens for public registries), merges layers with proper whiteout handling, and imports the result

The built-in OCI client works for public registries. For private registries that need authentication beyond anonymous Bearer tokens, WSL UI can also delegate to Docker or Podman if they're installed — giving you the best of both worlds.

Progress is shown as each layer downloads, so you can see how far along the pull is for large images.

Registry Authentication

Public images on Docker Hub, GHCR, Quay.io, and MCR (Microsoft Container Registry) use a challenge-based authentication flow:

Client requests the manifest
Registry responds with 401 Unauthorized and a WWW-Authenticate header
Client requests a token from the auth service
Client retries with the Bearer token

This happens automatically for public images — no login required. Private images need credentials, which is where having Docker or Podman configured with docker login or podman login helps.

Post-Import Setup

Container images are designed for containers, not interactive use. After importing, you'll typically want to:

Create a non-root user — containers run as root by default
Install an init system — some distros need systemd configured in /etc/wsl.conf
Set up a package manager — most images have one, but verify it works
Configure locale and timezone — container images often have minimal locale support

For Ubuntu and Debian-based images:

apt update && apt install -y sudo locales
locale-gen en_US.UTF-8
useradd -m -s /bin/bash -G sudo myuser
passwd myuser

For Fedora/RHEL-based images:

dnf install -y sudo passwd
useradd -m -s /bin/bash myuser
passwd myuser
usermod -aG wheel myuser

Summary

Task	Command
Pull with Docker	`docker pull image:tag`
Export container	`docker create --name tmp image && docker export tmp -o rootfs.tar && docker rm tmp`
Import to WSL	`wsl --import Name "D:\path" rootfs.tar`
Set default user	Edit `/etc/wsl.conf` → `[user]` → `default=username`

Container registries are the largest library of Linux environments available. Combined with WSL's import command, you can run virtually any Linux distribution — not just the handful in the Microsoft Store.

Originally published at https://wsl-ui.octasoft.co.uk/blog/importing-container-images-as-wsl-distributions

Cloning WSL Distributions

Ian Packard — Thu, 19 Feb 2026 00:29:08 +0000

You've spent hours setting up your WSL distribution — installed the right packages, configured your shell, tuned your development environment. Now you need to experiment with something risky. Maybe a major version upgrade, a new tool that might break things, or a client project that needs its own isolated environment.

You don't want to mess up your working setup. What you want is a clone.

WSL doesn't have a --clone command, but you can achieve the same result with export and import. The idea is simple: export your distribution to a tar file, then import it as a new distribution with a different name.

How to Clone a Distribution

Step 1: Export the Source

wsl --export Ubuntu C:\Temp\ubuntu-clone.tar

This creates a complete snapshot of the distribution's filesystem. Everything is included — installed packages, user accounts, configuration files, your home directory contents.

For large distributions, this can take a few minutes and the tar file will be roughly the same size as your used disk space inside the distro.

Step 2: Import as a New Distribution

wsl --import Ubuntu-Dev "D:\WSL\Ubuntu-Dev" C:\Temp\ubuntu-clone.tar

The arguments are:

Ubuntu-Dev — the name for the clone
D:\WSL\Ubuntu-Dev — where to store the clone's virtual disk
C:\Temp\ubuntu-clone.tar — the tar file from step 1

WSL creates a new VHDX file at the specified location and extracts the tar contents into it.

Step 3: Fix the Default User

When you import from a tar archive, WSL defaults to logging in as root. You need to restore your default user.

Start the clone as root and edit /etc/wsl.conf:

wsl -d Ubuntu-Dev -u root

# Check if [user] section already exists
grep -q "^\[user\]" /etc/wsl.conf 2>/dev/null || cat >> /etc/wsl.conf << 'EOF'
[user]
default=yourusername
EOF
exit

Restart the distribution:

wsl --terminate Ubuntu-Dev
wsl -d Ubuntu-Dev
whoami

This should show your username.

Step 4: Clean Up

Delete the temporary tar file:

Remove-Item C:\Temp\ubuntu-clone.tar

Faster Cloning with VHD Format

The tar export/import works but it's slow for large distributions. The entire filesystem gets serialized to tar, then extracted back. For a 50GB distribution, that's a lot of I/O.

A faster approach uses VHD format, which copies the virtual disk directly:

# Export as VHD (much faster)
wsl --export Ubuntu C:\Temp\ubuntu-clone.vhdx --format vhd

# Import the VHD copy
wsl --import Ubuntu-Dev "D:\WSL\Ubuntu-Dev" C:\Temp\ubuntu-clone.vhdx --vhd

The VHD method skips the tar serialization entirely. It copies the VHDX file as-is, which is significantly faster and also preserves your default user settings (no need to fix /etc/wsl.conf).

Use Cases for Cloning

Testing upgrades: Clone before running do-release-upgrade on Ubuntu. If it breaks, delete the clone and try again.

Project isolation: Give each major project its own distribution with exactly the dependencies it needs. No conflicts between projects with different Node.js, Python, or library versions.

Experimentation: Want to try a new shell, desktop environment, or system configuration? Clone first, experiment freely.

Training environments: Create a pre-configured development environment, clone it for each team member or workshop participant.

Before risky changes: About to restructure your home directory, change your shell, or modify system services? A clone is your safety net.

The Easy Way: WSL UI

WSL UI has a one-click clone feature. Right-click a distribution and choose "Clone" to get a dialog where you:

Enter a name for the clone (defaults to DistroName-clone)
Optionally choose a custom install location
Click Clone and wait

Behind the scenes, it exports to a temporary file in %TEMP%, imports with the new name, and cleans up automatically. It also tracks clone lineage in metadata — so you can see which distribution was cloned from which, useful when you have multiple clones and need to remember the original.

Tips

Choose meaningful names for clones. Ubuntu-Dev, Ubuntu-Staging, Ubuntu-ML are better than Ubuntu-clone-2.
Put clones on a different drive if your C: drive is running low. Use the install location parameter to direct the VHDX to D: or another drive.
Delete clones when done. Each clone has its own VHDX file that takes real disk space. Clean up with wsl --unregister CloneName when you no longer need it.
Prefer VHD format for large distributions. It's faster and preserves user settings.

Summary

Task	Command
Export (TAR)	`wsl --export Ubuntu backup.tar`
Export (VHD, faster)	`wsl --export Ubuntu backup.vhdx --format vhd`
Import clone (TAR)	`wsl --import NewName "D:\path" backup.tar`
Import clone (VHD)	`wsl --import NewName "D:\path" backup.vhdx --vhd`
Fix default user	Edit `/etc/wsl.conf` → `[user]` → `default=username`
Delete clone	`wsl --unregister NewName`

Cloning is one of those capabilities that changes how you work with WSL. Instead of being precious about your single distribution, you can branch off, experiment, and throw things away. Treat distributions like git branches — cheap to create, easy to discard.

Originally published at https://wsl-ui.octasoft.co.uk/blog/cloning-wsl-distributions

Backing Up and Restoring WSL Distributions

Ian Packard — Thu, 19 Feb 2026 00:28:18 +0000

Your WSL distribution is more than just an operating system. It's your development environment — your shell configuration, installed tools, SSH keys, project dependencies, database setups. Rebuilding all of that from scratch takes hours, sometimes days.

And yet most people don't back up their WSL distributions. The VHDX file sitting in %LOCALAPPDATA% is silently holding everything, and one bad Windows update, a disk failure, or an accidental wsl --unregister could wipe it out.

The fix is straightforward: WSL has built-in export and import commands that create portable backup archives.

Exporting a Distribution

The wsl --export command creates a complete snapshot of your distribution's filesystem:

wsl --export Ubuntu D:\Backups\ubuntu-2026-02-21.tar

This produces an uncompressed tar archive containing every file in the distribution — installed packages, user accounts, configuration, home directories, everything.

Export Formats

WSL supports several export formats:

Uncompressed TAR (default):

wsl --export Ubuntu D:\Backups\ubuntu.tar

Fastest to create and restore, but largest file size.

Compressed TAR (gzip):

wsl --export Ubuntu D:\Backups\ubuntu.tar.gz --format tar.gz

Significantly smaller file, takes longer to create and restore.

Compressed TAR (xz):

wsl --export Ubuntu D:\Backups\ubuntu.tar.xz --format tar.xz

Smallest file size, but slowest compression. Good for archival or transferring over the network.

VHD format:

wsl --export Ubuntu D:\Backups\ubuntu.vhdx --format vhd

Copies the virtual disk directly. Fastest export, preserves everything including disk structure and default user settings. Restore is also fast since it skips tar extraction.

Which Format Should I Use?

Format	Speed	Size	Preserves User	Best For
TAR	Fast	Large	No	Quick local backups
TAR.GZ	Medium	Medium	No	External drives, sharing
TAR.XZ	Slow	Small	No	Archival, network transfer
VHD	Fastest	Exact copy	Yes	Fast backup/restore

For regular backups to a local or external drive, VHD format is usually the best choice. It's fast in both directions and preserves your default user setting. Use compressed TAR when file size matters more than speed.

Restoring from a Backup

From a TAR Archive

wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu-2026-02-21.tar

The arguments are: name, install location, and backup file path.

After importing from TAR, you'll need to fix the default user since TAR imports default to root:

wsl -d Ubuntu -u root

# Add your default user to wsl.conf if not already there
grep -q "^\[user\]" /etc/wsl.conf 2>/dev/null || cat >> /etc/wsl.conf << 'EOF'
[user]
default=yourusername
EOF
exit

wsl --terminate Ubuntu
wsl -d Ubuntu
whoami

From a VHD Backup

wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu.vhdx --vhd

VHD restores are faster and your default user setting is already correct — no manual fix needed.

Restoring Over an Existing Distribution

If you're restoring to replace a damaged distribution, unregister the old one first:

wsl --unregister Ubuntu
wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu.vhdx --vhd

Warning: --unregister permanently deletes the distribution's virtual disk. Make sure your backup is valid before doing this.

A Simple Backup Script

Here's a PowerShell script that backs up all your distributions:

$backupDir = "D:\Backups\WSL"
$date = Get-Date -Format "yyyy-MM-dd"

# Create backup directory
New-Item -ItemType Directory -Path "$backupDir\$date" -Force | Out-Null

# Get all distributions
$distros = wsl --list --quiet | Where-Object { $_ -and $_.Trim() }

foreach ($distro in $distros) {
    $distro = $distro.Trim()
    $backupFile = "$backupDir\$date\$distro.vhdx"
    Write-Host "Backing up $distro..."
    wsl --export $distro $backupFile --format vhd
    Write-Host "  Done: $backupFile"
}

Write-Host "`nAll distributions backed up to $backupDir\$date"

Save this as backup-wsl.ps1 and run it periodically. You could schedule it with Task Scheduler for automated weekly backups.

What's Included (and What's Not)

Included in the backup:

All installed packages and their configuration
All user accounts and home directories
System configuration (/etc/, services, cron jobs)
Custom scripts and tools you've installed
Database data files (if running databases inside WSL)
SSH keys, GPG keys, shell configuration

NOT included:

WSL configuration from .wslconfig (this is a Windows-side file at %USERPROFILE%\.wslconfig)
Distribution-specific settings in the Windows Registry (default user, WSL version)
Windows Terminal profile customizations
Mounted Windows drives content (they're just mount points)

If you have customized .wslconfig, back that up separately:

Copy-Item "$env:USERPROFILE\.wslconfig" "D:\Backups\WSL\wslconfig-backup"

The Easy Way: WSL UI

WSL UI provides one-click export and import through the quick actions menu. Click Export on any distribution to get a save dialog with your distribution name and today's date as the default filename. Import opens a dialog where you select the tar file, enter a name, and choose an install location.

The app also tracks import/export metadata — recording when and from where each distribution was imported, so you can trace the history of your environments.

Tips

Include the date in filenames: Ubuntu-2026-02-21.tar makes it clear when the backup was taken
Store backups on a different drive: If your C: drive fails, backups on D: or an external drive survive
Test your backups periodically: Import a backup under a temporary name to verify it works, then wsl --unregister the test import
Back up before risky operations: Before major upgrades, kernel changes, or experimental tooling
Keep at least two generations: Don't overwrite your only backup — rotate between two or three copies

Summary

Task	Command
Export (TAR)	`wsl --export <distro> backup.tar`
Export (compressed)	`wsl --export <distro> backup.tar.gz --format tar.gz`
Export (VHD, fastest)	`wsl --export <distro> backup.vhdx --format vhd`
Import (TAR)	`wsl --import <name> "<location>" backup.tar`
Import (VHD)	`wsl --import <name> "<location>" backup.vhdx --vhd`
Fix default user	Edit `/etc/wsl.conf` → `[user]` → `default=username`
Unregister old	`wsl --unregister <distro>`
Back up .wslconfig	`Copy-Item $env:USERPROFILE\.wslconfig <backup-path>`

Your WSL environment is worth protecting. A few minutes of backup now can save hours of rebuilding later.

Originally published at https://wsl-ui.octasoft.co.uk/blog/backing-up-and-restoring-wsl-distributions

Moving WSL Distributions to Another Drive

Ian Packard — Wed, 18 Feb 2026 23:13:30 +0000

WSL2 distributions default to your C: drive. That's fine when you have one small Ubuntu install. It's less fine when you have five distros, each with a 20-50GB virtual disk, and your system drive is running out of space.

The good news: you can move distributions to any drive. The less good news: there are a couple of ways to do it, and the right approach depends on your WSL version.

Where Are My Distributions Stored?

Before moving anything, let's find where your distros currently live. WSL stores each distribution's virtual hard disk (VHDX) in a base path registered in the Windows Registry:

HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\BasePath

Common default locations:

Newer WSL: %LOCALAPPDATA%\wsl\{GUID}\
Store-installed distros: %LOCALAPPDATA%\Packages\<distro-package>\LocalState\

You can check your distro sizes from PowerShell:

Get-ChildItem -Path "$env:LOCALAPPDATA\wsl" -Recurse -Filter "ext4.vhdx" |
  Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB, 2)}}

Or list all your distributions and their WSL versions:

wsl --list --verbose

Method 1: wsl --manage --move (Recommended)

The simplest way to move a distribution is WSL's built-in move command. This relocates the VHDX file and updates the registry in one step.

Step 1: Stop the Distribution

The distro must be stopped before moving:

wsl --terminate Ubuntu

Verify it's stopped:

wsl --list --verbose

Look for "Stopped" next to your distro name.

Step 2: Move It

wsl --manage Ubuntu --move "D:\WSL\Ubuntu"

WSL will create the destination directory if needed and move the VHDX file. This can take a while for large distros — a 50GB VHDX will take a few minutes depending on your disk speed.

Step 3: Verify

Start the distro and confirm everything works:

wsl -d Ubuntu

whoami
ls ~

That's it. Your distribution is now on D: and WSL knows where to find it. All your files, installed packages, and configuration are preserved.

Method 2: Export and Import

If --manage --move isn't available on your WSL version, or if you want to rename the distro at the same time, the export/import approach works on all WSL2 installations.

Step 1: Export the Distribution

You have two format options:

TAR format (default, universal):

wsl --export Ubuntu D:\Backups\ubuntu-backup.tar

VHD format (faster, preserves disk structure):

wsl --export Ubuntu D:\Backups\ubuntu-backup.vhdx --format vhd

The VHD format is significantly faster because it copies the VHDX file directly instead of creating a tar archive from the filesystem. For large distros, this can save considerable time.

Compressed TAR (smaller file):

wsl --export Ubuntu D:\Backups\ubuntu-backup.tar.gz --format tar.gz

Step 2: Unregister the Old Distribution

This removes the distribution from WSL's registry and deletes the original VHDX:

wsl --unregister Ubuntu

Warning: This deletes the original distribution data. Make sure your export completed successfully before running this. Check the file size of your export — it should be reasonable (not 0 bytes).

Step 3: Import to the New Location

From a TAR export:

wsl --import Ubuntu "D:\WSL\Ubuntu" D:\Backups\ubuntu-backup.tar

From a VHD export:

wsl --import Ubuntu "D:\WSL\Ubuntu" D:\Backups\ubuntu-backup.vhdx --vhd

The arguments are: wsl --import <name> <install-location> <file-path>.

Step 4: Fix the Default User

When you import from a TAR archive, WSL defaults to logging in as root. You need to restore your default user. Edit /etc/wsl.conf inside the distro:

wsl -d Ubuntu -u root

cat >> /etc/wsl.conf << 'EOF'
[user]
default=yourusername
EOF
exit

Then restart the distro for the change to take effect:

wsl --terminate Ubuntu
wsl -d Ubuntu
whoami

This should now show your username instead of root.

Note: If you exported as VHD format, the /etc/wsl.conf file is preserved as-is inside the VHDX, so your default user setting should already be correct.

Step 5: Clean Up

Once everything is working, delete the backup file:

Remove-Item D:\Backups\ubuntu-backup.tar

Method 3: Import In-Place (Advanced)

If you've already manually copied a VHDX file to a new location, you can register it directly without WSL copying it again:

wsl --import-in-place Ubuntu "D:\WSL\Ubuntu\ext4.vhdx"

This tells WSL to use the VHDX at its current location. The file must be ext4-formatted (which all WSL2 VHDX files are). This is the fastest option if you've already moved the file yourself.

Choosing the Right Method

Factor	--manage --move	Export/Import (TAR)	Export/Import (VHD)
Speed	Fast (direct move)	Slow (tar + extract)	Medium (file copy)
Disk space needed	Just the destination	2x (export + import)	2x (export + import)
Preserves user settings	Yes	No (need to fix)	Yes
Rename distro	No	Yes	Yes
WSL version required	Recent WSL	Any WSL2	Any WSL2
Complexity	Low	Medium	Medium

For most people, --manage --move is the right choice. Use export/import when you need to rename the distro or are on an older WSL version.

Installing New Distros on a Different Drive

Prevention is better than cure. When installing new distributions, you can specify the location upfront:

wsl --install Ubuntu --location "D:\WSL\Ubuntu"

This puts the VHDX on D: from the start, avoiding the need to move it later.

The Easy Way: WSL UI

WSL UI makes moving distributions a point-and-click operation. The Move Distribution dialog:

Shows the current location and disk size
Lets you browse to a new location
Handles stopping the distro, moving the files, and updating the registry
Shows progress for large moves

No command line, no worrying about which method to use, no manual registry updates. It uses WSL's native move command under the hood, so everything is preserved — your files, settings, default user, and configuration.

Troubleshooting

"The operation is not supported" when using --manage --move:
You may be on an older WSL version. Update with wsl --update or use the export/import method instead.

Import defaults to root user:
This is expected with TAR imports. Edit /etc/wsl.conf as described in Step 4 of Method 2.

"Access is denied" during move:
Make sure no WSL processes are using the distro. Run wsl --shutdown to stop everything, then try again.

Distro not showing after import:
Check that the import path exists and you have write permissions. Try running PowerShell as Administrator.

Running out of space during export:
Export to the destination drive directly. For example, if moving from C: to D:, export to D:\Backups\ instead of a location on C:.

Summary

Task	Command
List distros	`wsl --list --verbose`
Stop a distro	`wsl --terminate <distro>`
Move (simple)	`wsl --manage <distro> --move "D:\WSL\path"`
Export (TAR)	`wsl --export <distro> backup.tar`
Export (VHD)	`wsl --export <distro> backup.vhdx --format vhd`
Unregister	`wsl --unregister <distro>`
Import (TAR)	`wsl --import <name> "D:\path" backup.tar`
Import (VHD)	`wsl --import <name> "D:\path" backup.vhdx --vhd`
Import in-place	`wsl --import-in-place <name> "D:\path\ext4.vhdx"`
Install on D:	`wsl --install Ubuntu --location "D:\WSL\Ubuntu"`
Fix default user	Edit `/etc/wsl.conf` → `[user]` → `default=username`

Moving a distro is one of those tasks you only do once or twice, but it makes a real difference when your C: drive is filling up.

Originally published at https://wsl-ui.octasoft.co.uk/blog/moving-wsl-distributions-to-another-drive

Managing WSL Disk Space

Ian Packard — Wed, 18 Feb 2026 23:12:52 +0000

If you've been using WSL2 for a while, you've probably noticed your C: drive slowly losing space. Maybe 10GB here, 50GB there. The culprit? WSL2's virtual hard disk files — they grow as you use them but never shrink back on their own.

This is one of those things that catches people off guard. You delete 20GB of files inside your distro, check your Windows disk space, and... nothing changed. The space is still gone.

Let's fix that.

How WSL2 Stores Data

WSL2 runs each distribution inside a lightweight virtual machine. Your Linux filesystem lives in a VHDX file — a Hyper-V virtual hard disk. When you install packages, download files, or build projects inside WSL, this VHDX file grows to accommodate the data.

The problem: when you delete those files, the VHDX doesn't shrink. The file on your Windows drive stays the same size, even though the Linux filesystem inside it now has free space. Over months of use, this gap between actual usage and file size can become substantial.

Finding Your VHDX Files

First, let's see what we're dealing with. Your VHDX files are typically stored in one of these locations:

Default (newer WSL): %LOCALAPPDATA%\wsl\
Store-installed distros: %LOCALAPPDATA%\Packages\<distro-package>\LocalState\
Custom locations: Wherever you specified during wsl --import

To find the exact path for a specific distro, check the Windows Registry:

HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\BasePath

The VHDX file is always called ext4.vhdx inside that base path.

Checking the Damage

From PowerShell, you can see all your VHDX sizes at once:

Get-ChildItem -Path "$env:LOCALAPPDATA\wsl" -Recurse -Filter "ext4.vhdx" |
  Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB, 2)}}

Inside each distro, check actual disk usage with:

df -h /

Compare those numbers. If your VHDX is 45GB but df shows only 20GB used, you have 25GB of reclaimable space.

Reclaiming Disk Space

Compacting a VHDX is a multi-step process. You need to zero out the free space inside the Linux filesystem, shut down WSL so the file isn't locked, then compact the VHDX from Windows.

Step 1: Zero Unused Blocks with fstrim

The fstrim command tells the filesystem to discard blocks that are no longer in use. This zeros them out so the VHDX compactor can identify and reclaim the space.

Run this inside your distro (as root):

sudo fstrim -av

You should see output like:

/: 12.5 GiB (13421772800 bytes) trimmed on /dev/sdd

That number tells you how much space is potentially reclaimable.

Alpine Linux note: Alpine uses BusyBox which has a simpler fstrim. Use sudo fstrim -v / instead of -av.

Step 2: Shut Down WSL

The VHDX file must not be in use when you compact it. From PowerShell or Command Prompt:

wsl --shutdown

This stops all running distributions and the WSL2 VM. Wait a few seconds for the filesystem to fully release.

Step 3: Compact the VHDX

You have two options here, depending on your Windows setup.

Option A: Optimize-VHD (Hyper-V required)

If you have Hyper-V enabled (Windows Pro/Enterprise), this is the faster and more reliable method. Run PowerShell as Administrator:

Optimize-VHD -Path "$env:LOCALAPPDATA\wsl\{distro-guid}\ext4.vhdx" -Mode Full

Option B: diskpart (works everywhere)

If you don't have Hyper-V, diskpart is built into every Windows installation. Run Command Prompt as Administrator:

diskpart
select vdisk file="C:\Users\YourName\AppData\Local\wsl\{distro-guid}\ext4.vhdx"
compact vdisk
exit

Wait for the "DiskPart successfully compacted the virtual disk file" message.

Step 4: Verify

Start your distro again and check the Windows file size:

wsl -d Ubuntu -- echo "Distro started"
Get-Item "$env:LOCALAPPDATA\wsl\{distro-guid}\ext4.vhdx" |
  Select-Object @{N='SizeGB';E={[math]::Round($_.Length/1GB, 2)}}

You should see a smaller file size. In practice, I've seen compaction reclaim anywhere from a few hundred MB to tens of GB depending on how long the distro has been running.

Enabling Sparse Mode (Automatic Reclamation)

Manually compacting is fine occasionally, but WSL has a better long-term solution: sparse mode. When enabled, WSL automatically reclaims disk space as you delete files — no manual compaction needed.

Enable it per-distro:

wsl --manage <distro-name> --set-sparse true

For example:

wsl --manage Ubuntu --set-sparse true

To disable it:

wsl --manage <distro-name> --set-sparse false

Things to know about sparse mode:

It works on a per-distribution basis
There's a small performance overhead for the automatic reclamation
It's most effective on distros where you frequently create and delete large files (build artifacts, container images, etc.)
Your distro needs to be stopped when you enable it

Resizing the Virtual Disk

Sometimes you need the opposite — more space. WSL2 defaults to a 1TB maximum virtual disk size, but you can expand it:

wsl --manage <distro-name> --resize 512GB

This increases the maximum size the VHDX can grow to. You can only increase the size, not decrease it. After resizing, you may need to extend the filesystem inside the distro:

sudo resize2fs /dev/sdd

The Easy Way: WSL UI

All of these steps — finding VHDX files, running fstrim, shutting down WSL, choosing between Optimize-VHD and diskpart — are exactly the kind of multi-step process that's easy to get wrong.

WSL UI handles all of this with a single click. The compact feature:

Runs fstrim inside the distro automatically
Shuts down WSL and waits for the file lock to release
Tries Optimize-VHD first, falls back to diskpart if Hyper-V isn't available
Shows you the before/after sizes and how much space was saved

It also shows disk usage in the main dashboard, so you can spot distros that need attention before your C: drive fills up.

Sparse mode is a toggle in the distribution settings — no command line needed.

Prevention Tips

A few things you can do to keep disk growth under control:

Enable sparse mode on distros where you do heavy development
Clean package caches regularly: sudo apt clean (Ubuntu/Debian) or sudo dnf clean all (Fedora)
Watch Docker/Podman storage — container images inside WSL are a common space hog. Run docker system prune or podman system prune periodically
Use --location when installing — wsl --install Ubuntu --location D:\WSL\Ubuntu puts the VHDX on a different drive from the start
Compact before and after major cleanup — if you're about to delete a lot of data, compact afterward to actually reclaim the space

Summary

Task	Command
Check VHDX size	`Get-Item path\ext4.vhdx` in PowerShell
Check Linux usage	`df -h /` inside distro
Zero free space	`sudo fstrim -av` inside distro
Shut down WSL	`wsl --shutdown`
Compact (Hyper-V)	`Optimize-VHD -Path "..." -Mode Full`
Compact (built-in)	`diskpart` → `select vdisk` → `compact vdisk`
Enable sparse mode	`wsl --manage <distro> --set-sparse true`
Resize disk	`wsl --manage <distro> --resize 512GB`

Your WSL distributions don't need to eat your entire C: drive. A bit of maintenance goes a long way.

Originally published at https://wsl-ui.octasoft.co.uk/blog/managing-wsl-disk-space

Automated TLS Certificates with Let's Encrypt and DNS-01 Challenges

Ian Packard — Sun, 01 Feb 2026 23:49:06 +0000

HTTPS everywhere isn't optional anymore. Browsers flag HTTP as insecure, service meshes expect mTLS, and APIs should be encrypted in transit. But managing TLS certificates manually is tedious - renewals every 90 days, CSR generation, key management, distribution to load balancers.

Let's Encrypt solved the cost problem (free certificates) and the validation problem (automated domain verification). cert-manager brings this to Kubernetes with native integration. This post covers how to set up fully automated TLS certificate management using DNS-01 challenges with AWS Route53.

Series context: This is Part 6 of the Homelab Kubernetes Series. We've covered bootstrapping, GitOps with ArgoCD, service mesh setup, and secrets management. Now we're adding automated TLS certificate management to complete the security layer.

Why DNS-01 Over HTTP-01

Let's Encrypt supports two main challenge types for proving domain ownership:

HTTP-01: Let's Encrypt requests a file at http://yourdomain.com/.well-known/acme-challenge/token. Your server must respond with the correct token.

DNS-01: Let's Encrypt queries a TXT record at _acme-challenge.yourdomain.com. You create this record with the token value.

For many Kubernetes deployments, DNS-01 is the better choice:

Scenario	HTTP-01	DNS-01
Public-facing services	Works	Works
Private/internal services	Fails	Works
Wildcard certificates	Not supported	Supported
Firewall restrictions	Needs port 80 open	No inbound ports
Load balancer complexity	Needs routing	DNS only

If your services aren't publicly accessible - homelab, private cloud, internal APIs - HTTP-01 won't work. DNS-01 proves you control the domain regardless of where your services run.

The Components

The setup involves four pieces:

cert-manager - Kubernetes controller that manages certificate lifecycle
Let's Encrypt - Free certificate authority with ACME protocol support
AWS Route53 - DNS provider (or your DNS provider of choice)
External Secrets - Secure credential management for AWS access

cert-manager watches for Certificate resources, contacts Let's Encrypt, solves the DNS challenge by creating Route53 records, and stores the issued certificate as a Kubernetes Secret.

Installing cert-manager

cert-manager installs via Helm. The key configuration enables Gateway API support and Prometheus metrics:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cert-manager
  namespace: argocd
spec:
  source:
    repoURL: https://charts.jetstack.io
    chart: cert-manager
    targetRevision: v1.18.2

    helm:
      values: |
        # Install CRDs with the chart
        installCRDs: true

        # Resource limits for homelab/small clusters
        resources:
          requests:
            cpu: 20m
            memory: 64Mi
          limits:
            cpu: 200m
            memory: 256Mi

        webhook:
          resources:
            requests:
              cpu: 5m
              memory: 16Mi
            limits:
              cpu: 50m
              memory: 64Mi

        cainjector:
          resources:
            requests:
              cpu: 5m
              memory: 16Mi
            limits:
              cpu: 100m
              memory: 128Mi

        # Prometheus metrics
        prometheus:
          enabled: true
          servicemonitor:
            enabled: true

        # Enable Gateway API integration
        extraArgs:
          - --enable-gateway-api

        # Security
        securityContext:
          runAsNonRoot: true

  destination:
    server: https://kubernetes.default.svc
    namespace: cert-manager

The --enable-gateway-api flag is important if you're using Gateway API instead of Ingress. As we covered in Part 4 (Service Mesh), cert-manager can automatically provision certificates for Gateway listeners.

AWS IAM Setup

cert-manager needs permission to create DNS records in Route53. The principle of least privilege means giving it exactly what it needs - and for ACME DNS-01 challenges, that's surprisingly narrow.

IAM architecture options:

IAM User with direct permissions - Simple, but the user has standing Route53 access
IAM Role with IRSA (EKS) - Pod assumes role via service account, no static credentials
IAM User + Role assumption - User can only assume a role, role has the actual permissions

I use option 3. The IAM user has no Route53 permissions at all - its only ability is to assume a specific role. This separates identity (the user) from capability (the role), and means compromised credentials can't do anything without also compromising the role assumption.

The IAM User (Identity Only)

The user exists solely to provide credentials that can assume the role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Resource": "arn:aws:iam::ACCOUNT_ID:role/CertManagerDNSRole"
    }
  ]
}

That's it. The user can assume exactly one role and nothing else.

The IAM Role (Capability)

The role has the actual Route53 permissions, tightly scoped for ACME challenges:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "route53:GetChange",
      "Resource": "arn:aws:route53:::change/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets",
        "route53:ListResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/ZONE_ID_HERE",
      "Condition": {
        "ForAllValues:StringEquals": {
          "route53:ChangeResourceRecordSetsRecordTypes": ["TXT"]
        },
        "ForAllValues:StringLike": {
          "route53:ChangeResourceRecordSetsRecordNames": ["_acme-challenge.*"]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ListHostedZonesByName",
        "route53:ListHostedZones",
        "route53:GetHostedZone"
      ],
      "Resource": "*"
    }
  ]
}

The conditions are key:

ChangeResourceRecordSetsRecordTypes: ["TXT"] - Can only modify TXT records
ChangeResourceRecordSetsRecordNames: ["_acme-challenge.*"] - Can only modify records starting with _acme-challenge.

Even if the role is compromised, it can't touch your A records, MX records, or anything else. It can only create and delete the specific TXT records needed for ACME validation.

Trust Policy (Who Can Assume)

The role's trust policy specifies which principals can assume it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT_ID:user/service-accounts/certmanager-dns-challenge"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Only the specific cert-manager IAM user can assume this role. Combined with the scoped permissions, this creates defence in depth: compromise the user credentials, and you can only assume this one role; compromise the role, and you can only modify ACME challenge records.

Credential Management

The IAM access key and secret need to reach cert-manager. Hardcoding them in manifests is a security incident waiting to happen. As covered in Part 5 (Secrets Management), I use External Secrets Operator to pull credentials from Infisical:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: route53-credentials-external
  namespace: cert-manager
spec:
  refreshInterval: 15m
  secretStoreRef:
    name: infisical-cluster-secretstore
    kind: ClusterSecretStore
  target:
    name: route53-credentials
    creationPolicy: Owner
  data:
    - secretKey: access-key-id
      remoteRef:
        key: /cert-manager/AWS_ACCESS_KEY_ID
    - secretKey: secret-access-key
      remoteRef:
        key: /cert-manager/AWS_SECRET_ACCESS_KEY

This creates a Kubernetes Secret named route53-credentials in the cert-manager namespace, refreshed every 15 minutes. If you rotate the AWS credentials in your secrets manager, they propagate automatically.

For simpler setups without a secrets manager, create the secret directly (but don't commit it to Git):

kubectl create secret generic route53-credentials \
  --namespace cert-manager \
  --from-literal=access-key-id=AKIAIOSFODNN7EXAMPLE \
  --from-literal=secret-access-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

The ClusterIssuer

A ClusterIssuer defines how cert-manager obtains certificates. For Let's Encrypt with DNS-01:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # Let's Encrypt production server
    server: https://acme-v02.api.letsencrypt.org/directory

    # Email for expiry notifications and account recovery
    email: your-email@example.com

    # Secret to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-prod

    # DNS-01 solver configuration
    solvers:
    - dns01:
        route53:
          region: us-east-1
          hostedZoneID: "Z0123456789ABCDEFGHIJ"

          # Reference to the credentials secret
          accessKeyIDSecretRef:
            name: route53-credentials
            key: access-key-id
          secretAccessKeySecretRef:
            name: route53-credentials
            key: secret-access-key

          # IAM role to assume (optional but recommended)
          role: "arn:aws:iam::ACCOUNT_ID:role/CertManagerDNSRole"

      # Only use this solver for specific domains
      selector:
        dnsZones:
        - example.com

Key fields explained:

server: Use staging (acme-staging-v02.api.letsencrypt.org) for testing to avoid rate limits
email: Let's Encrypt sends expiry warnings here (cert-manager renews automatically, but good to have)
privateKeySecretRef: cert-manager creates this secret to store your ACME account key
hostedZoneID: Your Route53 zone ID (find it in the AWS console)
role: Optional IAM role to assume - if specified, cert-manager uses STS AssumeRole
selector.dnsZones: Restricts this solver to specific domains (useful with multiple issuers)

Always test with staging first. Let's Encrypt has strict rate limits (50 certificates per domain per week). Staging certificates aren't trusted by browsers but validate your configuration works.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    # ... rest identical to production

Requesting Certificates

With the ClusterIssuer configured, request a certificate:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app-tls
  namespace: my-app
spec:
  # Where to store the certificate
  secretName: my-app-tls-cert

  # Which issuer to use
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

  # Domains to include
  dnsNames:
  - app.example.com
  - "*.app.example.com"  # Wildcard - requires DNS-01

cert-manager:

Contacts Let's Encrypt to start the ACME flow
Creates a TXT record in Route53: _acme-challenge.app.example.com
Tells Let's Encrypt to verify the record
Receives the signed certificate
Stores it in the my-app-tls-cert Secret
Cleans up the DNS record
Renews automatically before expiry (default: 30 days before)

The resulting secret contains:

tls.crt - The certificate chain (your cert + Let's Encrypt intermediate)
tls.key - The private key

Using Certificates

Kubernetes has two approaches for routing external traffic: the original Ingress API and the newer Gateway API. Gateway API is the successor - more expressive, role-oriented, and now the recommended approach for new deployments.

Gateway API (Recommended)

Gateway API separates concerns: infrastructure teams manage Gateways (the load balancer configuration), application teams manage HTTPRoutes (where traffic goes). As we set up in Part 4 (Service Mesh), the Gateway references the TLS certificate:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: istio-ingress
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
      - name: my-app-tls-cert
        namespace: istio-ingress
    allowedRoutes:
      namespaces:
        from: All

Services then attach to the Gateway via HTTPRoute resources. The HTTPRoute doesn't need to know about TLS - the Gateway handles termination:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: my-app
spec:
  parentRefs:
  - name: main-gateway
    namespace: istio-ingress
  hostnames:
  - "app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-app
      port: 80

This separation means one wildcard certificate on the Gateway serves all HTTPRoutes - you don't need per-service certificates.

Ingress (Legacy Approach)

Ingress combines routing and TLS in a single resource. It still works and is widely supported, but lacks the flexibility of Gateway API:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - app.example.com
    secretName: my-app-tls-cert
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app
            port:
              number: 80

With the annotation, cert-manager automatically creates a Certificate resource when you create the Ingress. This is convenient but couples certificate management to the Ingress resource.

Which to Choose

Consideration	Gateway API	Ingress
New projects	Recommended	Works, but why?
Existing Ingress setup	Migrate when ready	Continue using
Multi-team environments	Better separation of concerns	Everyone edits same resources
Advanced routing	Traffic splitting, header matching	Basic path/host routing
Controller support	Istio, Envoy, Nginx, Traefik	Nearly universal

Troubleshooting

Check certificate status:

kubectl get certificates -A
kubectl describe certificate my-app-tls -n my-app

Check certificate request:

kubectl get certificaterequests -A
kubectl describe certificaterequest my-app-tls-xxxxx -n my-app

Check challenges:

kubectl get challenges -A
kubectl describe challenge my-app-tls-xxxxx -n my-app

Common issues:

Symptom	Likely cause	Fix
Challenge stays pending	AWS credentials wrong	Check secret exists and has correct keys
"no hosted zone found"	Wrong zone ID or region	Verify hostedZoneID matches Route53
"access denied"	IAM permissions insufficient	Add required Route53 actions to policy
"rate limited"	Too many requests	Wait, or use staging issuer for testing
Certificate not renewing	cert-manager pod unhealthy	Check logs: `kubectl logs -n cert-manager deploy/cert-manager`

Verify DNS propagation:

# Check if the challenge record exists
dig TXT _acme-challenge.app.example.com

# Should return something like:
# _acme-challenge.app.example.com. 300 IN TXT "abc123..."

Other DNS Providers

Route53 is one of many supported DNS providers. cert-manager has solvers for:

Cloudflare - API token with Zone:DNS:Edit permission
Google Cloud DNS - Service account with dns.admin role
Azure DNS - Service principal with DNS Zone Contributor
DigitalOcean - API token
RFC2136 - Dynamic DNS updates (for self-hosted DNS)

The configuration differs slightly per provider, but the pattern is the same: give cert-manager credentials to modify DNS records, configure the solver in your ClusterIssuer.

Example for Cloudflare:

solvers:
- dns01:
    cloudflare:
      email: your-email@example.com
      apiTokenSecretRef:
        name: cloudflare-api-token
        key: api-token

Security Considerations

Credential scope: The DNS credentials can modify your domain's records. Scope them as tightly as possible - specific zones, specific record types if your provider supports it.

Namespace isolation: ClusterIssuer works across all namespaces. For multi-tenant clusters, consider namespace-scoped Issuer resources with separate credentials per tenant.

Private key protection: The certificate's private key is stored in a Kubernetes Secret. Enable encryption at rest for secrets, and use RBAC to restrict who can read them.

Rate limits: Let's Encrypt enforces rate limits. For production, this rarely matters (50 certs/domain/week). For development/testing, use the staging server.

What I'd Change

Automatic Gateway API certificates: cert-manager can watch Gateway resources and automatically provision certificates for listeners. I'm not using this yet - explicitly creating Certificate resources gives more control, but the automatic approach reduces boilerplate.

Multiple DNS providers: For redundancy, you could configure multiple solvers with different DNS providers. If Route53 has issues, fall back to Cloudflare. Probably overkill for most setups, but possible.

Certificate monitoring: Prometheus metrics are enabled, but I haven't built dashboards for certificate expiry tracking. The certmanager_certificate_expiration_timestamp_seconds metric exists - alerting on certificates expiring within 14 days would add defense in depth.

This is Part 6 of the Homelab Kubernetes Series, covering TLS and certificate automation for Kubernetes.

Sources:

Let's Encrypt - Free, automated certificate authority
cert-manager Documentation
ACME Protocol (RFC 8555)

Originally published at https://wsl-ui.octasoft.co.uk/blog/homelab-part-6-tls-certificates

Secrets Management with Infisical and External Secrets Operator

Ian Packard — Sun, 01 Feb 2026 23:47:55 +0000

GitOps has a fundamental tension: everything should be in Git, but secrets shouldn't be in Git. You need database passwords, API keys, and tokens to deploy applications, but committing them to a repository is a security incident waiting to happen.

This post covers how to solve this with Infisical and External Secrets Operator (ESO) - a combination that keeps secrets out of Git while letting Kubernetes applications access them seamlessly.

Series context: This post is part of the Homelab Kubernetes Series. In Part 2 (Bootstrap), I briefly mentioned using Infisical and ESO to fetch the ArgoCD password during cluster setup. This post goes deeper into the full secrets management architecture.

The Problem: Secret Zero

Every secrets management system has a bootstrapping problem. You need a secret to access your secrets manager. Where does that initial secret come from?

The options aren't great:

Environment variables on the host: Someone has to set them
Cloud IAM: Requires cloud infrastructure and vendor lock-in
Mounted files: Still need to get the file there somehow

The pragmatic approach: machine identity credentials stored locally, passed to scripts as environment variables. Not perfect, but contained to one location and never committed to Git.

Why Infisical

I evaluated several options: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, and Infisical. For a homelab or small team, Infisical won for a few reasons:

Free tier is generous enough for small-scale use
Simpler than Vault - no unsealing ceremony, no complex HA setup
First-class External Secrets support with a native provider
EU hosting option (eu.infisical.com) for data residency
Machine identity auth designed for Kubernetes workloads

The setup is: store secrets in Infisical's web UI or CLI, create a machine identity for the cluster, let ESO sync secrets into Kubernetes.

Choosing Your Infisical Region

Infisical offers two hosted regions. Choose based on your data residency requirements:

Region	API URL	Use Case
US (default)	`https://app.infisical.com`	Most users, no specific data residency needs
EU	`https://eu.infisical.com`	GDPR compliance, European data residency

Throughout this post, examples use the US region (app.infisical.com) as the default. If you need EU hosting, replace the domain in all configuration.

Setting Up Machine Identity

Machine identities in Infisical use Universal Auth - a client ID and secret pair specifically for automated systems. No user login, no MFA prompts, just machine-to-machine authentication.

In Infisical's web UI:

Within a project, go to Access Control > Machine Identities
Click Add Machine Identity to Project
Generate a client ID and client secret
Save these somewhere secure (you'll need them for bootstrap and ongoing management)

The identity needs access to read secrets from your project. Scope it to the appropriate environment with read-only access - it doesn't need to modify secrets, just fetch them.

Storing Configuration

Before diving into implementation, establish where configuration lives. I use a config.env file for non-secret values that both scripts and infrastructure-as-code tools can read:

# Infisical Configuration
INFISICAL_API_URL="https://app.infisical.com"    # or https://eu.infisical.com for EU
INFISICAL_PROJECT_SLUG="my-project-slug"
INFISICAL_PROJECT_ID="your-project-uuid"
INFISICAL_ENVIRONMENT="dev"
# Credentials come from environment variables, never stored in files

The actual credentials (INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET) stay in environment variables, set before running any scripts:

export INFISICAL_CLIENT_ID="your-client-id"
export INFISICAL_CLIENT_SECRET="your-client-secret"

This separation keeps configuration in version control while credentials stay out.

Bootstrap: Fetching Initial Secrets

During cluster bootstrap, ESO isn't installed yet. Use the Infisical CLI directly to fetch any secrets needed for initial setup (like an ArgoCD admin password).

Install the CLI:

curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-cli/setup.deb.sh' | sudo -E bash
sudo apt-get install -y infisical

Authenticate and fetch a secret:

# Authenticate with machine identity
INFISICAL_TOKEN=$(infisical login \
  --method="universal-auth" \
  --client-id="$INFISICAL_CLIENT_ID" \
  --client-secret="$INFISICAL_CLIENT_SECRET" \
  --domain="https://app.infisical.com" \
  --silent \
  --plain)

# Fetch a specific secret
ARGOCD_PASSWORD=$(infisical secrets get ARGOCD_ADMIN_PASSWORD \
  --path="/argocd" \
  --env="dev" \
  --projectId="$INFISICAL_PROJECT_ID" \
  --domain="https://app.infisical.com" \
  --token="$INFISICAL_TOKEN" \
  --silent \
  --plain)

# Clear token from memory when done
unset INFISICAL_TOKEN

The --plain flag returns just the value, no JSON wrapping. The --silent flag suppresses progress output.

Validate credentials early in your bootstrap script:

validate_environment() {
    if [ -z "$INFISICAL_CLIENT_ID" ] || [ -z "$INFISICAL_CLIENT_SECRET" ]; then
        echo "Missing Infisical credentials"
        echo "Please set: export INFISICAL_CLIENT_ID='...' INFISICAL_CLIENT_SECRET='...'"
        exit 1
    fi
}

Installing External Secrets Operator

With the cluster running, install ESO via Helm:

helm repo add external-secrets https://charts.external-secrets.io
helm repo update

helm upgrade --install external-secrets external-secrets/external-secrets \
  --namespace external-secrets \
  --create-namespace \
  --set installCRDs=true \
  --wait

Once installed, ESO watches for ExternalSecret resources and syncs them into Kubernetes Secrets.

Creating the Credentials Secret

ESO needs credentials to authenticate with Infisical. Create a Kubernetes Secret containing the machine identity:

kubectl create namespace platform-secrets

kubectl create secret generic infisical-credentials \
  --namespace platform-secrets \
  --from-literal=client-id="$INFISICAL_CLIENT_ID" \
  --from-literal=client-secret="$INFISICAL_CLIENT_SECRET"

Or declaratively with Terraform/OpenTofu:

resource "kubernetes_secret" "infisical_credentials" {
  metadata {
    name      = "infisical-credentials"
    namespace = "platform-secrets"
  }

  data = {
    "client-id"     = var.infisical_client_id
    "client-secret" = var.infisical_client_secret
  }
}

Configuring the ClusterSecretStore

A ClusterSecretStore tells ESO how to reach Infisical. This is cluster-wide, so any namespace can reference it:

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: infisical-cluster-secretstore
spec:
  provider:
    infisical:
      hostAPI: https://app.infisical.com  # or https://eu.infisical.com for EU

      auth:
        universalAuthCredentials:
          clientId:
            name: infisical-credentials
            key: client-id
            namespace: platform-secrets
          clientSecret:
            name: infisical-credentials
            key: client-secret
            namespace: platform-secrets

      secretsScope:
        projectSlug: my-project-slug
        environmentSlug: dev
        secretsPath: "/"

Apply it:

kubectl apply -f cluster-secret-store.yaml

Using the Terraform Provider

If you manage infrastructure with Terraform/OpenTofu, you can read secrets directly from Infisical. This is useful for configuring other providers (like ArgoCD) that need credentials.

terraform {
  required_providers {
    infisical = {
      source  = "Infisical/infisical"
      version = "~> 0.15"
    }
  }
}

provider "infisical" {
  host = "https://app.infisical.com"  # or https://eu.infisical.com for EU
  auth = {
    universal = {
      client_id     = var.infisical_client_id
      client_secret = var.infisical_client_secret
    }
  }
}

Fetch secrets as data sources:

data "infisical_secrets" "argocd" {
  env_slug     = "dev"
  workspace_id = var.infisical_project_id
  folder_path  = "/argocd"
}

# Use in other provider configurations
provider "argocd" {
  password = data.infisical_secrets.argocd.secrets["ARGOCD_ADMIN_PASSWORD"].value
}

This lets you bootstrap providers that need secrets without hardcoding values or using separate secret files.

Important: State file security

When Terraform/OpenTofu reads secrets, those values end up in the state file. This is a security consideration:

OpenTofu supports native client-side state encryption (since 1.7) using AES-GCM with keys from PBKDF2, AWS KMS, GCP KMS, or OpenBao
Terraform does not have native state encryption - you must rely on encrypted backends (S3 with SSE, Terraform Cloud, etc.)

If you're storing secrets in state, OpenTofu's encryption feature is worth considering. Otherwise, ensure your state backend is properly secured and access-controlled.

ExternalSecret Patterns

With the ClusterSecretStore configured, applications request secrets via ExternalSecret resources. These live in Git - they contain references to secrets, not the values themselves.

Basic pattern - single secret:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: redis-credentials
  namespace: redis
spec:
  refreshInterval: 15m
  secretStoreRef:
    name: infisical-cluster-secretstore
    kind: ClusterSecretStore
  target:
    name: redis-credentials
    creationPolicy: Owner
  data:
    - secretKey: password
      remoteRef:
        key: "/redis/REDIS_PASSWORD"

Multiple secrets in one resource:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: minio-credentials
  namespace: minio
spec:
  refreshInterval: 15m
  secretStoreRef:
    name: infisical-cluster-secretstore
    kind: ClusterSecretStore
  target:
    name: minio-credentials
  data:
    - secretKey: rootUser
      remoteRef:
        key: "/minio/MINIO_ROOT_USER"
    - secretKey: rootPassword
      remoteRef:
        key: "/minio/MINIO_ROOT_PASSWORD"

Templated secrets with labels:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: gitlab-repo-credentials
  namespace: argocd
spec:
  refreshInterval: 15m
  secretStoreRef:
    name: infisical-cluster-secretstore
    kind: ClusterSecretStore
  target:
    name: gitlab-repo
    creationPolicy: Owner
    template:
      metadata:
        labels:
          argocd.argoproj.io/secret-type: repository
      data:
        type: git
        url: https://gitlab.com/your-org/your-repo.git
        username: "{{ .username }}"
        password: "{{ .password }}"
  data:
    - secretKey: username
      remoteRef:
        key: "/gitlab/DEPLOY_TOKEN_USERNAME"
    - secretKey: password
      remoteRef:
        key: "/gitlab/DEPLOY_TOKEN_PASSWORD"

The template feature lets you construct complex secrets combining static values with fetched values.

Related: See GitLab Runner on Kubernetes for a practical example using ExternalSecrets for runner authentication.

Organising Secrets in Infisical

Organise secrets by path for clarity:

Path	Purpose
`/argocd/`	ArgoCD admin credentials
`/gitlab/`	GitLab deploy tokens, runner tokens
`/redis/`	Redis authentication
`/minio/`	Object storage credentials
`/grafana/`	Monitoring credentials
`/cert-manager/`	DNS challenge credentials

The pattern: /<application>/<SECRET_NAME>. Clear, searchable, and easy to scope access.

Types of secrets to store:

Service credentials: Database passwords, cache auth, object storage keys
Platform tokens: Deploy tokens, runner registration tokens
Cloud credentials: IAM keys for cert-manager DNS validation
Application secrets: API keys, admin passwords

The Refresh Cycle

ESO polls on an interval, not continuously. Use refreshInterval: 15m for most secrets:

Secret rotation takes up to 15 minutes to propagate
Reduces API calls to Infisical
Acceptable latency for most use cases

Lower the interval for critical secrets requiring faster rotation. Increase it for static secrets that rarely change.

Security Considerations

What's protected:

No secrets in Git - ExternalSecrets reference paths, not values
Machine identity credentials never committed
Infisical handles encryption at rest and in transit

What's not protected:

Kubernetes Secrets are base64 encoded, not encrypted (unless you enable encryption at rest)
Anyone with cluster access can read synced secrets
The secret zero problem is pushed to the operator, not eliminated

Recommendations:

Enable Kubernetes encryption at rest for Secrets
Use RBAC to restrict secret access by namespace
Consider Sealed Secrets or SOPS for secrets that must be in Git
Audit Infisical access logs periodically

The Complete Flow

Putting it all together:

Setup (one-time): Create machine identity in Infisical, store client ID/secret locally
Bootstrap: Script authenticates via CLI, fetches initial secrets, installs cluster components
ESO Install: External Secrets Operator deployed to cluster
Credentials: Create the infisical-credentials Kubernetes Secret
ClusterSecretStore: Configure ESO to connect to Infisical
ExternalSecrets: Deploy manifests that reference secrets by path
Sync: ESO watches ExternalSecrets, creates Kubernetes Secrets
Consumption: Pods mount secrets normally - they don't know the source

Applications see standard Kubernetes Secrets. ESO is the bridge.

What I'd Change

Secret versioning: Infisical supports secret versions. Pinning to specific versions would add safety during rotations.

Backup strategy: If Infisical is unavailable, ESO can't refresh secrets. Existing secrets persist, but new deployments might fail. A backup secret store would help.

Audit integration: Infisical has audit logs. Shipping these to your logging system would add visibility.

Workload identity: On cloud providers, workload identity (GKE, EKS IAM roles) eliminates the secret zero problem entirely.

This is Part 5 of the Homelab Kubernetes Series, covering secrets management patterns for Kubernetes. See also: GitLab Runner on Kubernetes for a practical example of using External Secrets.

Originally published at https://wsl-ui.octasoft.co.uk/blog/secrets-management-infisical-external-secrets

Service Mesh Adventures - Cilium, Istio Ambient, and the Ztunnel Saga

Ian Packard — Sat, 31 Jan 2026 17:39:49 +0000

This is the final part of my homelab series. We've covered the WSL/Hyper-V architecture, bootstrap scripts, and GitOps with ArgoCD. Now let's talk about the networking stack - and the ztunnel certificate issue that haunted me for weeks.

Why Both Cilium AND Istio?

A fair question. Cilium is a CNI that can do service mesh things. Istio is a service mesh. Why run both?

Cilium handles L3/L4:

Pod networking and IP address management
Network policies
eBPF-based observability (Hubble)
Fast packet processing

Istio handles L7:

mTLS between services (automatic encryption)
Request-level routing (headers, paths, retries)
Traffic splitting for canary deployments
Distributed tracing

You can do L7 with Cilium (via Envoy), and you can do basic networking with Istio. But in my experience, letting each tool do what it does best gives the cleanest result.

Also: I wanted to learn Istio's ambient mode. Running it alongside Cilium gave me that opportunity without replacing my working CNI.

Istio Ambient Mode: No Sidecars

Traditional Istio injects an Envoy sidecar into every pod. It works, but:

Every pod needs extra CPU/memory for the sidecar
Sidecar injection can cause deployment issues
Debugging gets complicated with two containers per pod

Ambient mode takes a different approach. Instead of sidecars, it uses:

ztunnel: A per-node DaemonSet that handles L4 mTLS
waypoint proxies: Optional per-service L7 proxies (only where needed)

For my homelab, this means dramatically lower resource usage. Most services just need mTLS, not full L7 features, so ztunnel handles them without any sidecars.

# Enable ambient mode on a namespace
apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  labels:
    istio.io/dataplane-mode: ambient

That's it. Pods in that namespace automatically get mTLS via ztunnel.

CNI Chaining: Making Them Play Nice

Running Cilium and Istio together requires CNI chaining. Both want to configure networking, so they need to cooperate.

The setup:

Cilium installs its CNI config as 05-cilium.conflist
Istio CNI installs as ZZ-istio-cni.conflist (the "ZZ" ensures it loads after Cilium)
Istio CNI chains onto Cilium rather than replacing it

# From istiod Helm values
cni:
  enabled: true
  chained: true
  cniConfFileName: "ZZ-istio-cni.conflist"

The Istio CNI doesn't do packet routing - Cilium handles that. It just sets up the identity and interception needed for ambient mode.

The Ztunnel Certificate Nightmare

Everything worked beautifully. For about a week. Then services started failing with TLS errors.

The symptoms:

Pods could start but couldn't communicate
Logs showed certificate validation failures
Restarting pods temporarily fixed it
The problem came back

After much debugging, I found the culprit: ztunnel workload certificates were expiring.

Istio issues short-lived certificates (24 hours by default) to workloads. These should auto-renew. But in certain conditions - especially after VM suspend/resume cycles - ztunnel's certificate renewal would fail silently.

The certificates would expire, mTLS would break, and nothing could talk to anything.

The Workaround: Weekly Restart

I couldn't find a proper fix. The issue seems related to how ztunnel handles time jumps and certificate state after VM hibernation. Even with chrony fixing the clock, ztunnel's internal state was sometimes corrupt.

My solution is crude but effective: a CronJob that restarts ztunnel weekly.

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ztunnel-restart
  namespace: istio-system
spec:
  schedule: "0 3 * * 0"  # Sunday at 3 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: kubectl
              image: bitnami/kubectl:latest
              command:
                - /bin/sh
                - -c
                - |
                  kubectl rollout restart daemonset/ztunnel -n istio-system
                  kubectl rollout status daemonset/ztunnel -n istio-system --timeout=300s
          restartPolicy: OnFailure
          serviceAccountName: ztunnel-restart-sa

Is this ideal? No. Does it work? Yes. The rolling restart refreshes certificates and clears any stale state. I haven't had a certificate-related outage since.

I also added alerts so I know if ztunnel is unhealthy between restarts:

# Prometheus alert rule
- alert: ZtunnelCertificateExpiringSoon
  expr: |
    istio_agent_cert_expiry_seconds{app="ztunnel"} < 3600
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Ztunnel certificate expiring soon"

Gateway API: The Modern Ingress

I use Gateway API instead of traditional Ingress resources. It's the future standard and works well with Istio.

The setup:

# Gateway definition
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: istio-ingress
spec:
  gatewayClassName: istio
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: homelab-tls-cert
      allowedRoutes:
        namespaces:
          from: All

Services expose themselves with HTTPRoutes:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: grafana
  namespace: monitoring
spec:
  parentRefs:
    - name: main-gateway
      namespace: istio-ingress
  hostnames:
    - "grafana.homelab.example.com"
  rules:
    - backendRefs:
        - name: grafana
          port: 3000

This is cleaner than Ingress annotations. Each service owns its routing configuration.

MetalLB: LoadBalancer on Bare Metal

The Gateway needs an external IP. On cloud providers, you'd get a LoadBalancer automatically. On bare metal (or a Hyper-V VM), you need MetalLB.

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: homelab-pool
  namespace: metallb-system
spec:
  addresses:
    - 192.168.100.200-192.168.100.220
  autoAssign: true

---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: homelab-advertisement
  namespace: metallb-system
spec:
  ipAddressPools:
    - homelab-pool

The IP range is on the same network as the VM (192.168.100.0/24). MetalLB uses L2 advertisement (ARP) to announce these IPs. From WSL2, I can reach 192.168.100.200 (the Gateway's IP) directly.

Combined with a wildcard DNS record (*.homelab.example.com -> 192.168.100.200), every service gets its own hostname automatically.

TLS with Let's Encrypt

cert-manager handles TLS certificates automatically:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - dns01:
          route53:
            region: eu-west-2
            hostedZoneID: YOUR_ZONE_ID

I use DNS-01 challenges via Route 53. This works even though the services are private - Let's Encrypt validates DNS ownership, not HTTP reachability.

The Gateway's TLS certificate auto-renews every 60 days. No manual intervention needed.

The Full Networking Stack

Here's how a request flows:

Observability

With this stack, I get observability at multiple layers:

Cilium Hubble: L3/L4 network flows, DNS queries, dropped packets
Istio telemetry: L7 request rates, latencies, error rates
Grafana dashboards: Everything visualised

Hubble is particularly useful for debugging. You can see exactly which pods are talking to which services and whether traffic is being allowed or denied.

Lessons Learned

1. Ambient mode is promising but young. The ztunnel certificate issue is a real pain. I'm betting on upstream fixes, but for now, the weekly restart workaround is necessary.

2. CNI chaining works, but read the docs carefully. The order matters, the config file names matter, and debugging is harder when two CNIs are involved.

3. Gateway API is worth adopting. It's cleaner than Ingress, more expressive, and becoming the standard. Start using it now.

4. Start simple, add complexity later. I could have run just Cilium without Istio. Adding the service mesh was a learning exercise. For a production homelab, consider whether you actually need L7 features.

What's Next for This Homelab

Things I want to improve:

Multi-node cluster: Currently single-node. Adding worker nodes would let me test HA patterns and node failure scenarios.
Better alerting: The current setup has basic alerts. I want smarter alert routing and better runbooks.
Fix ztunnel properly: Keep watching upstream Istio for fixes to the certificate renewal issues.
ArgoCD multi-namespace: When ApplicationSets support multi-namespace properly, reorganise the GitOps structure.

Wrapping Up

This homelab journey started because I wanted to run Kubernetes on my Windows machine. I ended up with:

A Hyper-V VM because WSL2 networking doesn't support proper CNIs
WSL2 mirrored networking for seamless access
K3s with Cilium and Istio ambient mode
Full GitOps with ArgoCD's app-of-apps pattern
Automatic TLS with Let's Encrypt
Comprehensive observability

Is it over-engineered for a homelab? Probably. But I've learned a ton about Kubernetes networking, service meshes, and GitOps patterns. And I have a platform where I can deploy and test anything I'm working on.

If you're considering a similar setup, I hope this series helps you avoid some of the pitfalls I hit. Good luck, and may your certificates never expire unexpectedly.

This concludes the 4-part series on building a homelab Kubernetes setup on Windows. Thanks for reading!

Originally published at https://wsl-ui.octasoft.co.uk/blog/homelab-part-4-service-mesh

GitOps All The Things - ArgoCD and the App-of-Apps Pattern

Ian Packard — Sat, 31 Jan 2026 17:39:08 +0000

The bootstrap script from Part 2 gave us a cluster with ArgoCD installed. But ArgoCD is just sitting there, doing nothing. In this post, I'll explain how I use the app-of-apps pattern to deploy and manage everything else.

The Problem: Too Many Things to Deploy

My homelab runs a lot of stuff:

Istio service mesh (4 components with specific ordering)
cert-manager for TLS certificates
MetalLB for LoadBalancer services
PostgreSQL, Kafka, Redis, MinIO
Grafana, Loki, Tempo, Mimir (the LGTM observability stack)
A private Docker registry
GitLab runners for CI/CD
And more...

I could deploy each of these manually with helm install and kubectl apply. But that's not GitOps. And it's definitely not repeatable when I inevitably nuke the cluster and start over.

The Solution: App-of-Apps

The app-of-apps pattern is simple: create one ArgoCD Application that points to a directory of other Application manifests. ArgoCD reads the directory, creates all the Applications it finds, and each of those Applications deploys their respective workloads.

One Application to rule them all.

Bootstrapping with OpenTofu

The catch-22: ArgoCD needs the app-of-apps Application to exist, but we can't create it via GitOps because ArgoCD isn't managing anything yet.

I use OpenTofu (Terraform fork) to create the initial app-of-apps:

resource "argocd_application" "app_of_apps" {
  metadata {
    name      = "app-of-apps"
    namespace = "argocd"
  }

  spec {
    project = "default"

    source {
      repo_url        = "https://gitlab.com/your-org/homelab.git"
      path            = "argocd-apps"
      target_revision = "main"
      directory {
        recurse = true
      }
    }

    destination {
      server    = "https://kubernetes.default.svc"
      namespace = "argocd"
    }

    sync_policy {
      automated {
        prune     = true
        self_heal = true
      }
      retry {
        limit = 5
        backoff {
          duration     = "5s"
          max_duration = "3m"
          factor       = 2
        }
      }
    }
  }
}

After tofu apply, ArgoCD picks up the app-of-apps, reads the argocd-apps/ directory, and starts creating Applications.

Sync Waves: Order Matters

Some things need to be installed before others. You can't configure Istio routing until Istio is installed. You can't create Certificates until cert-manager is running.

ArgoCD's sync waves solve this. Each Application gets a sync wave annotation:

# istio-base.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: istio-base
  annotations:
    argocd.argoproj.io/sync-wave: "1"
spec:
  source:
    repoURL: https://istio-release.storage.googleapis.com/charts
    chart: base
    targetRevision: 1.23.2
  # ...

# istio-cni.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: istio-cni
  annotations:
    argocd.argoproj.io/sync-wave: "2"
# ...

# istiod.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: istiod
  annotations:
    argocd.argoproj.io/sync-wave: "3"
# ...

ArgoCD deploys wave 1 first, waits for it to be healthy, then wave 2, and so on. For Istio, this means:

istio-base (CRDs and basic resources)
istio-cni (CNI plugin for ambient mode)
istiod (control plane)
ztunnel (ambient mode data plane)

Without sync waves, ArgoCD would try to deploy everything at once and fail because CRDs don't exist yet.

Multisource Applications

Some deployments need both a Helm chart AND custom manifests. For example, MinIO needs:

The official MinIO Helm chart
Custom HTTPRoute for Gateway API ingress
ExternalSecret to pull credentials from Infisical

ArgoCD's multisource feature handles this:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: minio
spec:
  sources:
    # Source 1: Official Helm chart
    - repoURL: https://charts.min.io/
      chart: minio
      targetRevision: 5.4.0
      helm:
        values: |
          mode: standalone
          replicas: 1
          resources:
            requests:
              memory: 512Mi

    # Source 2: Custom manifests from our repo
    - repoURL: https://gitlab.com/your-org/homelab.git
      path: manifests
      targetRevision: main
      directory:
        include: "minio-*.yaml"

  destination:
    server: https://kubernetes.default.svc
    namespace: minio

The directory.include pattern lets me keep all my custom manifests in one manifests/ directory while only pulling the relevant ones for each application.

Self-Healing and Auto-Sync

Every Application has automated sync enabled:

sync_policy:
  automated:
    prune: true      # Delete resources removed from git
    self_heal: true  # Revert manual changes

This is GitOps in action. If someone manually edits a deployment, ArgoCD reverts it. If I delete an Application YAML from git, ArgoCD removes it from the cluster.

The retry policy is important for the initial deployment:

retry:
  limit: 5
  backoff:
    duration: "5s"
    max_duration: "3m"
    factor: 2

Some Applications fail on first sync because dependencies aren't ready yet. The exponential backoff gives things time to settle.

A Typical Application Manifest

Here's what a standard Application looks like:

# cert-manager.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cert-manager
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default

  source:
    repoURL: https://charts.jetstack.io
    chart: cert-manager
    targetRevision: v1.16.2
    helm:
      values: |
        crds:
          enabled: true
        resources:
          requests:
            cpu: 10m
            memory: 32Mi

  destination:
    server: https://kubernetes.default.svc
    namespace: cert-manager

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Key points:

finalizers: Ensures resources are cleaned up when Application is deleted
CreateNamespace=true: ArgoCD creates the namespace if it doesn't exist
Resource requests are tuned low - this is a homelab, not production

The argocd-apps Directory Structure

argocd-apps/
├── argo-platform.yaml          # ArgoCD configuration
├── argo-projects.yaml          # ArgoCD projects
├── argo-repos.yaml             # Repository credentials
│
├── istio-base.yaml             # Sync wave 1
├── istio-cni.yaml              # Sync wave 2
├── istiod.yaml                 # Sync wave 3
├── ztunnel.yaml                # Sync wave 4
├── istio-gateway.yaml          # Gateway configuration
│
├── cilium.yaml                 # CNI management
├── metallb-system.yaml         # Load balancer
├── cert-manager.yaml           # TLS certificates
├── letsencrypt.yaml            # ACME issuer
│
├── postgres.yaml               # Database
├── kafka.yaml                  # Event streaming
├── redis-multisource.yaml      # Cache + custom routes
├── minio-multisource.yaml      # Object storage
│
├── lgtm-stack.yaml             # Observability
├── k8s-monitoring.yaml         # Metrics
│
└── ... (and more)

30+ Applications, all managed from one directory. Add a new YAML file, commit, push, and ArgoCD deploys it.

External Secrets Integration

I mentioned ExternalSecrets for MinIO. Here's how that works:

# manifests/minio-external-secret.yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: minio-credentials
  namespace: minio
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: infisical-store
    kind: ClusterSecretStore
  target:
    name: minio-credentials
  data:
    - secretKey: rootUser
      remoteRef:
        key: /minio/MINIO_ROOT_USER
    - secretKey: rootPassword
      remoteRef:
        key: /minio/MINIO_ROOT_PASSWORD

Infisical holds the actual credentials. External Secrets Operator syncs them into Kubernetes Secrets. The Helm chart references the Secret. No credentials in git.

The Joy of Drift Detection

My favourite ArgoCD feature is seeing when something drifts from the desired state. Someone manually scaled a deployment? ArgoCD shows it as "OutOfSync" and reverts it.

This has saved me multiple times when I "temporarily" changed something and forgot to revert it.

What I'd Change

ArgoCD multi-namespace support: Currently, all Applications live in the argocd namespace. There's work in progress to support Applications in other namespaces, which would be cleaner for multi-tenant setups. When that lands, I'll reorganise.

Application sets: For similar applications (like per-environment deployments), ApplicationSets would reduce duplication. I haven't needed it yet for this homelab, but it's on the list.

What's Next

The cluster is now deploying applications automatically. But we haven't talked about the service mesh yet - Cilium and Istio running together, and the ztunnel certificate issues that caused me grief. That's Part 4.

This is Part 3 of a 4-part series on building a homelab Kubernetes setup on Windows.

Originally published at https://wsl-ui.octasoft.co.uk/blog/homelab-part-3-gitops

From Zero to K3s - Bootstrap Scripts and Time Sync Nightmares

Ian Packard — Sat, 31 Jan 2026 17:38:11 +0000

In Part 1, I explained why my homelab runs in a Hyper-V VM instead of WSL2. Now let's talk about how I actually bootstrap the cluster - and the time synchronisation issue that had me questioning my life choices.

The Goal: One Script to Rule Them All

I wanted a single bootstrap.sh that could take a fresh Ubuntu VM and produce a working Kubernetes cluster with:

K3s as the distribution
Cilium as the CNI (with Hubble for observability)
Gateway API CRDs installed
External Secrets Operator for secrets management
ArgoCD for GitOps

The script needed to be idempotent - safe to run multiple times. Because you will run it multiple times while debugging.

Phase-Based Installation

The bootstrap script runs in phases. Each phase completes fully before the next begins, and each phase can be re-run independently if needed.

This structure saved me countless hours. When something broke in Phase 4, I didn't have to start from scratch.

Phase 0: The Time Sync Disaster

Let me tell you about the most frustrating bug I've encountered in this entire project.

Everything would work perfectly after a fresh install. Then I'd close my laptop, come back the next day, resume the VM, and chaos. Pods failing. Certificate errors everywhere. DNS not resolving. ArgoCD unable to sync.

The culprit? Time drift.

Hyper-V VMs don't maintain accurate time when suspended. When you resume a VM that's been asleep for hours, the VM's clock can be significantly off. And Kubernetes really doesn't like that:

TLS certificates appear expired (or not yet valid)
Tokens fail validation
Let's Encrypt challenges time out
Istio's mTLS goes haywire

The fix is chrony, configured aggressively for VM environments:

setup_time_sync() {
    sudo apt-get install -y chrony

    # Configure for VM environment with aggressive correction
    sudo tee /etc/chrony/chrony.conf > /dev/null <<EOF
server time.google.com iburst
server time.cloudflare.com iburst
server pool.ntp.org iburst

# Allow instant time correction for any offset up to 1 day
makestep 86400 -1

# Log any time changes larger than 0.5 seconds
logchange 0.5
EOF

    sudo systemctl restart chrony
}

The key is makestep 86400 -1. This tells chrony to immediately step the clock (rather than gradually adjusting) for any offset up to 86400 seconds (24 hours), with no limit on how many times it can do this.

After adding this, resume-from-suspend just works. Clock jumps forward, chrony notices, fixes it immediately, and everything continues.

Reference ID    : A29FC801 (time.cloudflare.com)
Stratum         : 4
Ref time (UTC)  : Thu Jan 16 10:23:45 2026
System time     : 0.000000023 seconds fast of NTP time
Last offset     : +0.000000012 seconds
RMS offset      : 0.000000156 seconds
Frequency       : 1.234 ppm slow
Residual freq   : +0.000 ppm
Skew            : 0.012 ppm
Root delay      : 0.012345678 seconds
Root dispersion : 0.000123456 seconds
Update interval : 1024.0 seconds
Leap status     : Normal

Phase 2: K3s Installation

K3s is delightfully simple to install, but needs specific flags for our setup:

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server \
  --bind-address=${VM_IP} \
  --advertise-address=${VM_IP} \
  --disable=traefik \
  --flannel-backend=none \
  --disable-network-policy \
  --cluster-cidr=10.42.0.0/16 \
  --service-cidr=10.43.0.0/16 \
  --write-kubeconfig-mode=644" sh -

Why these flags:

--bind-address / --advertise-address: Bind to VM IP, not localhost, so WSL2 can reach it
--disable=traefik: We're using Istio Gateway, not Traefik
--flannel-backend=none: Disables K3s's default CNI - we're using Cilium
--disable-network-policy: Cilium handles network policies
--write-kubeconfig-mode=644: Makes kubeconfig readable without sudo

The script also updates the kubeconfig to use the VM's IP:

kubectl config set-cluster default --server=https://${VM_IP}:6443

Phase 3: Cilium Bootstrap

With K3s running but no CNI, pods are stuck in Pending. Time to install Cilium:

cilium install --version "1.18.1" \
    --set cluster.name="homelab" \
    --set cluster.id="1" \
    --set cni.exclusive=false \
    --set hubble.enabled=true \
    --set hubble.relay.enabled=true \
    --set hubble.ui.enabled=true

The cni.exclusive=false is important - it allows CNI chaining, which we need later when Istio's CNI joins the party.

After installation, the script waits for DNS to actually work:

verify_cilium_functionality() {
    # Wait for CoreDNS pods
    kubectl -n kube-system wait --for=condition=ready pod -l k8s-app=kube-dns --timeout=120s

    # Test actual DNS resolution
    for i in {1..30}; do
        if kubectl run dns-test --image=busybox:1.36 --rm -it --restart=Never \
            -- nslookup kubernetes.default.svc.cluster.local; then
            echo "DNS is working"
            return 0
        fi
        sleep 10
    done
    echo "DNS verification failed"
    return 1
}

This caught so many race conditions. CoreDNS pods can be "Ready" but not actually resolving queries yet.

Phase 4: CRDs and External Secrets

Before ArgoCD can deploy anything, we need:

Gateway API CRDs:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml

External Secrets Operator (for pulling secrets from Infisical):

helm install external-secrets external-secrets/external-secrets \
    -n external-secrets --create-namespace \
    --set resources.requests.cpu=10m \
    --set resources.requests.memory=32Mi

I use Infisical as my secrets backend. The External Secrets Operator syncs secrets into Kubernetes automatically. No more committing secrets to git or manually creating them.

Phase 5: ArgoCD

Finally, ArgoCD:

helm install argocd argo/argo-cd \
    -n argocd --create-namespace \
    --set server.service.type=ClusterIP \
    --set configs.secret.argocdServerAdminPassword="$BCRYPT_PASSWORD" \
    --set controller.args.appResyncPeriod=60

The admin password comes from Infisical, fetched at the start of the bootstrap:

ARGOCD_PASSWORD=$(infisical secrets get ARGOCD_ADMIN_PASSWORD \
    --env=dev --projectId="${PROJECT_ID}" --plain)

The Full Flow

Here's what running the bootstrap looks like:

$ ./bootstrap.sh

Phase 0: System Prerequisites
  ✓ Installing chrony for time synchronisation
  ✓ Time sync configured and verified

Phase 1: Validation & Setup
  ✓ Infisical credentials validated
  ✓ ArgoCD password retrieved
  ✓ VM IP detected: 192.168.100.2
  ✓ External connectivity verified

Phase 2: K3s Installation
  ✓ Cleaning up any existing K3s installation
  ✓ Installing K3s (no CNI)
  ✓ Kubeconfig configured for external access

Phase 3: Cilium CNI
  ✓ Installing Cilium v1.18.1
  ✓ Waiting for Cilium to be ready
  ✓ DNS resolution verified

Phase 4: CRDs & Operators
  ✓ Gateway API CRDs installed
  ✓ External Secrets Operator deployed

Phase 5: ArgoCD
  ✓ ArgoCD installed
  ✓ ArgoCD server ready

Bootstrap complete!

Configuration Management

All the cluster-specific values live in a config.env file:

CLUSTER_NAME="homelab"
CLUSTER_ID="1"
CLUSTER_CIDR="10.42.0.0/16"
SERVICE_CIDR="10.43.0.0/16"
CILIUM_VERSION="1.18.1"

The bootstrap script sources this and uses the values throughout. Makes it easy to spin up a second cluster with different settings.

Lessons Learned

Time sync is critical - Add it to Phase 0 and never think about it again
Phase-based scripts save sanity - Isolate failures, enable partial re-runs
DNS verification is not optional - Don't assume CoreDNS is ready just because pods are running
Bind to real IPs - Localhost doesn't cut it when you're accessing from WSL2
Idempotency matters - You will run the script many times

What's Next

The cluster is up, but it's empty. In Part 3, I'll cover how ArgoCD and the app-of-apps pattern deploys everything else - Istio, cert-manager, monitoring, and all the applications.

This is Part 2 of a 4-part series on building a homelab Kubernetes setup on Windows.

Originally published at https://wsl-ui.octasoft.co.uk/blog/homelab-part-2-bootstrap

The Great WSL Escape - Why My Homelab Runs in a Hyper-V VM

Ian Packard — Sat, 31 Jan 2026 17:36:39 +0000

I wanted to run Kubernetes on my Windows machine. How hard could it be?

Turns out, harder than expected. This is the story of why my homelab now runs in a Hyper-V VM instead of directly in WSL2, and the networking tricks that make it all work seamlessly.

The Dream: K8s in WSL2

The appeal was obvious. WSL2 is right there, it runs Linux, and I already use it for everything else. Docker Desktop works fine in WSL2. Minikube kind of works. So surely I could run a proper K3s cluster with Cilium as my CNI and Istio for the service mesh?

Not so much.

The CNI Reality Check

Here's where the dream died: CNI plugins.

WSL2 uses a virtualised network adapter managed by Windows. It's not a real Linux network namespace. When you try to run Cilium (or Calico, or most production-grade CNIs), they expect to do things like:

Create eBPF maps and attach them to network interfaces
Manipulate iptables and routing tables
Manage network namespaces for pods

WSL2's networking layer doesn't play nicely with any of this. Cilium would partially install, then DNS would break. Or pods would start but couldn't talk to services. Or everything would work until you restarted WSL.

I spent more hours than I'd like to admit trying different combinations of CNI configurations, WSL kernel parameters, and creative workarounds. Eventually I accepted the truth: WSL2 wasn't designed for this.

The Pivot: Hyper-V VM

Windows ships with Hyper-V. It's a proper Type 1 hypervisor. And unlike WSL2's abstracted networking, a Hyper-V VM gets real virtual network adapters that behave like actual Linux networking.

So I created an Ubuntu VM with a static IP on an internal NAT network. The VM could run Cilium properly, eBPF worked, and suddenly Kubernetes networking behaved like it should.

Problem solved? Almost.

The New Problem: How Do I Access This Thing?

Now I had a working Kubernetes cluster, but it was isolated in a Hyper-V VM on a NAT network. From my Windows host I could reach it. But from WSL2 - where I actually do my development work - the VM was unreachable.

By default, WSL2 runs on its own virtual network (something like 172.x.x.x) that has no route to the Hyper-V internal network (192.168.100.0/24 in my case). I could set up port forwarding, or run a proxy, or configure complex routing rules...

Or I could use WSL2's mirrored networking mode.

WSL2 Mirrored Networking: The Key

This was the game-changer. In your .wslconfig file:

[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

With mirrored networking, WSL2 shares the Windows host's network interfaces. It can see everything Windows can see - including the Hyper-V internal network. No port forwarding. No routing hacks. Just direct connectivity.

# From WSL2, I can now directly reach the VM
ping 192.168.100.2
kubectl get nodes  # Works with kubeconfig pointing to VM IP

This requires Windows 11 22H2 or later (or Windows 10 with recent updates), but if you're doing homelab stuff in 2026, you probably have that.

The Network Architecture

Here's what the final setup looks like:

Key points:

VM has static IP (192.168.100.2) - no DHCP surprises
WSL2 in mirrored mode - can directly reach VM without port forwarding
Internal NAT network - VM has internet access but isn't exposed externally
K3s bound to VM IP - not localhost, so WSL2 can reach the API server

Setting Up the Hyper-V Network

I created PowerShell scripts to make this repeatable. The NAT setup:

# Create internal switch
New-VMSwitch -SwitchName "HomeLab" -SwitchType Internal

# Configure host IP on the switch
$adapter = Get-NetAdapter | Where-Object { $_.Name -like "*HomeLab*" }
New-NetIPAddress -IPAddress 192.168.100.1 -PrefixLength 24 -InterfaceIndex $adapter.ifIndex

# Create NAT rule for internet access
New-NetNat -Name "HomeLabNAT" -InternalIPInterfaceAddressPrefix 192.168.100.0/24

The scripts are idempotent - safe to run multiple times if you're iterating on the setup.

K3s Configuration for External Access

One gotcha: K3s by default binds to 127.0.0.1 for the API server. That doesn't work when you need to access it from WSL2. The install command needs explicit bind and advertise addresses:

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server \
  --bind-address=192.168.100.2 \
  --advertise-address=192.168.100.2 \
  --disable=traefik \
  --flannel-backend=none \
  --disable-network-policy" sh -

The --flannel-backend=none is because we're using Cilium instead of K3s's default networking.

Was It Worth It?

Absolutely. Yes, it's more moving parts than running K8s directly in WSL2 (if that worked). But I now have:

A proper Kubernetes cluster with real CNI support
Cilium with eBPF working correctly
Istio ambient mode (no sidecars!)
MetalLB for LoadBalancer services
Full GitOps with ArgoCD

And from WSL2, it feels native. kubectl commands just work. I can port-forward, exec into pods, tail logs - all the normal stuff.

What's Next

In Part 2, I'll cover the bootstrap process - how I go from a fresh VM to a working cluster with a single script. Including the time synchronisation nightmare that cost me several hours of debugging.

This is Part 1 of a 4-part series on building a homelab Kubernetes setup on Windows.

Originally published at https://wsl-ui.octasoft.co.uk/blog/homelab-part-1-the-great-wsl-escape