Set Up Minikube Cluster

Setting up a local Kubernetes cluster can feel like a daunting task—especially when you're a Python developer who just wants to test your Flask API or FastAPI service without spinning up costly cloud infrastructure. You've heard the buzzwords: pods, deployments, services, nodes—but where do you actually start? The answer is Minikube, the simplest way to run a feature-complete Kubernetes cluster on your own machine. In this lesson, you'll learn how to set up a local Kubernetes cluster with Minikube in minutes, understand what's happening under the hood, and be ready to deploy your first Python app in the next lesson.

The problem this lesson solves

Kubernetes is the industry standard for container orchestration, but the learning curve is steep. Many developers never get past the tutorials because they don't have a reliable, local environment to experiment in. You could rent a managed cluster from a cloud provider, but that introduces: costs (even a tiny cluster can rack up bills), latency (every command hitting a remote API), and configuration overhead (IAM, VPCs, and other distractions). You need a way to run Kubernetes locally—fast, free, and safely.

Minikube solves exactly this problem. It gives you a single-node Kubernetes cluster that runs on your laptop or workstation, using virtualization or container runtimes you already have. You can execute kubectl commands, deploy real workloads, and test your Python services exactly as they'd run in production—but without leaving your local machine. This lesson walks you through the entire setup, from installation to verification, so you can start building with confidence.

Core concept / mental model

Think of Kubernetes as a conductor for your containerized applications. Just as a conductor coordinates an orchestra—ensuring each musician plays at the right time, in harmony—Kubernetes coordinates containers, ensuring they start, run, and communicate correctly. A cluster is the set of machines (virtual or physical) that Kubernetes uses to run your workloads. Even a single-machine cluster is a real cluster; it has a control plane (the brain) and at least one node (the worker).

Minikube's job is to be the stage manager: it sets up that single-node orchestra on your local machine. It creates a lightweight virtual machine (or uses your local container runtime) that acts as the node, installs the necessary Kubernetes components, and gives you a command-line tool to start, stop, and manage the cluster.

The key pieces you'll interact with: - kubectl: The command-line tool that talks to your cluster's API server. It's how you send commands to Kubernetes (e.g., deploy a pod, check logs). - Minikube CLI: The tool that manages the cluster lifecycle itself (start, stop, delete, dashboard). - Docker: Minikube uses Docker to build and run containers—either inside the VM or directly, depending on your driver.

Pro tip: Think of kubectl as your remote control for the cluster, and minikube as the power button and maintenance crew. You'll use both constantly.

How it works step by step

Setting up a local cluster with Minikube follows a predictable sequence. Here's the high-level flow, from installation to a working cluster:

1. Install prerequisites — You need kubectl, a container runtime (Docker), and a hypervisor (if you're using the default VM driver).
2. Install Minikube — Download the binary or package for your OS.
3. Start the cluster — Run minikube start with your driver of choice. This creates the node, installs Kubernetes, and configures kubectl to talk to it.
4. Verify the cluster — Use kubectl cluster-info and kubectl get nodes to confirm everything is up.
5. Explore the dashboard (optional) — The web UI gives you a visual overview of your cluster's health and resources.

The minikube start command does a lot: it downloads the Kubernetes binaries, creates a VM or container-based node, initializes the control plane, and configures your local kubectl context. The result is a fully functional cluster that behaves just like a cloud-based one—but lives in your machine.

Hands-on walkthrough

Let's get our hands dirty. We'll go through the setup on a macOS/Linux environment (use the official docs for Windows specifics). Open a terminal and follow along.

Step 1: Install kubectl

If you don't have kubectl yet, install it. On macOS with Homebrew:

brew install kubectl

On Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install -y kubectl

Verify with:

kubectl version --client

You should see output like Client Version: v1.29.0 — the exact version may vary.

Step 2: Install Minikube

On macOS:

brew install minikube

On Linux, the easiest way is to download the binary directly:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Check it worked:

minikube version

Step 3: Start your cluster

The default driver uses Docker—you'll need Docker installed and running. If you have it, simply run:

minikube start

This process may take a few minutes on first run because it downloads images. You'll see output like:

😄  minikube v1.31.2 on Darwin 14.0
✨  Using the docker driver based on existing profile
👍  Starting control plane node minikube in cluster minikube
🔥  Creating docker container (CPUs=2, Memory=2048MB) ...
🐳  Preparing Kubernetes v1.28.3 on Docker 24.0.7 ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🏠  Configuring lookaside cache ...
🚜  Pulling images ...
🏄  Done! kubectl is now configured to use "minikube" cluster

If you don't want to use Docker (maybe you're on Linux without it), you can specify a driver like --driver=none to run directly on the host, or --driver=virtualbox if you have VirtualBox. For example:

