Skip to content

Instantly share code, notes, and snippets.

@wholroyd
Last active April 11, 2024 09:17
Show Gist options
  • Star 55 You must be signed in to star a gist
  • Fork 32 You must be signed in to fork a gist
  • Save wholroyd/748e09ca0b78897750791172b2abb051 to your computer and use it in GitHub Desktop.
Save wholroyd/748e09ca0b78897750791172b2abb051 to your computer and use it in GitHub Desktop.
Getting Minikube on WSL2 Ubuntu working

Windows Preparation

  1. Ensure hypervisor functionality is enabled in BIOS.

    • I know it sounds stupid, but if you already have it enabled, disable it, restart the machine, and enable it again.
    • Otherwise you will hit microsoft/WSL#5363
  2. Launch a PowerShell prompt in Administrator mode [Win+X > Windows PowerShell (Admin)]

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
bcdedit /set hypervisorlaunchtype auto
  1. Install the Linux kernel update package and install it

  2. Restart machine

  3. Launch a PowerShell prompt in Administrator mode [Win+X > Windows PowerShell (Admin)]

wsl --set-default-version 2
  1. Install Ubuntu Linux distribution of your choice from the Windows Store (not the one with the version in the names)

  2. Verify WSL version is set correctly

wsl --list --verbose

Ubuntu Preparation

  1. Run series of commands to get right build of Docker installed
    • Removes the old crap, gets the dependencies right, adds Docker key, adds Docker repo, installs the new hotness
sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update
sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install docker-ce docker-ce-cli containerd.io -y
  1. Run series of commands to ensure you can interact with Docker without root
    • Third command here is a trick to reload your profile without actually logging out
    • Closing out Ubuntu shell and starting over instead of third command is an option
sudo groupadd docker
sudo usermod -aG docker ${USER}
su -s ${USER}
  1. Test the Docker configuration
sudo service docker start
docker run hello-world

If you have issues with the docker run hello-world command, see the troubleshooting.md on this gist.

Minikube Preparation

  1. Install Minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb
sudo apt install ./minikube_latest_amd64.deb -y
rm minikube_latest_amd64.deb
  1. Start it
minikube start
  1. Get the dashboard going
    • The dashboard will continue to run and does not return back to a prompt here
    • You will need to kill the dashboard to continue in the guide
minikube dashboard
  1. Open the dashboard in your favorite browser (in Windows)
    • Port is dynamic, so can't document it well - you'll just have to be good at reading directions
    • The port will be in output of step 3 command
    • Should look something like this...
http://127.0.0.1:[PORT GOES HERE]/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/#/workloads?namespace=default
  1. This process is going to block you from the finishing this guide, but to keep it running, do the following...
    • Perform "CTRL+Z" on the keyboard to send the process into paused state
    • Execute the following command to resume the paused process in the background
bg

Kubectl Preparation

  1. Install Kubectl
    • Adds k8s key, adds k8s repo, installs the new hotness
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl
  1. Use it
kubectl get po -A

Helm Preparation

  1. Install Helm
curl --output helm-linux-amd64.tar.gz https://get.helm.sh/helm-v3.4.2-linux-amd64.tar.gz
tar -zxvf helm-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/helm
rm helm-linux-amd64.tar.gz
rm -rf linux-amd64
  1. Use it
helm version

Docker Start Failure

When using the preparations.md instructions...

--- If you get an [OK] message when doing sudo service docker start, but the docker run hello-world command fails:

Run the docker daemon on the terminal directly in debug mode

dockerd -D

If you get this message at the end of the output, this means we need the legacy iptables...

DEBU[2023-05-30T11:13:13.522324640-04:00] sd notification                               error="<nil>" notified=false state="STOPPING=1"
failed to start daemon: Error initializing network controller: error obtaining controller instance: unable to add return rule in DOCKER-ISOLATION-STAGE-1 chain:  (iptables failed: iptables --wait -A DOCKER-ISOLATION-STAGE-1 -j RETURN: iptables v1.8.7 (nf_tables):  RULE_APPEND failed (No such file or directory): rule in chain DOCKER-ISOLATION-STAGE-1
 (exit status 4))

This can be fixed by running these commands...

sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Once complete, start #3 on the preparations.md instructions over again.

Thank you to coarsehorse for identifying the resolution for this problem.

@CwjXFH
Copy link

CwjXFH commented May 24, 2022

Thanks for this document, Kubectl in Minikube is also good.

