Gateway crash on v0.0.16: k3s fatal error 'flag provided but not defined: -resolv-conf' #696

Activity

1. cluster2600

   added a commit that references this issue on Mar 31, 2026

   fix(gateway): pass resolv-conf as kubelet arg for k3s v1.35.2+

   ...

   This issue will close once commit b912b80 is merged into the 'main' branch.

   b912b80
2. yanggf8 commented on Mar 31, 2026

   

   yanggf8

   on Mar 31, 2026

   Author

   More actions

   Additional finding: overlayfs snapshotter failure on WSL2

   Even after working around the -resolv-conf flag issue (by passing server as the subcommand), k3s gets stuck in a loop unable to initialize containerd:

   Waiting to retrieve agent configuration; server is not ready: "overlayfs" snapshotter cannot be enabled
   for "/var/lib/rancher/k3s/agent/containerd", try using "fuse-overlayfs" or "native": failed to mount
   overlay: mount source: "overlay", target: "...", fstype: overlay, flags: 0, data: "...", err: invalid argument
   

   WSL2's kernel does not support nested overlayfs (overlay-on-overlay) when Docker itself is already using overlayfs as its storage driver. k3s's embedded containerd defaults to overlayfs and fails.

   Suggested fix

   The entrypoint should detect when overlayfs is unavailable and fall back to fuse-overlayfs or native snapshotter:

   # In cluster-entrypoint.sh, before exec:
   if ! mount -t overlay overlay -o lowerdir=/tmp/test-lower1:/tmp/test-lower2,upperdir=/tmp/test-upper,workdir=/tmp/test-work /tmp/test-merged 2>/dev/null; then
       EXTRA_KUBELET_ARGS="$EXTRA_KUBELET_ARGS --snapshotter=native"
   fi

   Or pass --snapshotter=native via k3s server args when running inside Docker (detected by /.dockerenv existence).

   Summary of issues

   So there are two distinct problems blocking WSL2:

   1. -resolv-conf as global flag — k3s v1.35.2 rejects it outside the server subcommand (original report)
   2. overlayfs snapshotter — nested overlayfs fails on WSL2, needs native or fuse-overlayfs fallback

   Environment

   • WSL2 kernel: 6.6.87.2-microsoft-standard-WSL2
   • Docker: 29.3.0 (Docker Desktop WSL backend)
   • Docker storage driver: overlay2
3. cluster2600 commented on Mar 31, 2026

   

   cluster2600

   on Mar 31, 2026

   Contributor

   More actions

   Verification: cluster image rebuilt and tested

   Built the cluster image from branch 696-k3s-resolv-conf-flag/mc on an NVIDIA DGX Spark (aarch64, Docker 29.1.3) and ran it with docker run --privileged:

   Before (v0.0.16 stock):

   time="…" level=fatal msg="Error: flag provided but not defined: -resolv-conf"
   

   Container exits immediately.

   After (this fix):

   time="2026-03-31T07:22:52Z" level=info msg="Starting k3s v1.35.2+k3s1 (13563feb)"
   time="2026-03-31T07:22:52Z" level=info msg="Configuring sqlite3 database connection pooling…"
   time="2026-03-31T07:22:52Z" level=info msg="Database tables and indexes are up to date"
   time="2026-03-31T07:22:52Z" level=info msg="Kine available at unix://kine.sock"
   …
   

   k3s starts successfully, generates all certificates, and begins agent configuration. Zero fatal messages in the container logs. Container remains running.

   The fix is a one-liner in the entrypoint: --resolv-conf= → --kubelet-arg=resolv-conf=. Regression test added to catch this if the flag format changes again.

   Build: mise run docker:build:cluster (5m 25s)
   Image: openshell/cluster:dev (sha256:167550c6…)
   Test: sh deploy/docker/test-cluster-entrypoint.sh — 6/6 assertions pass
4. drew

   self-assigned this

   on Mar 31, 2026
5. drew

   added 2 commits that reference this issue on Mar 31, 2026

   fix(cluster): pass resolv-conf as kubelet arg and pin k3s image digest

   ...

   This issue will close once commit c515094 is merged into the 'main' branch.

   c515094

   fix(cluster): add default CMD ["server"] for bare docker run

   ...

   This issue will close once commit b06377b is merged into the 'main' branch.

   b06377b
6. drew

   closed this as completedin #701on Mar 31, 2026
7. drew commented on Mar 31, 2026

   

   drew

   on Mar 31, 2026

   Collaborator

   More actions

   Please make sure to launch the cluster using the openshell gateway start command. Direct launching via the docker container is currently unsupported.