Minikube Getting Started Guide

This guide explains Kubernetes and Minikube from absolute zero. No prior knowledge required.

Part 1: What Problem Does Kubernetes Solve?

Before learning the tools, you need to understand WHY Kubernetes exists.

The Old Way: One Application, One Server

Imagine you have a web application. In the old days, you would:

1. Buy or rent a physical server

2. Install the operating system

3. Install your application

4. If traffic increases, buy a BIGGER server (expensive!)

5. If the server crashes, your application is DOWN until you fix it

Problems:

• Wasted resources (server runs at 10% capacity most of the time)

• Scaling is slow and expensive

• Single point of failure

The Container Way: Package Everything Together

Docker solved part of this problem. Instead of installing applications directly on servers, you package them into containers.

A container is like a shipping container - it contains everything your application needs to run, packaged together. You can move it anywhere and it works the same way.

But containers alone don't solve everything:

• How do you run 100 containers across 10 servers?

• What happens when a container crashes?

• How do containers find each other on the network?

• How do you update containers without downtime?

Enter Kubernetes: The Container Orchestrator

Kubernetes is an orchestrator - it manages containers at scale. Think of it as an automated system administrator that:

• Decides which server should run which container

• Restarts containers that crash

• Scales up/down based on traffic

• Routes network traffic to the right containers

• Rolls out updates without downtime

Analogy: If containers are musicians, Kubernetes is the conductor of the orchestra.

Part 2: Kubernetes Core Concepts (The Vocabulary)

Before touching any tools, you MUST understand these terms. Every Kubernetes tutorial assumes you know them.

Cluster

A cluster is a group of computers (servers) working together as one system.

When you deploy to Kubernetes, you deploy to "the cluster" - you don't care which specific server runs your app. Kubernetes decides that for you.

Minikube creates a cluster with just ONE server (your laptop). In production, clusters have many servers.

Node

A node is a single server (computer) in the cluster. It can be:

• A physical machine in a data center

• A virtual machine in the cloud (like an Azure VM)

• A container on your laptop (how Minikube works)

Types of nodes:

Node Type	What it does
Control Plane (Master)	The "brain" - makes decisions, stores cluster state
Worker Node	Runs your actual applications

In Minikube, both roles run on the same node (your laptop).

Pod

A pod is the smallest deployable unit in Kubernetes. It's a wrapper around one or more containers.

Why not just use containers directly?

• Pods provide a shared network namespace (containers in the same pod share an IP address)

• Pods can share storage volumes

• Pods allow "sidecar" patterns (helper containers next to your main app)

In practice: Most pods contain just ONE container. Think of a pod as "a running instance of your application."

Key insight: Pods are temporary. They get created, they run, they die. Kubernetes can delete and recreate pods at any time. Never rely on a specific pod existing.

Deployment

A deployment tells Kubernetes: "I want X copies of this application running at all times."

If one pod crashes, the deployment automatically creates a new one to maintain the count.

Deployment vs Pod:

Concept	What it is	Analogy
Pod	One running instance	One employee
Deployment	Desired state ("keep 3 running")	HR policy ("always have 3 people in this role")

You almost never create pods directly. You create deployments, and Kubernetes creates the pods.

Service

Problem: Pods are temporary and get new IP addresses when recreated. How do other applications find them?

Solution: A service is a stable network endpoint that routes traffic to pods.

The service has a stable IP/name. Even if pods die and get replaced (with new IPs), the service keeps working.

Types of services:

Type	What it does	Use case
ClusterIP	Only accessible inside the cluster	Backend services, databases
NodePort	Exposes on a port on every node	Development, testing
LoadBalancer	Gets a public IP from cloud provider	Production web apps

Namespace

A namespace is a way to organize resources in a cluster. Think of it like folders on your computer.

Cluster
├── Namespace: default          (your apps go here by default)
├── Namespace: kube-system      (Kubernetes internal stuff)
├── Namespace: production       (you might create this)
└── Namespace: development      (you might create this)

Namespaces let you:

• Organize resources by team, project, or environment

• Apply different permissions to different namespaces

• Set resource limits per namespace

For learning with Minikube: You'll use the default namespace. You don't need to think about this much yet.

