Installing Minikube on Linux: A Detailed Guide for Ubuntu/Debian

Introduction / Why You Need This

Minikube is a tool that runs a local single-node Kubernetes cluster on your machine. It's perfect for:

• Learning and development: Allows you to study Kubernetes without cloud access or cost.
• Testing manifests: You can safely validate Deployment, Service, and Ingress configurations before deploying to production.
• Local debugging: Run and debug applications in an environment closely resembling real Kubernetes.

After completing this guide, you will have a fully functional Kubernetes cluster accessible via kubectl, and you'll be able to deploy your applications to it.

Prerequisites / Preparation

Before you begin, ensure your system meets the following requirements:

1. OS: Any modern Linux distribution (Ubuntu, Debian, Fedora, CentOS, Arch, etc.).
2. Virtualization: Enabled virtualization support (Intel VT-x / AMD-V) in BIOS/UEFI. You can verify with:

   grep -E --color '(vmx|svm)' /proc/cpuinfo
   

   If the output is empty, enable virtualization in your BIOS/UEFI settings.
3. Resources: Minimum 2 GB of free RAM (recommended 4+ GB) and 20 GB of free disk space.
4. Internet access: Required for downloading images and binaries.
5. Permissions: The user must have sudo privileges (for some drivers) and access to the Docker daemon (if using the docker driver).

Installing Required Components

1. Install Docker (Recommended Driver) Minikube can use Docker as the container runtime. Install Docker Engine:

# For Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y docker.io

# Add the current user to the docker group to avoid using sudo
sudo usermod -aG docker $USER
newgrp docker  # Apply group changes without reboot

Note: If you prefer Podman, install it (sudo apt install podman) and use the podman driver.

2. Install kubectlkubectl is the CLI tool for managing Kubernetes. Install it:

# Download the latest stable version
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Install
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Check version
kubectl version --client

3. Install Additional Utilities (Optional) Depending on your chosen driver, you might need:

• virtualbox: sudo apt install virtualbox
• kvm2: sudo apt install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils After installation, add your user to the kvm and libvirt groups.

Step-by-Step Guide

Step 1: Download and Install Minikube

Download the Minikube executable matching your architecture (usually amd64).