minikube start --driver=virtualbox

Step 4: Verify the cluster

Once the start command finishes, check that the cluster is healthy:

kubectl cluster-info

Output should include the control plane and CoreDNS endpoints. Then list your nodes:

kubectl get nodes

You should see something like:

NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   2m    v1.28.3

Notice the node is named minikube—that's your single-node cluster, running the control plane and worker roles together.

Step 5: Explore the built-in dashboard

Minikube comes with a web dashboard. Launch it with:

minikube dashboard

This opens a browser window showing the cluster's CPU/memory usage, running pods, deployments, and more. It's great for visual verification—you'll see an empty cluster (no workloads yet, but healthy).

Step 6: Run a quick sanity test

To prove your cluster can run real workloads, deploy a simple nginx container:

kubectl create deployment web --image=nginx
kubectl get pods

You'll see a pod created and, within a few seconds, reach Running status. This confirms your local cluster is ready for the Python apps you'll deploy in upcoming lessons.

Compare options / when to choose what

Minikube isn't the only way to run Kubernetes locally. Here's a quick comparison with other popular options so you know when to choose what.

When to choose Minikube? If you're just starting out, want a one-command setup, and need a reliable local cluster for development. When to choose something else? If you need multiple nodes to test scheduling, you're setting up a CI pipeline (kind is ideal there), or you're running on resource-constrained Linux servers (k3s is excellent).

Pro tip: Minikube supports minikube start --nodes=3 to create a multi-node cluster, but it's still not as robust as kind for that use case. Stick with single-node for now.

Troubleshooting & edge cases

Even with a simple tool like Minikube, things can go wrong. Here are the most common issues and how to fix them.

Docker not running

If you get Docker is not running or Cannot connect to the Docker daemon, start Docker first. On macOS, launch Docker Desktop; on Linux, run:

sudo systemctl start docker

Then retry minikube start.

Driver conflicts

If you previously used VirtualBox and now want Docker, you may see a driver mismatch. Fix it by deleting the old profile:

minikube delete
minikube start --driver=docker

Resource limits

If the cluster fails to start due to insufficient resources, you might need to increase memory or CPU. For example:

minikube start --memory=4096 --cpus=4

This gives the VM 4GB RAM and 4 CPUs.

kubectl not pointing to minikube

If kubectl get nodes returns an error about connecting to a different cluster, switch the context:

kubectl config use-context minikube

Persistent storage in a VM

Edge case: If you're running Minikube with a VM driver (e.g., VirtualBox), the default storage driver may not persist data across restarts. To be safe, use the Docker driver (which stores data in containers) or configure the --disk-size flag. But for now, you won't need persistent storage.

Windows-specific issues

On Windows, you may need to run the terminal as administrator. Also, Docker Desktop must be using WSL 2 backend for best compatibility. If you hit Hyper-V issues, switch to VirtualBox driver.

Pro tip: When in doubt, run minikube logs to see detailed cluster logs. It's your best friend for debugging stubborn startup issues.

What you learned & what's next

Congratulations! You've successfully set up a local Kubernetes cluster with Minikube. You understand the mental model of clusters, nodes, and control planes; you know how kubectl and minikube work together; and you can start, verify, and stop your local environment. You've also compared Minikube with alternatives and can troubleshoot common problems like Docker not running or driver conflicts.

Now that you have a running cluster, it's time to deploy your first Python app. In the next lesson, you'll create a simple Flask service, package it as a container, and run it on your Minikube cluster using deployments and services. You're now fully equipped to move forward with hands-on Kubernetes for Python.

Keep this lesson handy—you'll reuse minikube start often. Before moving on, make sure you can stop your cluster with minikube stop and restart it later. That's your practice for mastering local Kubernetes.