Using WSL2

Kind can run using Windows Subsystem for Linux 2 (WSL2) on Windows 10 May 2020 Update (build 19041).

All the tools needed to build or run kind work in WSL2, but some extra steps are needed to switch to WSL2. This page covers these steps in brief but also links to the official documentation if you would like more details.

Getting Windows 10 or 11 🔗︎

Download the latest ISO at https://www.microsoft.com/en-us/software-download/. Choose the latest Windows 10 or Windows 11 release.

Installing on a virtual machine 🔗︎

Required Settings

Now, start up the VM. Watch carefully for the “Press any key to continue installation…” screen so you don’t miss it. Windows Setup will start automatically.

Installing on a physical machine 🔗︎

If you’re using a physical machine, you can mount the ISO, copy the files to a FAT32 formatted USB disk, and boot from that instead. Be sure the machine is configured to boot using UEFI (not legacy BIOS), and has Intel VT or AMD-V enabled for the hypervisor.

Tips during setup 🔗︎

Setting up WSL2 🔗︎

If you want the full details, see the Installation Instructions for WSL2. This is the TL;DR version.

Once your Windows machine is ready, you need to do a few more steps to set up WSL2

  1. Open a PowerShell window as an admin, then run

     
    Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform, Microsoft-Windows-Subsystem-Linux

  2. Reboot when prompted.

  3. After the reboot, set WSL to default to WSL2. Open an admin PowerShell window and run 

    wsl --set-default-version 2

  4. Now, you can install your Linux distro of choice by searching the Windows Store. If you don’t want to use the Windows Store, then follow the steps in the WSL docs for manual install.

  5. Start up your distro with the shortcut added to the start menu

Setting up Docker in WSL2 with Docker Desktop 🔗︎

Install Docker with WSL2 backend here: https://docs.docker.com/docker-for-windows/wsl/

Setting up Docker in WSL2 without Docker Desktop 🔗︎

Alternatively, docker can be installed in WSL2 without using Docker Desktop. See for example: https://dev.to/bowmanjd/install-docker-on-windows-wsl-without-docker-desktop-34m9

Now, move on to the Quick Start to set up your cluster with kind.

Accessing a Kubernetes Service running in WSL2 🔗︎

  1. prepare cluster config with exported node port 

    # cluster-config.yml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30000
    hostPort: 30000
    protocol: TCP

  2. create cluster kind create cluster --config=cluster-config.yml

  3. create deployment kubectl create deployment nginx --image=nginx --port=80

  4. create service kubectl create service nodeport nginx --tcp=80:80 --node-port=30000

  5. access service curl localhost:30000

Alternatively, see Helpful Tips for WSL2

Kubernetes Service with Session Affinity 🔗︎

If you want to create a Kubernetes Service with sessionAffinity: ClientIP it will not be accessible (and neither will any Service created afterwards). WSL2 kernel is missing xt_recent kernel module, which is used by Kube Proxy to implement session affinity. You need to compile a custom kernel to enable this feature.

  1. Build a kernel with xt_recent kernel module enabled 

    docker run --name wsl-kernel-builder --rm -it ubuntu:latest bash

WSL_COMMIT_REF=linux-msft-wsl-5.15.146.1 # change this line to the version you want to build

# Install dependencies
apt update
apt install -y git build-essential flex bison libssl-dev libelf-dev bc dwarves python3

# Checkout WSL2 Kernel repo
mkdir src
cd src
git init
git remote add origin https://github.com/microsoft/WSL2-Linux-Kernel.git
git config --local gc.auto 0
git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin +${WSL_COMMIT_REF}:refs/remotes/origin/build/linux-msft-wsl-5.15.y
git checkout --progress --force -B build/linux-msft-wsl-5.15.y refs/remotes/origin/build/linux-msft-wsl-5.15.y

# Enable xt_recent kernel module
sed -i 's/# CONFIG_NETFILTER_XT_MATCH_RECENT is not set/CONFIG_NETFILTER_XT_MATCH_RECENT=y/' Microsoft/config-wsl

# Compile the kernel 
make -j2 KCONFIG_CONFIG=Microsoft/config-wsl

# From the host terminal copy the newly built kernel
docker cp wsl-kernel-builder:/src/arch/x86/boot/bzImage .

  2. Configure WSL to use newly built kernel: https://docs.microsoft.com/en-us/windows/wsl/wsl-config#configure-global-options-with-wslconfig

    Create a .wslconfig file in C:\Users\<your-user-name>\: 

    [wsl2]
kernel=c:\\path\\to\\your\\kernel\\bzImage

Helpful Tips for WSL2 🔗︎