Skip to content

docs: add WSL2 + Docker Desktop setup guide for running KubeEdge on Windows#801

Open
Gurkaran18 wants to merge 3 commits into
kubeedge:masterfrom
Gurkaran18:docs/wsl2-setup-guide-issue-797
Open

docs: add WSL2 + Docker Desktop setup guide for running KubeEdge on Windows#801
Gurkaran18 wants to merge 3 commits into
kubeedge:masterfrom
Gurkaran18:docs/wsl2-setup-guide-issue-797

Conversation

@Gurkaran18
Copy link
Copy Markdown

What type of PR is this?
/kind documentation

What this PR does / why we need it:

I went through the issue carefully and noticed that there's currently no
documentation for setting up KubeEdge on Windows using WSL2 + Docker Desktop,
which is a really common environment for students and developers who don't have
a dedicated Linux machine.

This PR adds a new guide at docs/setup/wsl2-docker-desktop.md that covers
all six undocumented failure points mentioned in the issue:

  1. Enabling systemd in WSL2 (it's not on by default)
  2. Installing native containerd inside WSL2 (Docker Desktop's containerd
    is not accessible from within WSL2 at the expected socket path)
  3. Fixing the cgroupDriver mismatch (WSL2 uses cgroupv2 but edgecore
    defaults to cgroupfs)
  4. Disabling swap validation (WSL2 has swap enabled which blocks edgecore)
  5. Installing CNI plugins manually (not covered in the quickstart)
  6. Installing iptables (not pre-installed on WSL2 Ubuntu, causes pods to
    get stuck in ContainerCreating silently)

Each step includes the exact commands to run and also explains what symptom
you'll see if you skip that step, so it's useful both for initial setup and
for debugging.

I also added a Chinese locale mirror file under i18n/zh/ to make sure the
Docusaurus build doesn't fail.

Which issue(s) this PR fixes:
Fixes #797

Special notes for reviewer:
Only 2 new files added, no existing files modified. All commands were taken
directly from the verified steps documented in the original issue report.

Does this PR introduce a user-facing change?:
Yes — adds a new setup guide for Windows developers using WSL2 + Docker Desktop.

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 <gurkaranbirsingh@example.com>
@kubeedge-bot kubeedge-bot added the kind/documentation Categorizes issue or PR as related to documentation. label May 13, 2026
@kubeedge-bot
Copy link
Copy Markdown
Collaborator

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign fisherxu after the PR has been reviewed.
You can assign the PR to them by writing /assign @fisherxu in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubeedge-bot kubeedge-bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 13, 2026
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new documentation guide for running KubeEdge on Windows using WSL2 and Docker Desktop, including both English and Chinese versions. The guide outlines essential configuration steps such as enabling systemd, installing containerd, and configuring CNI plugins. The review feedback suggests improving maintainability by using variables for the CNI plugin version instead of hardcoding it in both the English and Chinese documentation files.

Comment thread docs/setup/wsl2-docker-desktop.md Outdated
Comment thread i18n/zh/docusaurus-plugin-content-docs/current/setup/wsl2-docker-desktop.md Outdated
Signed-off-by: Gurkaran Singh <gurkaranbirsingh@example.com>
@Gurkaran18
Copy link
Copy Markdown
Author

Hi maintainers! I investigated the Netlify build failure and wanted to clarify:

The 4 failing Netlify checks are caused by pre-existing broken links in i18n/zh/...advanced/cloudcore-logs.md (missing zh mirrors for debug.md, install-with-keadm.md, config.md, and faq/setup.md). These broken links exist on master and are not introduced by this PR.

The WSL2 guide files added in this PR are clean — I confirmed by running a local yarn build with only the cloudcore-logs errors appearing (same as master baseline).

Would it be okay to proceed with merging, or would you like me to fix the pre-existing cloudcore-logs broken links in a separate PR?

Signed-off-by: Gurkaran Singh <gurkaranbirsingh@example.com>
Copy link
Copy Markdown
Contributor

@fujitatomoya fujitatomoya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i am not necessarily against this documentation. but i would suggest to move this doc under https://github.com/kubeedge/website/tree/master/blog at this moment, instead of official documentation setup procedure with a couple of reasons.

  • for real situation, it is highly likely that business developers use linux based platform instead of windows WSL environment.
  • without having the CI/CD pipleline for WSL, it is so easy to break and generate the gap between official documentation and what user can do. especially on this point, i would recommend to move this doc under blog as community support section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/documentation Categorizes issue or PR as related to documentation. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing WSL2 setup documentation for running KubeEdge on Windows with Docker Desktop

3 participants