Skip to content

Instantly share code, notes, and snippets.

@wholroyd
Last active October 30, 2024 01:11
Show Gist options
  • 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.

@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 !

@MnisiVN
Copy link

MnisiVN commented May 24, 2024

nice one I just followed it successfully. I had some issues with "Kubectl Preparation" package not found. but I sorted it with:

`echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

sudo apt update

sudo apt install -y kubelet kubeadm kubectl`

@johnddias
Copy link

nice one I just followed it successfully. I had some issues with "Kubectl Preparation" package not found. but I sorted it with:

You are my hero!

@starkgate
Copy link

starkgate commented Aug 9, 2024

Thank you for the guide. I had 3 errors:

  1. When running minikube start:
πŸ˜„  minikube v1.33.1 on Ubuntu 22.04 (amd64)
✨  Automatically selected the docker driver. Other choices: ssh, none
πŸ›‘  The "docker" driver should not be used with root privileges. If you wish to continue as root, use --force.
πŸ’‘  If you are running minikube within a VM, consider using --driver=none:
πŸ“˜    https://minikube.sigs.k8s.io/docs/reference/drivers/none/

❌  Exiting due to DRV_AS_ROOT: The "docker" driver should not be used with root privileges.

My WSL instance was using the default root user. To solve the issue, I created a new user and added it to the docker group:

adduser user
usermod -aG sudo user
su - user
sudo groupadd docker
sudo usermod -aG docker $USER && newgrp docker
  1. When running minikube dashboard:
πŸŽ‰  Opening http://127.0.0.1:46779/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/ in your default browser...
/usr/bin/xdg-open: 882: www-browser: not found
/usr/bin/xdg-open: 882: links2: not found
/usr/bin/xdg-open: 882: elinks: not found
/usr/bin/xdg-open: 882: links: not found
/usr/bin/xdg-open: 882: lynx: not found
/usr/bin/xdg-open: 882: w3m: not found
xdg-open: no method available for opening 'http://127.0.0.1:46779/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/'

❌  Exiting due to HOST_BROWSER: failed to open browser: exit status 3

The solution was to install wslu and set the env variable BROWSER to wslview:

sudo apt install wslu

In ~/.bashrc:

export BROWSER=wslview

Don't forget to source ~/.bashrc to update your shell, or open a new shell.

  1. Repository not found in Kubectl Preparation:
Hit:7 http://security.ubuntu.com/ubuntu jammy-security InRelease
Ign:8 https://packages.cloud.google.com/apt kubernetes-xenial InRelease
Err:9 https://packages.cloud.google.com/apt kubernetes-xenial Release
  404  Not Found [IP: 142.250.179.174 443]
Reading package lists... Done
W: https://download.docker.com/linux/ubuntu/dists/jammy/InRelease: Key is stored in legacy trusted.gpg keyring (/etc/apt/trusted.gpg), see the DEPRECATION section in apt-key(8) for details.
E: The repository 'https://apt.kubernetes.io kubernetes-xenial Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

The issue here seems to be that the guide assumes an installation of ubuntu xenial (16.04), I have version 22.04 installed. To fix this I instead followed the installation instructions for Debian in the Kubernetes documentation: https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#kubectl-install-0

@starkgate
Copy link

I would also suggest using the Helm installation script to get the latest version, the instructions here are hardcoded to install version 3.4.2 (latest at the time of writing is 3.15.3): https://helm.sh/docs/intro/install/#from-script

@Srivardhan-T
Copy link

Thank you

@Srivardhan-T
Copy link

Can anyone point me to clean up steps. cluster messed up with labs practice and wanted to reinstall it with clean setup again.

@morvanabonin
Copy link

Thanks for sharing!

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