Skip to content

Instantly share code, notes, and snippets.

@Lupus

Lupus/wsl2-custom-kernel-rancher-desktop-cilium.md

Created September 18, 2025 07:19
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Lupus/ac3c370dea6c51f85d54751b8d35d950 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Lupus/ac3c370dea6c51f85d54751b8d35d950 to your computer and use it in GitHub Desktop.
Download ZIP
WSL2 Custom Kernel Build Guide for Cilium with Rancher Desktop
Raw
wsl2-custom-kernel-rancher-desktop-cilium.md

WSL2 Custom Kernel Build Guide for Cilium with Rancher Desktop

Overview

This guide documents the complete process of building a custom WSL2 kernel with Cilium support and integrating it with Rancher Desktop's K3s distribution. The custom kernel enables full Cilium functionality including L7 proxy features, eBPF acceleration, and advanced networking capabilities.

Prerequisites

  • Windows 11 22H2 or later
  • WSL2 installed and updated to latest version
  • Rancher Desktop installed
  • Ubuntu 22.04 or 24.04 WSL2 instance for kernel building

Part 1: Kernel Build Playbook

Step 1: Update WSL2 and Create Build Environment

# Update WSL to latest version
wsl --update
wsl --version

# Install Ubuntu for kernel building (if not already installed)
wsl --install -d Ubuntu-22.04

Step 2: Install Build Dependencies

In your Ubuntu WSL2 instance:

sudo apt update && sudo apt install -y \
  build-essential \
  flex \
  bison \
  libssl-dev \
  libelf-dev \
  bc \
  dwarves \
  cpio \
  qemu-utils \
  python3 \
  pahole

Step 3: Clone WSL2 Kernel Source

Clone the latest 6.6 LTS kernel branch:

# Clone the specific tag matching your current kernel
git clone https://github.com/microsoft/WSL2-Linux-Kernel.git \
  --depth=1 -b linux-msft-wsl-6.6.87.2

cd WSL2-Linux-Kernel

Step 4: Apply Cilium Kernel Configurations

Create and run the configuration script that adds all required Cilium options:

cat << 'EOF' > configure_cilium.sh
#!/bin/bash

# Core eBPF requirements (Essential)
sed -i 's/# CONFIG_BPF_JIT is not set/CONFIG_BPF_JIT=y/' Microsoft/config-wsl
echo "CONFIG_BPF_JIT_ALWAYS_ON=y" >> Microsoft/config-wsl
echo "CONFIG_BPF_JIT_DEFAULT_ON=y" >> Microsoft/config-wsl

# L7 Proxy requirements (Essential for Cilium L7 features)
sed -i 's/# CONFIG_NETFILTER_XT_MATCH_RECENT is not set/CONFIG_NETFILTER_XT_MATCH_RECENT=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_TARGET_TPROXY is not set/CONFIG_NETFILTER_XT_TARGET_TPROXY=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_TARGET_CT is not set/CONFIG_NETFILTER_XT_TARGET_CT=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_MATCH_MARK is not set/CONFIG_NETFILTER_XT_MATCH_MARK=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_MATCH_SOCKET is not set/CONFIG_NETFILTER_XT_MATCH_SOCKET=m/' Microsoft/config-wsl

# Additional L7/networking requirements
sed -i 's/# CONFIG_NETFILTER_XT_TARGET_MARK is not set/CONFIG_NETFILTER_XT_TARGET_MARK=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_MATCH_COMMENT is not set/CONFIG_NETFILTER_XT_MATCH_COMMENT=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_NETFILTER_XT_SET is not set/CONFIG_NETFILTER_XT_SET=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_IP_SET is not set/CONFIG_IP_SET=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_IP_SET_HASH_IP is not set/CONFIG_IP_SET_HASH_IP=m/' Microsoft/config-wsl

