Kubernetes Tutorial: Troubleshooting Guide WIP
Kubernetes Tutorial: Troubleshooting Guide
This guide provides solutions to common issues you might encounter when setting up and working with a local Kubernetes cluster on Docker Desktop.
Docker Desktop Startup Issues
Problem: Docker Desktop fails to start
Possible causes and solutions:
- 
Virtualization not enabled in BIOS
- Restart your computer and enter BIOS settings (usually by pressing F2, F10, or Del during startup)
 - Look for Virtualization Technology, VT-x, AMD-V, or similar options
 - Enable these settings, save changes, and restart
 
 - 
Hyper-V or WSL 2 configuration issues
- Ensure Hyper-V is properly installed (for Hyper-V backend)
 - For WSL 2 backend, verify WSL 2 is installed and updated
 - Run PowerShell as Administrator and execute:
# For Hyper-V Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All # For WSL 2 wsl --update 
 - 
Windows features missing
- Open “Turn Windows features on or off” from Control Panel
 - Ensure the following are enabled:
- Hyper-V (if using Hyper-V backend)
 - Virtual Machine Platform
 - Windows Subsystem for Linux (if using WSL 2)
 
 - Restart your computer after enabling these features
 
 
Problem: Docker Desktop is extremely slow
Possible solutions:
- 
Increase resource allocation in Docker Desktop settings:
- Open Docker Desktop > Settings > Resources
 - Increase CPU, Memory, and Swap allocations
 - Recommended minimum: 2 CPUs, 4GB RAM
 
 - 
Check for disk space issues:
- Ensure you have at least 10GB free space
 - Clean up unused Docker images and volumes:
docker system prune -a 
 
Kubernetes Initialization Problems
Problem: Kubernetes fails to start or gets stuck
Possible solutions:
- 
Increase Docker Desktop resources
- Open Docker Desktop > Settings > Resources
 - Increase memory allocation to at least 4GB
 - Increase CPU allocation to at least 2 CPUs
 
 - 
Reset Kubernetes cluster
- Open Docker Desktop > Settings > Kubernetes
 - Click “Reset Kubernetes Cluster”
 - Wait for the process to complete and try enabling Kubernetes again
 
 - 
Check for network conflicts
- Ensure no other services are using ports required by Kubernetes (6443, 10250-10252)
 - Temporarily disable VPNs or other network tools that might interfere
 
 - 
Review Docker Desktop logs
- Open Docker Desktop > Troubleshoot > Get support
 - Click “Diagnose & Feedback” to generate logs
 - Review logs for specific error messages
 
 
Problem: “No connection could be made because the target machine actively refused it”
This typically indicates a port conflict or networking issue:
- 
Check if another service is using Kubernetes ports:
netstat -ano | findstr 6443 netstat -ano | findstr 10250 - 
Temporarily disable firewall to test if it’s blocking connections:
# Note: Re-enable after testing netsh advfirewall set allprofiles state off - 
Reset Docker Desktop networking:
- Open Docker Desktop > Troubleshoot
 - Click “Clean / Purge data”
 - Select “Reset network” and apply
 
 
kubectl Command Failures
Problem: “kubectl: command not found”
Solutions:
- 
Verify Docker Desktop installation:
- Reinstall Docker Desktop if necessary
 - Ensure the “Add to PATH” option was selected during installation
 
 - 
Manually add kubectl to PATH:
- Locate kubectl.exe (typically in 
C:\Program Files\Docker\Docker\resources\bin) - Add this directory to your system PATH
 
 - Locate kubectl.exe (typically in 
 - 
Install kubectl separately:
# Using Chocolatey choco install kubernetes-cli # Or download directly curl -LO "https://dl.k8s.io/release/v1.26.0/bin/windows/amd64/kubectl.exe" # Move to a directory in your PATH 
Problem: “The connection to the server localhost:8080 was refused”
Solutions:
- 
Ensure Docker Desktop is running and Kubernetes is enabled
 - 
Check kubectl configuration:
kubectl config view - 
Set the correct context:
kubectl config use-context docker-desktop - 
Manually configure kubectl:
kubectl config set-cluster docker-desktop --server=https://localhost:6443 kubectl config set-context docker-desktop --cluster=docker-desktop kubectl config use-context docker-desktop 
Deployment Issues
Problem: Pods stuck in “Pending” state
Possible causes and solutions:
- 
Insufficient resources
- Increase Docker Desktop resource allocation
 - Reduce resource requests in your deployment YAML
 
 - 
PersistentVolumeClaim issues
- Check if PVCs are bound:
kubectl get pvc - Ensure storage class exists:
kubectl get storageclass 
 - Check if PVCs are bound:
 - 
Node taints or affinity issues
- Check node conditions:
kubectl describe node docker-desktop 
 - Check node conditions:
 
Problem: “ImagePullBackOff” or “ErrImagePull” errors
Solutions:
- 
For local images, ensure they’re properly built and tagged:
docker images - 
For private repositories, configure image pull secrets:
kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<username> --docker-password=<password>Then reference this secret in your deployment YAML.
 - 
Check image name and tag for typos in your deployment YAML
 
Networking Issues
Problem: Cannot access services via NodePort
Solutions:
- 
Verify the service is running:
kubectl get services - 
Check if pods are running and ready:
kubectl get pods - 
Ensure the NodePort is accessible:
# Test connection curl http://localhost:<nodePort> - 
Check for firewall rules blocking the port
 
Problem: DNS resolution issues between pods
Solutions:
- 
Verify CoreDNS is running:
kubectl get pods -n kube-system | findstr coredns - 
Check DNS configuration:
kubectl exec -it <pod-name> -- cat /etc/resolv.conf - 
Test DNS resolution from within a pod:
kubectl exec -it <pod-name> -- nslookup kubernetes.default