Minikube Tutorial: Run Your First Kubernetes Cluster Locally

Posted November 22, 2025 by Karol Polakowski

Minikube is the fastest way to run a full Kubernetes cluster locally. It creates a single-node Kubernetes cluster inside a VM or container on your laptop and is ideal for development, learning, and CI experiments. This tutorial walks you through installing Minikube, starting a cluster, deploying a simple app, and practical commands for everyday use.

Prerequisites

Before you begin, ensure you have:

  • macOS, Linux, or Windows with virtualization support
  • Docker, Podman, Hyperkit, Hyper-V, or another supported driver installed (Docker is most common)
  • kubectl CLI (Kubernetes command-line tool)
  • 2GB+ RAM recommended

If you don’t have kubectl, you can install it via the official docs or with a package manager (Homebrew, apt, choco).

Install Minikube

Install via package manager or download the binary. Example: macOS/Linux using the official binary install (Linux/macOS):

# macOS / Linux (curl + install)
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
# or on macOS using Homebrew
# brew install minikube

# verify
minikube version

On Windows, use Chocolatey or the installer, or use Homebrew on WSL.

Start a local cluster

Start Minikube using the Docker driver (commonly available and fast):

# start a single-node cluster with the docker driver
minikube start --driver=docker --cpus=2 --memory=4096

# show status
minikube status

minikube provisions the node, runs a container runtime, and sets up kubeconfig so kubectl talks to the local cluster.

Verify cluster and nodes

Check cluster info and nodes with kubectl:

kubectl cluster-info
kubectl get nodes
kubectl get pods --all-namespaces

You should see one node in Ready state and cluster control plane endpoints.

Deploy your first app

Create a Deployment and Service for a simple nginx app. Save this manifest as nginx-deploy.yaml or apply directly.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:stable
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-svc
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP

Apply the manifest and check resources:

kubectl apply -f nginx-deploy.yaml
kubectl get deployments
kubectl get pods -l app=nginx
kubectl get svc nginx-svc

Accessing the service

Use minikube’s convenience commands to open the service in your browser or fetch the URL.

# opens the service in your default browser
minikube service nginx-svc

# or get the URL (useful in scripts)
minikube service nginx-svc --url

# alternative: port-forward to localhost
kubectl port-forward svc/nginx-svc 8080:80
# then visit http://localhost:8080

minikube service uses a tunnel or NodePort depending on driver to expose the service.

Useful kubectl + minikube commands

  • kubectl get all -n default: list all resources in namespace
  • kubectl describe pod : get detailed info and events
  • kubectl logs -f : stream container logs
  • minikube dashboard: launch Kubernetes dashboard
  • minikube ssh: get shell inside the Minikube VM/container
  • minikube addons list: view and enable addons (metrics-server, ingress, dashboard)

Enable ingress for testing Ingress resources:

minikube addons enable ingress

Common issues & troubleshooting

  • Driver errors: ensure your chosen driver (docker, hyperkit, hyperv) is installed and running.
  • Insufficient resources: increase –memory and –cpus when starting minikube.
  • Network issues: on macOS with Docker for Desktop, ensure virtualization and resources are enabled.
  • Stuck start: try minikube delete && minikube start to reset.

To inspect start logs:

minikube logs --file=minikube.log

Cleanup

Remove resources and stop the cluster when you’re done:

kubectl delete -f nginx-deploy.yaml
minikube stop
minikube delete

Deleting removes the VM/container and cluster state — useful to free disk and reset environment.

Next steps

  • Try deploying a multi-service app (backend + database)
  • Enable metrics-server and experiment with HPA (Horizontal Pod Autoscaler)
  • Use minikube mount to mount local folders into the cluster for live development
  • Integrate with Skaffold or Tilt for fast inner-loop development

Minikube provides a low-friction Kubernetes environment perfect for learning and local development. Once you’re comfortable, explore multi-node clusters (kind, k3d, or cloud-managed clusters) and CI integration for production-like testing.