@jdhom
Copy link

jdhom commented Aug 30, 2022

Thanks!

@svabra
Copy link

svabra commented Nov 26, 2022

Works on Win11 Home, WSL2. That was a shortcut. Thank you for documenting it.

@cezarymostowiec
Copy link

Thank you :)

@magnem66
Copy link

magnem66 commented Jan 9, 2023

Awesome! Thank you.

@raleik-pl
Copy link

raleik-pl commented Feb 13, 2023

Is it ok if I get this error related to virtualbox?

Setting up virtualbox (6.1.38-dfsg-3~ubuntu1.20.04.1) ...
Job for virtualbox.service failed because the control process exited with error code.
See "systemctl status virtualbox.service" and "journalctl -xe" for details.
invoke-rc.d: initscript virtualbox, action "restart" failed.
* virtualbox.service - LSB: VirtualBox Linux kernel module
     Loaded: loaded (/etc/init.d/virtualbox; generated)
     Active: failed (Result: exit-code) since Mon 2023-02-13 13:11:18 CET; 4ms ago
       Docs: man:systemd-sysv-generator(8)
    Process: 10472 ExecStart=/etc/init.d/virtualbox start (code=exited, status=1/FAILURE)

Feb 13 13:11:18 raleik-laptop systemd[1]: Starting LSB: VirtualBox Linux kernel module...
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:  * Loading VirtualBox kernel modules...
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:  * No suitable module for running kernel found
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:    ...fail!
Feb 13 13:11:18 raleik-laptop systemd[1]: virtualbox.service: Control process exited, code=exited, status=1/FAILURE
Feb 13 13:11:18 raleik-laptop systemd[1]: virtualbox.service: Failed with result 'exit-code'.
Feb 13 13:11:18 raleik-laptop systemd[1]: Failed to start LSB: VirtualBox Linux kernel module.

Should I ignore it or something's wrong? Despite I got this, everything seems to work fine.

@wholroyd
Copy link
Author

Is it ok if I get this error related to virtualbox?

Setting up virtualbox (6.1.38-dfsg-3~ubuntu1.20.04.1) ...
Job for virtualbox.service failed because the control process exited with error code.
See "systemctl status virtualbox.service" and "journalctl -xe" for details.
invoke-rc.d: initscript virtualbox, action "restart" failed.
* virtualbox.service - LSB: VirtualBox Linux kernel module
     Loaded: loaded (/etc/init.d/virtualbox; generated)
     Active: failed (Result: exit-code) since Mon 2023-02-13 13:11:18 CET; 4ms ago
       Docs: man:systemd-sysv-generator(8)
    Process: 10472 ExecStart=/etc/init.d/virtualbox start (code=exited, status=1/FAILURE)

Feb 13 13:11:18 raleik-laptop systemd[1]: Starting LSB: VirtualBox Linux kernel module...
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:  * Loading VirtualBox kernel modules...
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:  * No suitable module for running kernel found
Feb 13 13:11:18 raleik-laptop virtualbox[10472]:    ...fail!
Feb 13 13:11:18 raleik-laptop systemd[1]: virtualbox.service: Control process exited, code=exited, status=1/FAILURE
Feb 13 13:11:18 raleik-laptop systemd[1]: virtualbox.service: Failed with result 'exit-code'.
Feb 13 13:11:18 raleik-laptop systemd[1]: Failed to start LSB: VirtualBox Linux kernel module.

Should I ignore it or something's wrong? Despite I got this, everything seems to work fine.

This sounds like an issue with a Linux kernel upgrade and the VirtualBox kernel driver not existing for the version of kernel you're running.

Although, I'm not sure how you would be getting this unless you're attempting to run VirtualBox from within the WSL environment. This should be possible in the latest versions of WSL2, but not sure why you'd be doing this - unless you're using Vagrant?

@akshayVGS
Copy link

thank you

@network-charles
Copy link

tar -zxvf helm-linux-amd64.tar.gz
tar (child): helm-linux-amd64.tar.gz: Cannot open: No such file or directory
tar (child): Error is not recoverable: exiting now
tar: Child returned status 2
tar: Error is not recoverable: exiting now

helm version
Segmentation fault

I got the above error

@wholroyd
Copy link
Author

@network-charles - Did the command immediately before the tar -zxvf helm-linux-amd64.tar.gz complete successfully?

curl --output helm-linux-amd64.tar.gz https://get.helm.sh/helm-v3.4.2-linux-amd64.tar.gz

