Kubernetes Installation on WSL2 - Complete Setup Guide

Install Kubernetes on WSL

This guide walks you through installing a complete Kubernetes development environment inside WSL2, including Docker, Minikube, and K9s for cluster management. Perfect for Windows developers who want to run Kubernetes locally.

Prerequisites

• Windows 10 version 2004 or higher, or Windows 11
• Administrative access to install WSL2
• At least 8GB RAM (4GB will be allocated to Minikube)
• Internet connection for downloading components

Tip

This setup provides a full Kubernetes development environment without the overhead of running a full VM or using Docker Desktop.

Step 1: Enable WSL2

1. Install WSL2

   • Open PowerShell as Administrator
   • Run the following command:

   wsl --install

2. Verify WSL2 installation

   • If WSL2 is already installed, ensure your distro is using WSL2:

   wsl --set-version DISTRO-NAME 2

   Note

   Replace DISTRO-NAME with your actual distribution name (e.g., Ubuntu, Debian).

3. Restart your computer

   • Reboot to complete the WSL2 installation
   • Launch your WSL2 distribution after restart

Step 2: Install Docker Engine in WSL

1. Update package index

   • Launch your WSL2 distribution (e.g., Ubuntu)
   • Update the package repository:

   sudo apt update && sudo apt upgrade -y

2. Install Docker

   sudo apt install -y docker.io

3. Configure user permissions

   • Add your user to the docker group to avoid using sudo:

   sudo usermod -aG docker $USER
   exec su -l $USER

   Tip

   The exec su -l $USER command refreshes your user session to apply the group changes immediately.

Step 3: Enable systemd in WSL

1. Configure WSL to use systemd

   • Edit or create the WSL configuration file:

   sudo nano /etc/wsl.conf

2. Add systemd configuration

   • Add the following content to the file:

   [boot]
   systemd=true

3. Restart WSL

   • Exit your WSL session and shutdown WSL from PowerShell:

   wsl --shutdown

   • Restart your WSL distribution

   Note

   Systemd is required for Docker and other services to work properly in WSL2.

Step 4: Configure and Start Docker

1. Enable Docker service

   • Back in your WSL distribution, enable Docker to start automatically:

   sudo systemctl enable docker
   sudo systemctl start docker

2. Verify Docker installation

   • Test that Docker is working correctly:

   docker ps

   • You should see an empty table (no running containers)

3. Test Docker functionality

   # Run a simple test container
   docker run hello-world

   Tip

   If you see the “Hello from Docker!” message, Docker is working correctly.

Step 5: Install Portainer (Optional Docker UI)

1. Create persistent volume

   • Create a Docker volume for Portainer data:

   docker volume create portainer_data

2. Deploy Portainer

   • Run Portainer container with the following configuration:

   docker run -d \
     --name portainer \
     --restart=always \
     -p 9000:9000 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v portainer_data:/data \
     portainer/portainer-ce

3. Access Portainer

   • Open your web browser and navigate to:
   • http://localhost:9000
   • Create an admin account on first access

   Tip

   Portainer provides a web-based GUI for managing Docker containers, images, and volumes.

Step 6: Install Kubernetes Tools

1. Install kubectl

   • Download and install the Kubernetes command-line tool:

   curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
   chmod +x kubectl
   sudo mv kubectl /usr/local/bin/

2. Install Minikube

   • Download and install Minikube for local Kubernetes clusters:

   curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
   chmod +x minikube-linux-amd64
   sudo mv minikube-linux-amd64 /usr/local/bin/minikube

3. Verify installation

   • Check that both tools are installed correctly:

   kubectl version --client
   minikube version

   Note

   kubectl is the main tool for interacting with Kubernetes clusters, while Minikube creates and manages local clusters.

Step 7: Start Your Kubernetes Cluster

1. Configure Docker environment

   • Set the Docker host for Minikube:

   export DOCKER_HOST=unix:///var/run/docker.sock

2. Start Minikube cluster

   • Initialize your local Kubernetes cluster:

   minikube start \
     --driver=docker \
     --cpus=2 \
     --memory=4096

   Tip

   Adjust CPU and memory allocation based on your system resources. Minimum recommended is 2 CPUs and 2GB RAM.

3. Wait for cluster initialization

   • The first start may take several minutes as it downloads images
   • You’ll see progress updates in the terminal

Step 8: Verify Kubernetes Setup

1. Check Minikube status

   minikube status

   • All components should show “Running”

2. Configure kubectl context

   kubectl config use-context minikube

3. Verify cluster connectivity

   kubectl get pods -A

   • You should see system pods running in kube-system namespace

4. Test with a sample deployment

   # Create a test deployment
   kubectl create deployment hello-minikube --image=kicbase/echo-server:1.0
   
   # Expose it as a service
   kubectl expose deployment hello-minikube --type=NodePort --port=8080
   
   # Check the service
   kubectl get services hello-minikube

   Tip

   Use minikube service hello-minikube to open the service in your browser and test connectivity.

Step 9: Install K9s for Cluster Management

1. Install K9s on Windows

   • Open PowerShell and install K9s using winget:

   winget install k9s

2. Configure K9s to use WSL kubeconfig

   • Set up environment variable to point to WSL kubeconfig:
   • Press Win + R, type sysdm.cpl, and press Enter
   • Click Environment Variables
   • Under User variables, click New:
     • Variable name: KUBECONFIG
     • Variable value: \\wsl$\Ubuntu\home\YOUR-USERNAME\.kube\config
   • Replace YOUR-USERNAME with your actual WSL username

3. Alternative: Copy kubeconfig to Windows

   # In WSL, copy kubeconfig to Windows user directory
   cp ~/.kube/config /mnt/c/Users/WINDOWS-USERNAME/.kube/config

   Note

   K9s provides a terminal-based UI for managing Kubernetes clusters, making it easier to navigate pods, services, and logs.

4. Test K9s

   • Restart your terminal and run:

   k9s

   • You should see the K9s interface connected to your Minikube cluster

Useful Commands and Tips

Common kubectl Commands

# View cluster information
kubectl cluster-info

# Get all resources in a namespace
kubectl get all -n kube-system

# Describe a resource
kubectl describe pod POD-NAME

# View logs
kubectl logs POD-NAME

# Execute commands in a pod
kubectl exec -it POD-NAME -- /bin/bash

# Port forward to access services locally
kubectl port-forward service/SERVICE-NAME 8080:80

Minikube Management

# Stop the cluster
minikube stop

# Delete the cluster
minikube delete

# SSH into the Minikube VM
minikube ssh

# Open Minikube dashboard
minikube dashboard

# List available addons
minikube addons list

# Enable an addon (e.g., ingress)
minikube addons enable ingress

Troubleshooting

Caution

Common Issues:

• If Docker fails to start, ensure systemd is properly configured
• If Minikube fails to start, check available system resources
• For WSL networking issues, try restarting WSL with wsl --shutdown

Check Docker status:

sudo systemctl status docker

Check WSL version:

wsl --list --verbose

Reset Minikube if needed:

minikube delete
minikube start --driver=docker