# XDP acceleration support
echo "CONFIG_INET_DIAG=y" >> Microsoft/config-wsl
echo "CONFIG_INET_UDP_DIAG=y" >> Microsoft/config-wsl
echo "CONFIG_INET_DIAG_DESTROY=y" >> Microsoft/config-wsl

# VXLAN overlay networking
sed -i 's/# CONFIG_VXLAN is not set/CONFIG_VXLAN=m/' Microsoft/config-wsl

# Bandwidth Manager
sed -i 's/# CONFIG_NET_SCH_FQ is not set/CONFIG_NET_SCH_FQ=m/' Microsoft/config-wsl

# IPsec encryption support
sed -i 's/# CONFIG_XFRM_STATISTICS is not set/CONFIG_XFRM_STATISTICS=y/' Microsoft/config-wsl
sed -i 's/# CONFIG_INET_ESP is not set/CONFIG_INET_ESP=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_INET_ESP_OFFLOAD is not set/CONFIG_INET_ESP_OFFLOAD=m/' Microsoft/config-wsl
sed -i 's/# CONFIG_INET_ESPINTCP is not set/CONFIG_INET_ESPINTCP=y/' Microsoft/config-wsl

# Additional requirements for modern Cilium
echo "CONFIG_FIB_RULES=y" >> Microsoft/config-wsl
echo "CONFIG_CRYPTO_SHA1=y" >> Microsoft/config-wsl
echo "CONFIG_CRYPTO_USER_API_HASH=y" >> Microsoft/config-wsl

# Version identification
echo 'CONFIG_LOCALVERSION="-cilium-6.6.87.2"' >> Microsoft/config-wsl

echo "Cilium kernel configuration applied successfully!"
EOF

chmod +x configure_cilium.sh
./configure_cilium.sh

Step 5: Build the Kernel

# Build kernel with parallel jobs
make -j$(nproc) KCONFIG_CONFIG=Microsoft/config-wsl

# Build and install modules (required for 6.6 kernel series)
make INSTALL_MOD_PATH="$PWD/modules" modules_install

# Create modules VHDX
sudo ./Microsoft/scripts/gen_modules_vhdx.sh \
  "$PWD/modules" \
  $(make -s kernelrelease) \
  modules-cilium.vhdx

Step 6: Copy Build Artifacts to Windows

Replace YOUR_USERNAME with your actual Windows username:

# Create kernel directory in Windows filesystem
mkdir -p /mnt/c/Users/YOUR_USERNAME/.wsl-kernels/

# Copy kernel image (using the -builtin naming as in your config)
cp arch/x86/boot/bzImage /mnt/c/Users/YOUR_USERNAME/.wsl-kernels/bzImage-cilium-builtin

# Copy modules VHDX
cp modules-cilium.vhdx /mnt/c/Users/YOUR_USERNAME/.wsl-kernels/modules-cilium.vhdx

Step 7: Configure WSL2 to Use Custom Kernel

Create or update .wslconfig in your Windows user directory (C:\Users\YOUR_USERNAME\.wslconfig):

[wsl2]
# Custom kernel with Cilium support
kernel=C:\\Users\\YOUR_USERNAME\\.wsl-kernels\\bzImage-cilium-builtin
kernelModules=C:\\Users\\YOUR_USERNAME\\.wsl-kernels\\modules-cilium.vhdx

memory=16GB

# Windows 11 networking optimizations
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

[experimental]
# Performance improvements
autoMemoryReclaim=gradual
sparseVhd=true

Note: The localhostForwarding setting has no effect when using mirrored networking mode and can be omitted.

Step 8: Apply Configuration and Verify Kernel

# Shutdown WSL to apply new kernel
wsl --shutdown

# Start WSL and verify kernel
wsl
uname -r
# Should show: 6.6.87.2-cilium-6.6.87.2-microsoft-standard-WSL2

# Verify critical Cilium modules are configured
zgrep CONFIG_NETFILTER_XT_TARGET_TPROXY /proc/config.gz
zgrep CONFIG_BPF_JIT /proc/config.gz
# Both should return '=m' or '=y'