@network-charles
Copy link

@wholroyd I just retried it again and the helms' installation was successful.

@coarsehorse
Copy link

coarsehorse commented Apr 25, 2023

Getting docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?. after running docker run hello-world.
Edit: this was the issue. To fix, run:

sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
sudo service docker start

@nagarjuna831
Copy link

very helpful, nice documentation

@igor-korotkov
Copy link

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb
sudo apt install ./minikube_latest_amd64.deb -y
rm minikube_latest_amd64.deb

this leads to apt trying to install a whole bunch of dependencies including ubuntu-mono virtualbox
virtualbox-qt x11-common

This is also why a person above was messaging about virtualbox issues
Obviously we don't want to also be getting virtualbox in our wsl2 if we're already using hyperv

I saw people using pre-compiled minucube in wsl2, but that required manually installing some dependencies, and also seems pretty unstable...

@sangrepura
Copy link

@igor-korotkov I saw the same and just performed these steps in my WSL2 Ubuntu 22.04. No additional dependencies needed:

curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
chmod +x ./minikube
sudo mv ./minikube /usr/local/bin/
minikube config set driver docker
❗  These changes will take effect upon a minikube delete and then a minikube start

minikube start
 -- truncated for brevity
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

minikube kubectl -- get pods -A
 
NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
kube-system   coredns-5d78c9869d-46fkz           1/1     Running   0          14s
kube-system   etcd-minikube                      1/1     Running   0          25s
kube-system   kube-apiserver-minikube            1/1     Running   0          28s
kube-system   kube-controller-manager-minikube   1/1     Running   0          28s
kube-system   kube-proxy-cfbvl                   1/1     Running   0          14s
kube-system   kube-scheduler-minikube            1/1     Running   0          28s
kube-system   storage-provisioner                1/1     Running   0          24s

Hope this helps!

@igor-korotkov
Copy link

igor-korotkov commented Aug 8, 2023

@igor-korotkov I saw the same and just performed these steps in my WSL2 Ubuntu 22.04. No additional dependencies needed:

curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
chmod +x ./minikube
sudo mv ./minikube /usr/local/bin/
minikube config set driver docker
❗  These changes will take effect upon a minikube delete and then a minikube start

minikube start
 -- truncated for brevity
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

minikube kubectl -- get pods -A
 
NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
kube-system   coredns-5d78c9869d-46fkz           1/1     Running   0          14s
kube-system   etcd-minikube                      1/1     Running   0          25s
kube-system   kube-apiserver-minikube            1/1     Running   0          28s
kube-system   kube-controller-manager-minikube   1/1     Running   0          28s
kube-system   kube-proxy-cfbvl                   1/1     Running   0          14s
kube-system   kube-scheduler-minikube            1/1     Running   0          28s
kube-system   storage-provisioner                1/1     Running   0          24s

Hope this helps!

Ye, I did the same in the end, minikube seems to be working just fine in my system.

@cbolyard
Copy link

Thanks for sharing!

@stephanlamoureux
Copy link

Installing minikube caused my code command in WSL to stop working.

@derMatze82
Copy link

@igor-korotkov I saw the same and just performed these steps in my WSL2 Ubuntu 22.04. No additional dependencies needed:

curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
chmod +x ./minikube
sudo mv ./minikube /usr/local/bin/
minikube config set driver docker
❗  These changes will take effect upon a minikube delete and then a minikube start

minikube start
 -- truncated for brevity
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

minikube kubectl -- get pods -A
 
NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
kube-system   coredns-5d78c9869d-46fkz           1/1     Running   0          14s
kube-system   etcd-minikube                      1/1     Running   0          25s
kube-system   kube-apiserver-minikube            1/1     Running   0          28s
kube-system   kube-controller-manager-minikube   1/1     Running   0          28s
kube-system   kube-proxy-cfbvl                   1/1     Running   0          14s
kube-system   kube-scheduler-minikube            1/1     Running   0          28s
kube-system   storage-provisioner                1/1     Running   0          24s

Hope this helps!

thank you for this one!

@ryankert01
Copy link

Installing minikube caused my code command in WSL to stop working.

same problem

@ryankert01
Copy link

ryankert01 commented Mar 13, 2024

Installing minikube caused my code command in WSL to stop working.

@stephanlamoureux This can be solve by this issue.

@giffarda
Copy link

this guide is unbelievable thank you so much !

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