Missing WSL2 setup documentation for running KubeEdge on Windows with Docker Desktop
- Dominant language
- MDX
- Stars
- 64
- Forks
- 203
- Avg merge
- 5d 22h
- Merged PRs (30d)
- 8
Description
## Problem
There is no documentation covering how to set up KubeEdge on Windows using WSL2 + Docker Desktop, which is a very common developer environment on Windows. Users attempting this setup hit several undocumented failures in sequence, with no official guidance available.
## Undocumented Requirements for WSL2
### 1. Systemd must be explicitly enabled
WSL2 does not run systemd by default. EdgeCore installs itself as a systemd service and requires systemd as PID 1. Without explicitly enabling it, `keadm join` appears to succeed but EdgeCore silently fails to start.
**Fix:**
```bash
sudo tee /etc/wsl.conf << 'EOF'
[boot]
systemd=true
EOF
# Then from Windows PowerShell:
wsl --shutdown
```
Verify with: `ps -p 1 -o comm=` — must output `systemd`.
### 2. Docker Desktop does not expose a containerd socket in WSL2
Even with Docker Desktop WSL2 integration fully enabled, there is no containerd socket at the default path `/run/containerd/containerd.sock`. EdgeCore fails immediately with:
```
dial unix /run/containerd/containerd.sock: connect: no such file or directory
```
Docker Desktop's containerd runs in an isolated context and is not accessible from within WSL2.
**Fix:** Install containerd natively inside WSL2:
```bash
sudo apt-get install -y containerd
sudo systemctl enable --now containerd
```
### 3. cgroupDriver must be changed to `systemd`
WSL2 uses cgroupv2. EdgeCore defaults to `cgroupDriver: cgroupfs` in the generated `edgecore.yaml`, which mismatches with cgroupv2 and causes ContainerManager startup to fail.
**Fix:** Edit `/etc/kubeedge/config/edgecore.yaml`:
```yaml
edged:
cgroupDriver: systemd # change from cgroupfs
```
### 4. failSwapOn must be set to `false`
WSL2 has swap enabled by default. EdgeCore inherits kubelet's swap validation, which fails on systems with swap active.
**Fix:** Edit `/etc/kubeedge/config/edgecore.yaml`:
```yaml
edged:
failSwapOn: false
```
### 5. CNI plugins must be installed manually
The edge node will remain in `NotReady` state unless CNI plugins are present at `/opt/cni/bin`. This is not mentioned in the quickstart.
**Fix:**
```bash
sudo mkdir -p /opt/cni/bin
wget https://github.com/containernetworking/plugins/releases/download/v1.5.0/cni-plugins-linux-amd64-v1.5.0.tgz -O /tmp/cni.tgz
sudo tar -xzf /tmp/cni.tgz -C /opt/cni/bin
sudo mkdir -p /etc/cni/net.d
sudo tee /etc/cni/net.d/10-bridge.conflist << 'EOF'
{
"cniVersion": "1.0.0",
"name": "edge-bridge",
"plugins": [
{
"type": "bridge",
"bridge": "cni0",
"isGateway": true,
"ipMasq": true,
"ipam": {
"type": "host-local",
"ranges": [[{"subnet": "10.88.0.0/16"}]],
"routes": [{"dst": "0.0.0.0/0"}]
}
},
{"type": "portmap", "capabilities": {"portMappings": true}}
]
}
EOF
```
### 6. `iptables` must be installed manually
WSL2 Ubuntu 26.04 does not ship with `iptables`. The bridge CNI plugin requires `iptables` to configure pod networking rules. Without it, every pod creation fails with:
```
plugin type="bridge" failed (add): failed to locate iptables: exec: "iptables": executable file not found in $PATH
```
The pod stays permanently in `ContainerCreating` with no visible error in `kubectl describe` — the error only appears in `journalctl -u edgecore.service`.
**Fix:**
```bash
sudo apt-get install -y iptables
sudo systemctl restart edgecore
```
## Request
Add a dedicated **"Running KubeEdge on Windows (WSL2 + Docker Desktop)"** guide to the KubeEdge documentation that covers all six requirements above with exact commands. This would significantly reduce friction for Windows-based contributors, students, and developers attempting to evaluate KubeEdge locally.
## System Verified On
- Windows 11 Home (Build 26200)
- WSL2 Ubuntu 26.04 LTS
- Docker Desktop v29.4.0
- KubeEdge v1.23.0
- Kubernetes v1.34.3
Contributor guide
Assessment
This issue has not been assessed yet.