Container Image

A container image is a packaged application - the "recipe" for creating containers.

Images are stored in registries like:

• Docker Hub (hub.docker.com)

• Azure Container Registry

• Google Container Registry

When you tell Kubernetes to run an application, you specify the image name (e.g., nginx:1.24), and Kubernetes downloads it and runs it.

Putting It All Together

Here's how all these pieces connect:

Part 3: What is Minikube?

Now that you understand Kubernetes concepts, we can talk about Minikube.

Problem: Setting up a real Kubernetes cluster requires multiple servers, networking, and complex configuration. Not practical for learning.

Solution: Minikube creates a single-node Kubernetes cluster on your laptop.

Everything you learn on Minikube works exactly the same on real clusters. The only difference is scale.

Part 4: Installation

Step 4.1: Install Minikube

macOS (with Homebrew):

brew install minikube

Windows (with Chocolatey):

choco install minikube

Linux (binary download):

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

Step 4.2: Verify Installation

minikube version

You should see something like: minikube version: v1.32.0

Part 5: Understanding kubectl and Minikube

This is where most confusion happens. Let me explain clearly.

What Are These Two Tools?

Tool	What it does
minikube	Creates and runs a local Kubernetes cluster on your laptop
kubectl	Communicates with ANY Kubernetes cluster (local or cloud)

Think of it like this:

• minikube = The Kubernetes cluster itself (the server)

• kubectl = The remote control to talk to the cluster (the client)

The Recommended Setup: Install BOTH

For the cleanest experience with no confusion later, install both tools separately:

macOS:

brew install minikube
brew install kubectl

Windows:

choco install minikube
choco install kubernetes-cli

Linux:

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

# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install kubectl /usr/local/bin/kubectl

Verify both are installed:

minikube version
kubectl version --client

Why Install Both? Why Not Just Use the Alias?

You might see guides suggesting this alias:

alias kubectl="minikube kubectl --"

Don't do this. Here's why:

Problem	What happens
You connect to Azure AKS later	The alias still runs minikube kubectl -- instead of real kubectl
You uninstall minikube	All your kubectl commands break
Version mismatch	Minikube's built-in kubectl may be older than what the cloud requires
Confusion	You forget the alias exists and wonder why things behave strangely

The alias is a shortcut that creates problems later. Just install both tools and avoid the confusion.

How kubectl Knows Which Cluster to Talk To

When you run kubectl get pods, how does kubectl know whether to talk to Minikube or Azure?

The answer is the kubeconfig file at ~/.kube/config. This file stores:

• List of clusters you can connect to

• Credentials for each cluster

• Which cluster is currently "active"

When you run minikube start, Minikube automatically:

1. Creates the cluster

2. Adds it to your ~/.kube/config

3. Sets it as the active cluster

So after minikube start, any kubectl command automatically goes to Minikube.

Later, when you connect to Azure AKS:

az aks get-credentials --resource-group myRG --name myCluster

This adds AKS to your config and makes it active. Now kubectl commands go to Azure.

To switch between clusters:

# See all clusters in your config
kubectl config get-contexts

# Switch to minikube
kubectl config use-context minikube

# Switch to Azure (name depends on your cluster)
kubectl config use-context myCluster

What About "minikube kubectl --"?

Yes, Minikube has kubectl built-in. You CAN use it like this:

minikube kubectl -- get pods

When would you use this?

• If you absolutely cannot install kubectl separately

• For quick testing when kubectl isn't installed

But for normal use: Just install kubectl separately. It's cleaner.

Summary: The Right Setup

# Install both tools
brew install minikube
brew install kubectl

# Start the cluster
minikube start

# Now use kubectl normally
kubectl get pods
kubectl get services

No aliases. No confusion. This works with Minikube today and with Azure/AWS/GCP tomorrow.

Part 6: Starting and Stopping Minikube

Step 3.1: Start Your Cluster

minikube start

This creates a virtual machine (or container) and installs Kubernetes inside it. First run takes 2-5 minutes.

You should see output like:

