Complete Guide to Installing Minikube on Ubuntu/Debian

Introduction / Why This Is Needed

Minikube is a tool that runs a single-cluster Kubernetes on your local machine. It's the perfect solution for developers and DevOps engineers who want to:

• Learn Kubernetes basics without access to a cloud cluster.
• Develop and test manifests (Deployment, Service, etc.) locally.
• Try new versions of Kubernetes or its components.

After completing this guide, you will have a fully functional Kubernetes cluster managed through the standard CLI tool kubectl.

Requirements / Preparation

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

1. OS: Ubuntu 22.04+, Debian 11+, or any other modern systemd-based distribution.
2. Privileges: Access to sudo for installing packages and managing services.
3. Resources:
   • RAM: minimum 2 GB, 4 GB recommended.
   • CPU: minimum 2 cores.
   • Disk Space: minimum 20 GB of free space.
4. Virtualization driver: We will use Docker as the driver, as it's the simplest path on Linux. You must have Docker installed and running.

Step-by-Step Guide

Step 1: Installing and Starting Docker

Minikube requires a working container runtime. Docker is the most robust choice.

# Update package cache
sudo apt-get update

# Install necessary packages for working with HTTPS repositories
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository (for Ubuntu, replace accordingly for Debian)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and components
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

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

# Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Verify Docker is running
docker run hello-world

If the docker run hello-world command finishes with the output "Hello from Docker!", the driver is ready.

Step 2: Installing Minikube

We will download the latest stable version of Minikube from the official GitHub repository.

# Determine the latest version (at time of writing — v1.33.1)
MINIKUBE_VERSION="v1.33.1"
# Download the binary
curl -LO https://storage.googleapis.com/minikube/releases/${MINIKUBE_VERSION}/minikube-linux-amd64

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

# Verify installation
minikube version

Step 3: Starting the Minikube Cluster

Now you can create and start the cluster. We will explicitly specify the docker driver and allocate 4 GB of RAM.

# Stop previous cluster if it exists (optional)
minikube stop

# Start a new cluster with parameters:
# --driver=docker: use Docker as the virtualization driver
# --memory='4g': allocate 4 GB RAM
# --cpus=2: allocate 2 CPU cores
minikube start --driver=docker --memory='4g' --cpus=2

⚠️ Important: The first start may take 5-10 minutes, as Minikube will download Kubernetes images (k8s.gcr.io/kube-apiserver, etc.) that are several hundred megabytes in size.

After successful completion, you will see the message Done! kubectl is now configured to use "minikube" cluster....

Step 4: Verifying Functionality and Configuring kubectl

Let's ensure the cluster is running and accessible via kubectl.

# Show cluster status
minikube status

# Should output with all components in Running state.
# Example:
# host: Running
# kubelet: Running
# apiserver: Running
# kubeconfig: Configured

# Check cluster accessibility via kubectl
kubectl cluster-info

# Get list of nodes (in Minikube there is always one)
kubectl get nodes

# Test deployment: create an nginx pod
kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --type=NodePort --port=80

# Verify the pod is running
kubectl get pods,svc

# Get the URL to access nginx in a browser
minikube service nginx

Step 5: Useful Commands and Configuration

• Stop the cluster (preserves state):

  minikube stop
  

• Delete the cluster (full cleanup):

  minikube delete
  

• Access the node console (as a virtual machine):

  minikube ssh
  

• Set default driver (to avoid specifying --driver each time):

  minikube config set driver docker
  

• Update Minikube:

  minikube update
  

Verification

Run the following commands. If all return successful results (Running, object lists), the installation was correct:

1. minikube status — all components Running.
2. kubectl get nodes — node in Ready status.
3. kubectl get pods -A — system pods (coredns, etcd, kube-apiserver, etc.) in Running status.
4. minikube service list — services you created are displayed.

Potential Issues

Issue: minikube start fails with error Failed to start host: ...

Cause and solution:

• Insufficient memory/CPU. Increase --memory and --cpus parameters. For example, --memory=6g --cpus=3.
• Port 8443 is occupied (used by another process or another Minikube cluster). Stop the conflicting process or delete the old cluster (minikube delete).
• Docker is not running. Check systemctl status docker. If the service is inactive, start it.

Issue: kubectl not found or kubectl: command not found

Cause and solution: Install kubectl separately.

# Install kubectl (latest version)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl version --client

Issue: Errors like Error: failed to pull image ... or ImagePullBackOff

Cause and solution: Minikube/Docker cannot download the image from k8s.gcr.io. This is usually a network or DNS issue. Check internet access on the machine. You can try using a different registry (e.g., registry.k8s.io) or configure a proxy for Docker.

Issue: minikube ssh doesn't work or hangs

Cause and solution: Problem with the driver. Ensure the Docker container with the cluster exists: docker ps | grep minikube. If the container isn't running, try minikube start --alsologtostderr for detailed logs and minikube delete followed by a clean start.