From 7230d96b070b1d5da25d7be5e14c313c8d3d88ef Mon Sep 17 00:00:00 2001 From: Gurkaran Singh Date: Wed, 13 May 2026 15:12:46 +0530 Subject: [PATCH 1/3] docs: add WSL2 Docker Desktop setup guide for KubeEdge on Windows Add a comprehensive guide covering all six WSL2-specific requirements that must be satisfied before EdgeCore can run inside WSL2 with Docker Desktop: 1. Enabling systemd (not active by default in WSL2) 2. Installing native containerd (Docker Desktop's containerd is not accessible at the expected socket path) 3. Setting cgroupDriver to systemd (WSL2 uses cgroupv2) 4. Disabling swap validation (WSL2 has swap enabled by default) 5. Installing CNI plugins manually (not included in keadm quickstart) 6. Installing iptables (not pre-installed on WSL2 Ubuntu 22.04+) Also adds a Chinese locale mirror to satisfy the Docusaurus i18n build. Signed-off-by: Gurkaran Singh --- docs/setup/wsl2-docker-desktop.md | 283 ++++++++++++++++++ .../current/setup/wsl2-docker-desktop.md | 108 +++++++ 2 files changed, 391 insertions(+) create mode 100644 docs/setup/wsl2-docker-desktop.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md diff --git a/docs/setup/wsl2-docker-desktop.md b/docs/setup/wsl2-docker-desktop.md new file mode 100644 index 000000000..ebeec2f2a --- /dev/null +++ b/docs/setup/wsl2-docker-desktop.md @@ -0,0 +1,283 @@ +--- +title: Running KubeEdge on Windows (WSL2 + Docker Desktop) +sidebar_position: 9 +--- + +> **Applies to:** KubeEdge v1.13+ +> **Related issue:** [kubeedge/website#797](https://github.com/kubeedge/website/issues/797) + +This guide explains how to run a KubeEdge edge node inside **WSL2** (Windows Subsystem for Linux 2) on a Windows machine that uses **Docker Desktop**. Without following these steps, users encounter a series of silent or misleading failures because WSL2's default environment differs from a standard Linux server in several important ways. + +:::note System Requirements +This guide was verified on: +- Windows 11 Home (Build 26200) +- WSL2 with Ubuntu 22.04 LTS or later +- Docker Desktop v4.x or later +- KubeEdge v1.13+ +::: + +--- + +## Overview of WSL2-Specific Requirements + +WSL2 is not a standard Linux environment. Before running EdgeCore, you must address the following six requirements. Each one causes a distinct failure if skipped: + +| # | Requirement | Symptom if Skipped | +|---|---|---| +| 1 | Enable systemd | EdgeCore silently fails to start after `keadm join` | +| 2 | Install native containerd | `dial unix /run/containerd/containerd.sock: no such file` | +| 3 | Set `cgroupDriver: systemd` | ContainerManager startup failure | +| 4 | Set `failSwapOn: false` | EdgeCore refuses to start due to swap validation | +| 5 | Install CNI plugins | Edge node stays in `NotReady` state | +| 6 | Install iptables | Pod creation fails with `ContainerCreating` and no clear error | + +--- + +## Step 1: Enable systemd in WSL2 + +WSL2 does not run systemd by default. EdgeCore installs itself as a systemd service, so systemd **must** be PID 1 inside WSL2. + +Open a WSL2 terminal and run: + +```bash +sudo tee /etc/wsl.conf << 'EOF' +[boot] +systemd=true +EOF +``` + +Then, from a **Windows PowerShell** (outside WSL2), shut down the WSL2 VM to apply the change: + +```powershell +wsl --shutdown +``` + +Reopen your WSL2 terminal and verify that systemd is running as PID 1: + +```bash +ps -p 1 -o comm= +``` + +The output must be `systemd`. If it shows `init` or anything else, the change has not taken effect — recheck `/etc/wsl.conf` and run `wsl --shutdown` again. + +--- + +## Step 2: Install Native containerd Inside WSL2 + +Even when Docker Desktop's WSL2 integration is fully enabled, its internal containerd instance runs in an **isolated VM context** and does **not** expose a socket at the default path `/run/containerd/containerd.sock` that EdgeCore expects. + +If you skip this step, EdgeCore will fail immediately with: + +``` +dial unix /run/containerd/containerd.sock: connect: no such file or directory +``` + +Install containerd natively inside your WSL2 distribution: + +```bash +sudo apt-get update +sudo apt-get install -y containerd +``` + +Enable and start the containerd service: + +```bash +sudo systemctl enable --now containerd +``` + +Verify that the socket is now present: + +```bash +ls /run/containerd/containerd.sock +``` + +Generate the default containerd configuration so that EdgeCore can interact with it correctly: + +```bash +sudo mkdir -p /etc/containerd +containerd config default | sudo tee /etc/containerd/config.toml +sudo systemctl restart containerd +``` + +--- + +## Step 3: Fix cgroupDriver Mismatch + +WSL2 uses **cgroupv2** by default. However, `keadm join` generates an `edgecore.yaml` configuration file that sets `cgroupDriver: cgroupfs`, which is incompatible with cgroupv2. + +After running `keadm join`, open the EdgeCore configuration file: + +```bash +sudo nano /etc/kubeedge/config/edgecore.yaml +``` + +Find the `edged` section and change `cgroupDriver` from `cgroupfs` to `systemd`: + +```yaml +edged: + cgroupDriver: systemd # Change from cgroupfs +``` + +Save the file and restart EdgeCore: + +```bash +sudo systemctl restart edgecore +``` + +--- + +## Step 4: Disable Swap Validation + +WSL2 has swap memory enabled by default. EdgeCore inherits Kubernetes kubelet's strict swap validation and will refuse to start on a node where swap is active. + +After editing `/etc/kubeedge/config/edgecore.yaml` (from Step 3), also set `failSwapOn` to `false` within the `edged` section: + +```yaml +edged: + cgroupDriver: systemd # from Step 3 + failSwapOn: false # add this line +``` + +Save the file. This change takes effect after restarting EdgeCore (which you will do at the end). + +--- + +## Step 5: Install CNI Plugins + +Without CNI plugins, the edge node will register with the cluster but remain permanently in a `NotReady` state. The KubeEdge quickstart guide does not mention this requirement for edge nodes. + +Create the required directories and download the CNI plugin bundle: + +```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 +``` + +Create a basic bridge CNI network configuration for the edge node: + +```bash +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 +``` + +--- + +## Step 6: Install iptables + +WSL2 Ubuntu 22.04 and later may not ship with `iptables` pre-installed. The bridge CNI plugin from Step 5 requires `iptables` to set up pod networking rules. Without it, every pod creation fails with `ContainerCreating` and this error only appears in EdgeCore's journal — not in `kubectl describe pod`: + +``` +plugin type="bridge" failed (add): failed to locate iptables: exec: "iptables": executable file not found in $PATH +``` + +Install iptables: + +```bash +sudo apt-get install -y iptables +``` + +--- + +## Final Step: Apply All Configuration and Verify + +After completing Steps 1–6, restart EdgeCore to apply all changes: + +```bash +sudo systemctl restart edgecore +``` + +Check that EdgeCore is running without errors: + +```bash +sudo systemctl status edgecore +``` + +You should see `active (running)`. To watch logs in real time: + +```bash +journalctl -u edgecore -f +``` + +From the **cloud side**, verify that the edge node has joined and is `Ready`: + +```bash +kubectl get nodes +``` + +The edge node should appear with status `Ready` within a minute or two. + +--- + +## Quick-Reference Checklist + +Use this checklist when troubleshooting a failed WSL2 edge node setup: + +- [ ] `ps -p 1 -o comm=` outputs `systemd` +- [ ] `/run/containerd/containerd.sock` exists +- [ ] `edgecore.yaml` has `cgroupDriver: systemd` +- [ ] `edgecore.yaml` has `failSwapOn: false` +- [ ] `/opt/cni/bin/bridge` exists (CNI plugins installed) +- [ ] `/etc/cni/net.d/10-bridge.conflist` exists +- [ ] `iptables --version` returns a version string without error +- [ ] `systemctl status edgecore` shows `active (running)` + +--- + +## Troubleshooting + +### EdgeCore fails to start after `keadm join` + +Verify systemd is PID 1 (`ps -p 1 -o comm=` → `systemd`). If not, re-enable systemd in `/etc/wsl.conf` and run `wsl --shutdown` from PowerShell, then restart. + +### `dial unix /run/containerd/containerd.sock: no such file` + +Docker Desktop's containerd is not accessible from within WSL2. Install native containerd as described in [Step 2](#step-2-install-native-containerd-inside-wsl2). + +### Edge node is `NotReady` + +Check EdgeCore logs for CNI errors: + +```bash +journalctl -u edgecore --no-pager | grep -i cni +``` + +If CNI plugins or iptables are missing, complete [Step 5](#step-5-install-cni-plugins) and [Step 6](#step-6-install-iptables). + +### Pod stuck in `ContainerCreating` + +This is almost always an iptables issue on WSL2. Run: + +```bash +journalctl -u edgecore --no-pager | grep -i iptables +``` + +If you see `executable file not found in $PATH`, install iptables and restart EdgeCore. + +### cgroupDriver error in EdgeCore logs + +``` +failed to get cgroupDriver: Failed to start ContainerManager +``` + +Edit `/etc/kubeedge/config/edgecore.yaml` and set `cgroupDriver: systemd`, then restart EdgeCore. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md new file mode 100644 index 000000000..e8aafbf55 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md @@ -0,0 +1,108 @@ +--- +title: 在 Windows 上运行 KubeEdge（WSL2 + Docker Desktop） +sidebar_position: 9 +--- + +> **适用版本：** KubeEdge v1.13+ +> **相关 Issue：** [kubeedge/website#797](https://github.com/kubeedge/website/issues/797) + +本文档说明如何在 Windows 环境下通过 **WSL2**（Windows Subsystem for Linux 2）和 **Docker Desktop** 运行 KubeEdge 边缘节点。 + +:::note 中文翻译说明 +本页面为英文原文的占位镜像，完整内容请参阅英文版本：[Running KubeEdge on Windows (WSL2 + Docker Desktop)](../wsl2-docker-desktop)。 +::: + +--- + +## WSL2 环境特殊要求概览 + +WSL2 不是标准的 Linux 环境，在运行 EdgeCore 之前，必须满足以下六个要求： + +| # | 要求 | 跳过时的现象 | +|---|---|---| +| 1 | 启用 systemd | `keadm join` 后 EdgeCore 静默失败 | +| 2 | 在 WSL2 内安装原生 containerd | `dial unix /run/containerd/containerd.sock: no such file` | +| 3 | 设置 `cgroupDriver: systemd` | ContainerManager 启动失败 | +| 4 | 设置 `failSwapOn: false` | EdgeCore 因 swap 校验拒绝启动 | +| 5 | 手动安装 CNI 插件 | 边缘节点持续处于 `NotReady` 状态 | +| 6 | 安装 iptables | Pod 创建失败，卡在 `ContainerCreating` | + +--- + +## 完整步骤 + +请参考英文完整文档以获取所有步骤的详细命令和说明。 + +### 步骤 1：在 WSL2 中启用 systemd + +```bash +sudo tee /etc/wsl.conf << 'EOF' +[boot] +systemd=true +EOF +``` + +然后在 **Windows PowerShell** 中执行： + +```powershell +wsl --shutdown +``` + +验证： + +```bash +ps -p 1 -o comm= +# 输出必须为：systemd +``` + +### 步骤 2：在 WSL2 内安装原生 containerd + +```bash +sudo apt-get update +sudo apt-get install -y containerd +sudo systemctl enable --now containerd +sudo mkdir -p /etc/containerd +containerd config default | sudo tee /etc/containerd/config.toml +sudo systemctl restart containerd +``` + +### 步骤 3：修正 cgroupDriver + +编辑 `/etc/kubeedge/config/edgecore.yaml`： + +```yaml +edged: + cgroupDriver: systemd +``` + +### 步骤 4：禁用 Swap 校验 + +编辑 `/etc/kubeedge/config/edgecore.yaml`： + +```yaml +edged: + failSwapOn: false +``` + +### 步骤 5：安装 CNI 插件 + +```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 +``` + +### 步骤 6：安装 iptables + +```bash +sudo apt-get install -y iptables +``` + +### 最终：重启并验证 + +```bash +sudo systemctl restart edgecore +sudo systemctl status edgecore +kubectl get nodes +``` From 6fb333e91727e3d30e322ff827ee8563811da72f Mon Sep 17 00:00:00 2001 From: Gurkaran Singh Date: Wed, 13 May 2026 16:50:18 +0530 Subject: [PATCH 2/3] docs: fix broken link in zh locale WSL2 guide Signed-off-by: Gurkaran Singh --- .../current/setup/wsl2-docker-desktop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md index e8aafbf55..b42351a03 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md @@ -9,7 +9,7 @@ sidebar_position: 9 本文档说明如何在 Windows 环境下通过 **WSL2**（Windows Subsystem for Linux 2）和 **Docker Desktop** 运行 KubeEdge 边缘节点。 :::note 中文翻译说明 -本页面为英文原文的占位镜像，完整内容请参阅英文版本：[Running KubeEdge on Windows (WSL2 + Docker Desktop)](../wsl2-docker-desktop)。 +本页面为英文原文的占位镜像，完整内容请参阅英文版本（English documentation）。 ::: --- From 917cb32cfa02daa29eb511756ffae45997513b3a Mon Sep 17 00:00:00 2001 From: Gurkaran Singh Date: Wed, 13 May 2026 17:15:07 +0530 Subject: [PATCH 3/3] docs: use variable for CNI plugins version in WSL2 guide Signed-off-by: Gurkaran Singh --- docs/setup/wsl2-docker-desktop.md | 4 +++- .../current/setup/wsl2-docker-desktop.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/setup/wsl2-docker-desktop.md b/docs/setup/wsl2-docker-desktop.md index ebeec2f2a..035675a32 100644 --- a/docs/setup/wsl2-docker-desktop.md +++ b/docs/setup/wsl2-docker-desktop.md @@ -149,8 +149,10 @@ Without CNI plugins, the edge node will register with the cluster but remain per Create the required directories and download the CNI plugin bundle: ```bash +# Check for the latest version at https://github.com/containernetworking/plugins/releases +CNI_PLUGINS_VERSION="v1.5.0" 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 \ +wget "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGINS_VERSION}/cni-plugins-linux-amd64-${CNI_PLUGINS_VERSION}.tgz" \ -O /tmp/cni.tgz sudo tar -xzf /tmp/cni.tgz -C /opt/cni/bin ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md index b42351a03..4622f1c25 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md @@ -87,8 +87,10 @@ edged: ### 步骤 5：安装 CNI 插件 ```bash +# 可在 https://github.com/containernetworking/plugins/releases 查看最新版本 +CNI_PLUGINS_VERSION="v1.5.0" 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 \ +wget "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGINS_VERSION}/cni-plugins-linux-amd64-${CNI_PLUGINS_VERSION}.tgz" \ -O /tmp/cni.tgz sudo tar -xzf /tmp/cni.tgz -C /opt/cni/bin ```