diff --git a/docs/setup/wsl2-docker-desktop.md b/docs/setup/wsl2-docker-desktop.md new file mode 100644 index 000000000..035675a32 --- /dev/null +++ b/docs/setup/wsl2-docker-desktop.md @@ -0,0 +1,285 @@ +--- +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 +# 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/${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 +``` + +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..4622f1c25 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md @@ -0,0 +1,110 @@ +--- +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 中文翻译说明 +本页面为英文原文的占位镜像，完整内容请参阅英文版本（English documentation）。 +::: + +--- + +## 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 +# 可在 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/${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 +``` + +### 步骤 6：安装 iptables + +```bash +sudo apt-get install -y iptables +``` + +### 最终：重启并验证 + +```bash +sudo systemctl restart edgecore +sudo systemctl status edgecore +kubectl get nodes +```