# Determine the latest version
MINIKUBE_VERSION=$(curl -L -s https://github.com/kubernetes/minikube/releases/latest | grep -oP '(?<=tag/v)[0-9.]+')

# Download
curl -LO https://github.com/kubernetes/minikube/releases/download/v${MINIKUBE_VERSION}/minikube-linux-amd64

# Install to system directory
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Clean up temporary file
rm minikube-linux-amd64

# Verify installation
minikube version

Step 2: Choose and Configure a Driver

Minikube uses drivers to create a virtual machine or container. The best choice for Linux is docker or podman, as they don't require additional virtualization and run faster.

Check which driver is available by default:

minikube driver list

For the docker driver (recommended): Ensure the Docker daemon is running and your user is in the docker group (see preparation). No minimal configuration is required.

For the kvm2 driver (alternative):

# Check if libvirtd is running
sudo systemctl status libvirtd

# If not, start and enable it
sudo systemctl enable --now libvirtd

You can explicitly specify the driver on first run: minikube start --driver=docker. To set the driver globally:

minikube config set driver docker

Step 3: Start the Minikube Cluster

Now start the cluster. Basic start with the docker driver:

minikube start --driver=docker

Configuring Resources (Important for Performance): It's recommended to explicitly specify memory and CPU, especially if you have limited resources or use a virtualization driver (virtualbox, kvm2).

# Example: 4 CPUs, 8 GB RAM, Kubernetes v1.28.x image
minikube start --driver=docker --cpus=4 --memory=8192 --kubernetes-version=v1.28.0

Command-line arguments:

• --driver: Driver (docker, podman, virtualbox, kvm2, none).
• --cpus: Number of virtual CPUs.
• --memory: RAM size in MB (e.g., 4096 for 4 GB).
• --disk-size: Disk size (default 20GB), e.g., --disk-size=50g.
• --kubernetes-version: Specific Kubernetes version (default is latest stable).

The process may take 2-5 minutes: Minikube downloads the ISO/Docker image with Kubernetes, configures networking, and starts cluster components.

Step 4: Verify Cluster Operation

After minikube start completes successfully, run:

# 1. Check cluster status
minikube status
# Expected output: host: Running, kubelet: Running, apiserver: Running, ...

# 2. View nodes (should be one - 'minikube')
kubectl get nodes
# NAME       STATUS   ROLES           AGE   VERSION
# minikube   Ready    control-plane   5m    v1.28.0

# 3. Check system pods (all should be in Running status)
kubectl get pods -A

Important: kubectl is automatically configured to work with the Minikube cluster thanks to a wrapper script. You can use minikube kubectl -- <command> for guarantee, but after minikube start, the minikube context is already active.

Verification

The cluster is considered successfully installed if all three conditions are met:

1. minikube status shows Running for all components.
2. kubectl get nodes outputs the minikube node with status Ready.
3. kubectl cluster-info shows the Kubernetes control plane and CoreDNS addresses.

You can also test by deploying a sample application:

kubectl create deployment hello-minikube --image=kicbase/echo-server:1.0
kubectl expose deployment hello-minikube --type=NodePort --port=8080
minikube service hello-minikube  # Will open the service in your browser

Troubleshooting

❌ Error: Failed to start host: Creating host: creating kic cluster: create: context deadline exceeded

Cause: The kicbase Docker image failed to download due to network issues or insufficient disk space. Solution:

1. Check free space (df -h).
2. Clean unused Docker images: docker system prune -a.
3. Force restart with cache cleanup: minikube delete && minikube start --driver=docker --force.

❌ Error: This computer doesn't have VT-x/AMD-v virtualization enabled

Cause: Virtualization is disabled in BIOS/UEFI. Solution: Reboot your computer, enter BIOS/UEFI (Del/F2/F10 key), and enable Intel VT-x or AMD-V. Save settings and reboot.

❌ Error: Exiting due to DRV_NOT_FOUND: The specified driver "docker" is not installed

Cause: The docker driver is not found (Docker not installed or not running). Solution: Install Docker and ensure the daemon is running (sudo systemctl start docker). Verify your user is in the docker group (groups $USER).

❌ Error: Failed to configure pod network: network plugin cni failed to set up...

Cause: CNI plugin conflict or firewall blocking. Solution:

1. Delete the cluster: minikube delete.
2. Temporarily disable the firewall (sudo ufw disable or sudo systemctl stop firewalld) and try again.
3. Use a different CIDR for the pod network: minikube start --pod-cidr=10.244.0.0/16.

❌ Error: Error: EACCES: permission denied, access '/var/run/docker.sock'

Cause: The current user lacks permissions to access the Docker socket. Solution: Add the user to the docker group (sudo usermod -aG docker $USER) and re-login or run newgrp docker.

❌ Issue: Minikube stops after host reboot

Cause: Minikube is not set to autostart (by design). Solution: This is expected behavior. Minikube is a development tool. For a permanent cluster, use a full Kubernetes deployment. To quickly restore the cluster, run minikube start.

Additional Commands and Management

• Stop cluster (preserves state): minikube stop
• Delete cluster (full cleanup): minikube delete
• Enable/disable addons (ingress, dashboard, metrics-server):

  minikube addons enable ingress
  minikube addons disable ingress
  

• Access the node's console (e.g., for Docker debugging): minikube ssh
• Get kubectl configuration for another context: minikube kubectl -- <kubectl command> or export: kubectl config use-context minikube.

Conclusion

You have successfully installed and launched a local Kubernetes cluster using Minikube on Linux. Now you can:

• Practice kubectl commands.
• Deploy YAML manifests.
• Test Helm charts.
• Experiment with various network policies and ingresses.

To continue learning, explore the official Kubernetes documentation or try deploying a simple application like Nginx by following our guide on basic Deployment and Service.

What's next? Learn how to manage cluster configuration via kubectl in our guide Configuring kubectl Contexts for Multiple Clusters.