😄  minikube v1.37.0 on Darwin 26.2 (arm64)
✨  Automatically selected the docker driver. Other choices: qemu2, vmware, ssh
📌  Using Docker Desktop driver with root privileges
👍  Starting "minikube" primary control-plane node in "minikube" cluster
🚜  Pulling base image v0.0.48 ...
💾  Downloading Kubernetes v1.34.0 preload ...
    > preloaded-images-k8s-v18-v1...:  332.38 MiB / 332.38 MiB  100.00% 24.82 M
    > gcr.io/k8s-minikube/kicbase...:  450.06 MiB / 450.06 MiB  100.00% 29.16 M
🔥  Creating docker container (CPUs=2, Memory=12200MB) ...
🐳  Preparing Kubernetes v1.34.0 on Docker 28.4.0 ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Step 3.2: Check Cluster Status

minikube status

Expected output:

minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

Step 3.3: Stop Your Cluster (saves resources)

minikube stop

This shuts down the VM but preserves your data. You can start it again later.

Step 3.4: Delete Your Cluster (complete reset)

minikube delete

This removes everything. Use this if something is broken and you want to start fresh.

Part 7: Essential Navigation Commands

Every kubectl command follows this pattern:

kubectl <action> <resource-type> [name] [flags]

Part	Examples
action	get, describe, delete, create, apply, logs, exec
resource-type	pods, services, deployments, nodes
name	(optional) specific resource name
flags	-o wide, -n namespace, -f filename

kubectl get - List Resources

Lists resources in your cluster.

kubectl get pods                    # List all pods
kubectl get services                # List all services (or: kubectl get svc)
kubectl get deployments             # List all deployments (or: kubectl get deploy)
kubectl get all                     # List pods, services, deployments together

Common flags:

Flag	What it does
-o wide	Show more columns (IPs, nodes)
-n kube-system	Look in specific namespace
-A	Look in ALL namespaces
-w	Watch for changes (live updates)

Understanding the output:

NAME            READY   STATUS    RESTARTS   AGE
nginx-abc123    1/1     Running   0          5m

Column	Meaning
NAME	Pod's name (auto-generated from deployment + random suffix)
READY	Ready containers / Total (1/1 means 1 container, it's ready)
STATUS	Running, Pending, Error, CrashLoopBackOff, etc.
RESTARTS	How many times the container crashed and restarted
AGE	Time since pod was created

kubectl describe - Get Details

Shows detailed information about a resource. Use when debugging.

kubectl describe pod nginx-abc123
kubectl describe service my-service
kubectl describe deployment my-app

The output includes configuration, status, and Events - the Events section tells you why something failed.

kubectl logs - View Container Output

Shows what the application is printing (stdout/stderr).

kubectl logs nginx-abc123           # View logs
kubectl logs -f nginx-abc123        # Follow logs live (like tail -f)
kubectl logs --tail=50 nginx-abc123 # Last 50 lines only
kubectl logs -p nginx-abc123        # Logs from previous (crashed) container

Press Ctrl+C to stop following logs.

kubectl exec - Run Commands Inside Container

Run commands inside a running container. Like SSH for containers.

kubectl exec nginx-abc123 -- ls /app           # Run single command
kubectl exec -it nginx-abc123 -- /bin/sh       # Open interactive shell

The -- is important - it separates kubectl flags from the command to run inside.

The -it flags:

• -i = interactive (keep stdin open so you can type)

• -t = tty (allocate a terminal so you get a proper prompt)

Type exit to leave the container.

kubectl delete - Remove Resources

kubectl delete pod nginx-abc123           # Delete specific pod
kubectl delete deployment nginx           # Delete deployment (and its pods)
kubectl delete pod pod1 pod2 pod3         # Delete multiple
kubectl delete pods --all                 # Delete all pods (careful!)

Note: If you delete a pod created by a deployment, Kubernetes immediately creates a replacement. Delete the deployment to permanently remove.

kubectl create - Create Resources

kubectl create deployment nginx --image=nginx:1.24

This creates a deployment named "nginx" using the nginx:1.24 container image.

kubectl apply - Create or Update from File

kubectl apply -f my-deployment.yaml       # Create or update from YAML file

Difference from create:

Command	If already exists	If doesn't exist
kubectl create	ERROR	Creates it
kubectl apply	Updates it	Creates it

Use apply - it's safer.

Quick Reference

Goal	Command
List pods	kubectl get pods
List pods with IPs	kubectl get pods -o wide
List services	kubectl get svc
List everything	kubectl get all
Pod details	kubectl describe pod <name>
View logs	kubectl logs <pod>
Follow logs	kubectl logs -f <pod>
Shell into container	kubectl exec -it <pod> -- /bin/sh
Delete pod	kubectl delete pod <name>
Delete deployment	kubectl delete deployment <name>
Apply YAML	kubectl apply -f <file.yaml>

Part 8: Namespaces - Organizing Your Cluster

Namespaces are like folders for organizing resources. Minikube has these by default:

kubectl get namespaces

Output:

NAME              STATUS   AGE
default           Active   5m
kube-system       Active   5m
kube-public       Active   5m
kube-node-lease   Active   5m

Namespace	Purpose
default	Where your applications go (unless you specify otherwise)
kube-system	Kubernetes internal components (don't touch)
kube-public	Publicly readable data (rarely used)
kube-node-lease	Node heartbeat data (internal)

Working with Namespaces

# List pods in a specific namespace
kubectl get pods -n kube-system

# List pods in ALL namespaces
kubectl get pods -A

# Create a new namespace
kubectl create namespace my-project

# Set default namespace for your session
kubectl config set-context --current --namespace=my-project

Part 9: Minikube-Specific Features

Accessing Services (LoadBalancer)

In cloud Kubernetes, LoadBalancer services get public IPs. Minikube can't do this, so use:

# Opens the service in your browser
minikube service <service-name>

# Just get the URL without opening browser
minikube service <service-name> --url

Minikube Dashboard (Visual Interface)

minikube dashboard

This opens a web-based UI where you can see all resources visually.

Enabling Add-ons

Minikube has optional features you can enable:

# List available add-ons
minikube addons list

# Enable metrics server (for resource monitoring)
minikube addons enable metrics-server

# Enable ingress controller (for routing HTTP traffic)
minikube addons enable ingress

SSH into Minikube VM

minikube ssh

This gives you a shell inside the Minikube virtual machine.

Part 10: Your First Deployment

Let's deploy a simple application to verify everything works.

Step 10.1: Create a Deployment

kubectl create deployment hello-node --image=registry.k8s.io/e2e-test-images/agnhost:2.39 -- /agnhost netexec --http-port=8080

Step 10.2: Check the Deployment

kubectl get deployments
kubectl get pods

Wait until the pod shows STATUS: Running.

Step 10.3: Expose as a Service

kubectl expose deployment hello-node --type=LoadBalancer --port=8080

Step 10.4: Access the Service

minikube service hello-node

Your browser should open showing the application.

Step 10.5: Clean Up

kubectl delete service hello-node
kubectl delete deployment hello-node

Part 11: Common Issues and Solutions

Issue: "minikube start" hangs or fails

# Try with a different driver
minikube start --driver=docker

# Or completely reset
minikube delete
minikube start

Issue: kubectl commands fail with connection error

# Check if minikube is running
minikube status

# If not running, start it
minikube start

# Verify kubectl is configured correctly
kubectl config current-context
# Should show: minikube

Issue: Not enough resources

# Start with more memory/CPU
minikube start --memory=4096 --cpus=2

Part 12: Quick Reference Card

Command	What it does
minikube start	Start the cluster
minikube stop	Stop (preserve data)
minikube delete	Delete everything
minikube status	Check if running
minikube dashboard	Open web UI
minikube service <name>	Access a service
minikube ssh	Shell into VM
kubectl get pods	List pods
kubectl get services	List services
kubectl get all	List everything
kubectl describe <type> <name>	Detailed info
kubectl logs <pod>	View pod logs
kubectl exec -it <pod> -- sh	Shell into pod
kubectl apply -f file.yaml	Deploy from file
kubectl delete -f file.yaml	Remove from file

Summary: The Mental Model

Think of it like this:

• Minikube = Virtual machine containing Kubernetes

• kubectl = Remote control that talks to Kubernetes API

• Pods = Your running containers

• Services = Network access to your pods

You're now ready to explore Kubernetes!