Skip to content

Commit de54335

Browse files
committed
Add known issue for WSL2 and cgroupv2 support
This adds a note to the Known Issues document with details related to proper setup requirements for cgroupv2 support and links to the known issues page for extra visibility from the Using WSL2 page. Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>
1 parent 846a2cc commit de54335

File tree

2 files changed

+28
-5
lines changed

2 files changed

+28
-5
lines changed

site/content/docs/user/known-issues.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ description: |-
4040
* [Failed to get rootfs info](#failed-to-get-rootfs-info--stat-failed-on-dev)
4141
* [Docker Desktop for macOS and Windows](#docker-desktop-for-macos-and-windows)
4242
* [Older Linux Distributions](#older-linux-distributions)
43+
* [Failure to Create Cluster on WSL2](#failure-to-create-cluster-on-wsl2)
4344

4445
## Troubleshooting Kind
4546

@@ -376,7 +377,14 @@ Although the policy has been fixed in Fedora 34, the fix has not been backported
376377
377378
## Docker Desktop for macOS and Windows
378379
379-
Docker containers cannot be executed natively on macOS and Windows, therefore Docker Desktop runs them in a Linux VM. As a consequence, the container networks are not exposed to the host and you cannot reach the kind nodes via IP. You can work around this limitation by configuring [extra port mappings](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings) though.
380+
Docker containers cannot be executed natively on macOS and Windows, therefore
381+
Docker Desktop runs them in a Linux VM. As a consequence, the container networks
382+
are not exposed to the host and you cannot reach the kind nodes via IP.
383+
384+
You may be able to work around this limitation by configuring [extra port
385+
mappings](https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings),
386+
leveraging [cloud-provider-kind](https://github.com/kubernetes-sigs/cloud-provider-kind),
387+
using a network proxy, or other solution specific to your environment.
380388
381389
## Older Linux Distributions
382390
@@ -393,6 +401,21 @@ Command Output: WARNING: Your kernel does not support cgroup namespaces. Cgroup
393401
Using KIND in these environments will require upgrading your OS to a more recent version that supports cgroup namespaces.
394402
Another option is to run a virtual machine using a newer kernel.
395403
404+
## Failure to Create Cluster on WSL2
405+
406+
Some Linux kernel options for WSL2 do not have cgroup configured in a way that
407+
KIND and other Linux-focused tools may expect. This may result in a failure
408+
message when attempting to create a cluster, similar to:
409+
410+
```txt
411+
unable to start container process: error adding pid 655569 to cgroups
412+
```
413+
414+
The KIND development team is not able to provide support with Windows and WSL, so
415+
the project relies on community support and feedback. It has been noted that the
416+
steps detailed in [https://github.com/spurin/wsl-cgroupsv2](https://github.com/spurin/wsl-cgroupsv2)
417+
have been necessary to resolve this issue.
418+
396419
[kind#156]: https://github.com/kubernetes-sigs/kind/issues/156
397420
[kind#229]: https://github.com/kubernetes-sigs/kind/issues/229
398421
[kind#1179]: https://github.com/kubernetes-sigs/kind/issues/1179

site/content/docs/user/using-wsl2.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ description: |-
1111
All the tools needed to build or run kind work in WSL2, but some extra steps are needed to switch to WSL2. This page covers these steps in brief but also links to the official documentation if you would like more details.
1212
---
1313

14-
## Getting Windows 10
14+
## Getting Windows 10 or 11
1515

16-
Download the latest ISO at https://www.microsoft.com/en-us/software-download/windows10ISO. Choose "Windows 10 May 2020 Update". If there's a later update, that will work too.
16+
Download the latest ISO at https://www.microsoft.com/en-us/software-download/.
17+
Choose the latest Windows 10 or Windows 11 release.
1718

1819
### Installing on a virtual machine
1920

@@ -63,13 +64,11 @@ wsl --set-default-version 2
6364

6465
Install Docker with WSL2 backend here: https://docs.docker.com/docker-for-windows/wsl/
6566

66-
6767
## Setting up Docker in WSL2 without Docker Desktop
6868

6969
Alternatively, docker can be installed in WSL2 without using Docker Desktop.
7070
See for example: https://dev.to/bowmanjd/install-docker-on-windows-wsl-without-docker-desktop-34m9
7171

72-
7372
Now, move on to the [Quick Start](/docs/user/quick-start) to set up your cluster with kind.
7473

7574
## Accessing a Kubernetes Service running in WSL2
@@ -141,3 +140,4 @@ kernel=c:\\path\\to\\your\\kernel\\bzImage
141140
- You can check the status of all installed distros with `wsl --list --verbose`.
142141
- If you had a distro installed with WSL1, you can convert it to WSL2 with `wsl --set-version <distro> 2`
143142
- Alternative of [Accessing a Kubernetes Service running in WSL2](#accessing-a-kubernetes-service-running-in-wsl2) or [Setting Up An Ingress Controller](/docs/user/ingress/#setting-up-an-ingress-controller) for accessing workloads is using `kubectl port-forward --address=0.0.0.0`.
143+
- See the [Known Issues](/docs/user/known-issues/) page for additional Windows-related issues and concerns.

0 commit comments

Comments
 (0)