Part 2: Rancher Desktop Integration

Step 1: Reset Kubernetes in Rancher Desktop

After verifying the new kernel is working:

  1. Open Rancher Desktop UI
  2. Go to Kubernetes settings
  3. Click "Reset Kubernetes"
  4. This will re-create WSL instances and reinstall Kubernetes with the new kernel

Step 2: Create Cilium Provisioning Script

Create the provisioning script for Rancher Desktop to configure K3s for Cilium:

# In PowerShell, create the provisioning script
$provisioningPath = "$env:LOCALAPPDATA\rancher-desktop\provisioning"
New-Item -ItemType Directory -Path $provisioningPath -Force

# Create the provisioning script with Unix LF line endings
$scriptContent = @'
#!/bin/sh
set -e

# 1. Cilium mounts
echo "Setting up Cilium mount requirements..."

# Check and create BPF mount
if ! mount | grep -q "/sys/fs/bpf"; then
    mount bpffs -t bpf /sys/fs/bpf 2>/dev/null || true
    mount --make-shared /sys/fs/bpf 2>/dev/null || true
    echo "BPF filesystem mounted"
fi

# Check and create cgroup2 mount for Cilium
if [ ! -d "/run/cilium/cgroupv2" ]; then
    mkdir -p /run/cilium/cgroupv2
    mount -t cgroup2 none /run/cilium/cgroupv2 2>/dev/null || true
    mount --make-shared /run/cilium/cgroupv2/ 2>/dev/null || true
    echo "Cilium cgroup2 mounted"
fi

echo "Cilium mount setup completed"

# 2. Create K3s config directory
echo "[Cilium Setup] Preparing K3s configuration..."
mkdir -p /etc/rancher/k3s/config.yaml.d

# 3. Write K3s server config (will be used when K3s starts)
cat > /etc/rancher/k3s/config.yaml.d/99-cilium.yaml <<EOF
flannel-backend: "none"
disable-network-policy: true
disable:
  - servicelb
EOF

echo "[Cilium Setup] Provisioning completed successfully"
'@

# Write with Unix LF line endings (important for WSL/Linux scripts)
# PowerShell 5+ method to ensure LF line endings
$scriptContent -split "`r?`n" -join "`n" | Set-Content -NoNewline -Path "$provisioningPath\01-cilium-setup.start"

Important: The provisioning script must have Unix LF line endings since it will be executed in a Linux environment.

Step 3: Reset Kubernetes Again

After creating the provisioning script:

  1. Reset Kubernetes in Rancher Desktop UI once more
  2. This will apply the provisioning script and configure K3s for Cilium

Part 3: Install Cilium

Step 1: Setup kubectl Access from Ubuntu WSL

From your Ubuntu WSL instance:

# Create .kube directory if it doesn't exist
mkdir -p ~/.kube

# Copy kubeconfig from Windows
cp /mnt/c/Users/YOUR_USERNAME/.kube/config ~/.kube/config

# Verify kubectl works
kubectl get nodes

Step 2: Install Cilium CLI

# Install Cilium CLI
CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
curl -L --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-amd64.tar.gz
sudo tar xzvfC cilium-linux-amd64.tar.gz /usr/local/bin
rm cilium-linux-amd64.tar.gz

# Verify CLI installation
cilium version --client

Step 3: Install Cilium

# Install Cilium with default settings
cilium install

# Wait for Cilium to be ready
cilium status --wait

Step 4: Verify Cilium Installation

# Check Cilium status - should show all green
cilium status

# Run connectivity test (optional but recommended)
cilium connectivity test

Notes

  • The mirrored networking mode in Windows 11 eliminates most static IP configuration needs
  • The provisioning script runs automatically when Rancher Desktop starts
  • Cilium replaces K3s's default Flannel CNI and ServiceLB
  • All Cilium features including L7 proxy are available with this setup
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment