Introduction

Minikube is a powerful, lightweight implementation of Kubernetes that enables developers to run a single-node Kubernetes cluster on their local machine. This tool is invaluable for developers, DevOps engineers, and IT professionals who need to work with Kubernetes in a development or testing environment.

The primary purpose of Minikube is to provide a simple, accessible way to learn and experiment with Kubernetes without the complexity and cost of a full-scale cluster. It offers a perfect sandbox for developing, testing, and debugging Kubernetes applications.

Before proceeding with the installation, users should have basic familiarity with:

• Command-line interfaces
• Container concepts
• Basic Kubernetes terminology

System Requirements and Prerequisites

Hardware Requirements

To run Minikube effectively, your system should meet these minimum specifications:

• CPU: 2 cores minimum
• Memory: 2GB RAM (4GB recommended)
• Storage: 20GB free disk space
• Active internet connection

Software Prerequisites

Before installing Minikube, ensure you have:

• Container Runtime:
  • Docker (recommended)
  • Podman
  • ContainerD
• Hypervisor (OS-specific):
  • macOS: HyperKit or VirtualBox
  • Linux: KVM or VirtualBox
• kubectl command-line tool
• Virtual Machine manager compatible with your OS

Installation Process

Linux Installation Guide

Binary Installation

# Download the latest Minikube binary for Linux
curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-linux-amd64
   
# Make the binary executable and move it to a directory in your PATH
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Package Manager Installation

Debian/Ubuntu

# Install Minikube using the apt package manager
sudo apt install minikube

Fedora

# Install Minikube using the dnf package manager
sudo dnf install minikube

Installing kubectl

Linux Installation

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

# Make kubectl executable and install it in a system directory
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Creating Your First Kubernetes Cluster

Basic Cluster Creation

Starting a Cluster

# Create and start a single-node Kubernetes cluster
minikube start

The output should look something along these lines:

😄  minikube v1.35.0 on Ubuntu 24.04
✨  Automatically selected the docker driver. Other choices: none, ssh
📌  Using Docker driver with root privileges
👍  Starting "minikube" primary control-plane node in "minikube" cluster
🚜  Pulling base image v0.0.46 ...
💾  Downloading Kubernetes v1.32.0 preload ...
    > preloaded-images-k8s-v18-v1...:  333.57 MiB / 333.57 MiB  100.00% 1.24 Mi
    > gcr.io/k8s-minikube/kicbase...:  500.31 MiB / 500.31 MiB  100.00% 1.36 Mi
🔥  Creating docker container (CPUs=2, Memory=7900MB) ...
🐳  Preparing Kubernetes v1.32.0 on Docker 27.4.1 ...
    ▪ Generating certificates and keys ...
    ▪ Booting up control plane ...
    ▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
💡  kubectl not found. If you need it, try: 'minikube kubectl -- get pods -A'
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

This command could take several minutes depending on our internet connection.

Verifying Installation

# Check the status of your Minikube cluster
minikube status

Output:

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

Checking Cluster Information

# Display information about the Kubernetes control plane and services
kubectl cluster-info

Output:

Kubernetes control plane is running at https://192.168.49.2:8443
CoreDNS is running at https://192.168.49.2:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Advanced Configuration Options

Custom Resource Allocation

# Start Minikube with custom CPU and memory allocation
minikube start --cpus=4 --memory=8192mb

Specific Driver Selection

# Start Minikube using the VirtualBox driver
minikube start --driver=virtualbox

Multi-node Setup

# Create a Minikube cluster with 3 nodes (1 control plane + 2 workers)
minikube start --nodes=3

Deploying Your First Application

Hello World Deployment

Let’s deploy a simple “Hello World” application to verify your Kubernetes cluster is working properly:

Creating the Deployment File

Create a file named hello-world.yaml:

# Deployment defines how many pods to run and how to update them
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
spec:
  replicas: 2  # Run 2 identical pods for redundancy
  selector:
    matchLabels:
      app: hello-world  # Select pods with this label
  template:
    metadata:
      labels:
        app: hello-world  # Label for the pod
    spec:
      containers:
      - name: hello-world
        image: paulbouwer/hello-kubernetes:1.10  # Container image to use
        ports:
        - containerPort: 8080  # Port the container listens on
---
# Service exposes the deployment to network traffic
apiVersion: v1
kind: Service
metadata:
  name: hello-world
spec:
  type: NodePort  # Makes the service accessible outside the cluster
  ports:
  - port: 80  # Port the service listens on
    targetPort: 8080  # Port to forward to in the pod
  selector:
    app: hello-world  # Route traffic to pods with this label

Applying the Deployment

# Create resources defined in the YAML file
kubectl apply -f hello-world.yaml

Output:

deployment.apps/hello-world created
service/hello-world created

Checking Running Pods

# List all pods in the current namespace
kubectl get pods

You should see output similar to:

NAME                           READY   STATUS    RESTARTS   AGE
hello-world-6b554d9b87-2kvxn   1/1     Running   0          45s
hello-world-6b554d9b87-89dfc   1/1     Running   0          45s

Accessing the Application

# Open a browser window to access the service
minikube service hello-world

This command will automatically open your browser to the application URL, showing a simple “Hello Kubernetes!” web page.

Deleting the Deployment

# Remove all resources defined in the YAML file
kubectl delete -f hello-world.yaml

Output:

deployment.apps "hello-world" deleted
service "hello-world" deleted

Real-World Example: Deploying a WordPress Blog with MySQL Database

Let’s deploy a WordPress blog with a MySQL database backend:

Creating the WordPress Deployment File

Create a file named wordpress-app.yaml:

# MySQL Database Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  replicas: 1  # Single MySQL instance
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - name: mysql
        image: mysql:5.7  # MySQL container image
        ports:
        - containerPort: 3306  # MySQL default port
        env:
        - name: MYSQL_ROOT_PASSWORD  # Root password for MySQL
          value: "rootpassword"
        - name: MYSQL_DATABASE  # Database to create
          value: "wordpress"
        - name: MYSQL_USER  # MySQL user for WordPress
          value: "wordpress"
        - name: MYSQL_PASSWORD  # Password for WordPress user
          value: "wordpress"  # For production, use Kubernetes Secrets
        volumeMounts:
        - name: mysql-data  # Mount for persistent storage
          mountPath: /var/lib/mysql
      volumes:
      - name: mysql-data
        emptyDir: {}  # For persistence in production, use PersistentVolumeClaim
---
# MySQL Service - internal access only for WordPress
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  selector:
    app: mysql  # Selects the MySQL pod
  ports:
  - port: 3306  # Service port
    targetPort: 3306  # Container port
---
# WordPress Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wordpress
spec:
  replicas: 1  # Single WordPress instance
  selector:
    matchLabels:
      app: wordpress
  template:
    metadata:
      labels:
        app: wordpress
    spec:
      containers:
      - name: wordpress
        image: wordpress:5.9-apache  # WordPress container image
        ports:
        - containerPort: 80  # WordPress runs on port 80
        env:
        - name: WORDPRESS_DB_HOST  # Database hostname
          value: "mysql"  # Matches the MySQL service name
        - name: WORDPRESS_DB_USER  # Database user
          value: "wordpress"
        - name: WORDPRESS_DB_PASSWORD  # Database password
          value: "wordpress"
        - name: WORDPRESS_DB_NAME  # Database name
          value: "wordpress"
---
# WordPress Service - exposed externally
apiVersion: v1
kind: Service
metadata:
  name: wordpress
spec:
  type: NodePort  # Makes WordPress accessible outside the cluster
  selector:
    app: wordpress  # Selects WordPress pods
  ports:
  - port: 80  # Service port
    targetPort: 80  # Container port

Deploying the WordPress Stack

# Create all resources defined in the wordpress-app.yaml file
kubectl apply -f wordpress-app.yaml

Output:

deployment.apps/mysql created
service/mysql created
deployment.apps/wordpress created
service/wordpress created

Verifying All Components

# List all resources in the current namespace
kubectl get all

You should see the MySQL and WordPress deployments, pods, and services.

NAME                             READY   STATUS    RESTARTS   AGE
pod/mysql-58ddcf7bf5-xxvq2       1/1     Running   0          2m35s
pod/wordpress-7f554bd4f5-strx2   1/1     Running   0          2m35s

NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
service/kubernetes   ClusterIP   10.96.0.1        <none>        443/TCP        18m
service/mysql        ClusterIP   10.104.153.230   <none>        3306/TCP       2m35s
service/wordpress    NodePort    10.110.116.187   <none>        80:32660/TCP   2m35s

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/mysql       1/1     1            1           2m35s
deployment.apps/wordpress   1/1     1            1           2m35s

NAME                                   DESIRED   CURRENT   READY   AGE
replicaset.apps/mysql-58ddcf7bf5       1         1         1       2m35s
replicaset.apps/wordpress-7f554bd4f5   1         1         1       2m35s

Accessing WordPress

# Open WordPress in your default browser
minikube service wordpress

This will open your browser to the WordPress setup page where you can complete the installation and start creating your blog content. The application’s data is stored in the MySQL database.

Basic Cluster Operations

Essential Management Commands

Cluster Control Commands

minikube stop      # Stop the cluster without deleting it
minikube start     # Start an existing cluster
minikube pause     # Pause Kubernetes without stopping the VM/container
minikube unpause   # Resume a paused Kubernetes cluster
minikube delete    # Delete the cluster and all related resources

Service Access Commands

Accessing the Dashboard

# Launch the Kubernetes dashboard in your browser
minikube dashboard

Output:

🔌  Enabling dashboard ...
▪ Using image docker.io/kubernetesui/dashboard:v2.7.0
▪ Using image docker.io/kubernetesui/metrics-scraper:v1.0.8
💡  Some dashboard features require the metrics-server addon. To enable all features please run:

    minikube addons enable metrics-server

🤔  Verifying dashboard health ...
🚀  Launching proxy ...
🤔  Verifying proxy health ...
🎉  Opening http://127.0.0.1:45951/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/ in your default browser...

Listing Services

# List all services in all namespaces with their URLs
minikube service list

Output:

|----------------------|---------------------------|--------------|---------------------------|
|      NAMESPACE       |           NAME            | TARGET PORT  |            URL            |
|----------------------|---------------------------|--------------|---------------------------|
| default              | kubernetes                | No node port |                           |
| default              | mysql                     | No node port |                           |
| default              | wordpress                 |           80 | http://192.168.49.2:32660 |
| kube-system          | kube-dns                  | No node port |                           |
| kubernetes-dashboard | dashboard-metrics-scraper | No node port |                           |
| kubernetes-dashboard | kubernetes-dashboard      | No node port |                           |
|----------------------|---------------------------|--------------|---------------------------|

Getting Service URL

# Get the URL for a specific service without opening browser
minikube service wordpress --url

Output:

http://192.168.49.2:32660

Resource Monitoring Commands

• Use minikube dashboard for GUI monitoring – provides a web-based UI to monitor and manage your cluster
• Check cluster health with kubectl get nodes – displays the status of all nodes in your cluster
• Monitor pods with kubectl get pods --all-namespaces – shows all pods across all namespaces

Advanced Features and Configuration

Add-ons Management

Listing Available Add-ons

# List all available add-ons and their current status
minikube addons list

Enabling Common Add-ons

# Enable the Ingress controller for external access to services
minikube addons enable ingress

# Enable metrics-server for resource usage monitoring
minikube addons enable metrics-server

# Enable the built-in container registry
minikube addons enable registry

Multi-cluster Management

Creating Multiple Profiles

# Create a separate cluster with profile name "cluster1"
minikube start -p cluster1

# Create another cluster with profile name "cluster2"
minikube start -p cluster2

Switching Between Profiles

# Switch to using a specific cluster profile
minikube profile cluster1

Troubleshooting and Maintenance

Common Issues and Solutions

Resource Problems

• Insufficient memory: Increase allocated memory with minikube start --memory=4096mb
• CPU constraints: Adjust CPU allocation with minikube start --cpus=4
• Disk space: Clean unused images and containers with docker system prune

Driver Issues

• Hypervisor conflicts: Ensure only one hypervisor is active at a time
• Driver compatibility: Verify OS compatibility with chosen driver

Network Connectivity

• DNS issues: Check network configuration with kubectl -n kube-system get pods -l k8s-app=kube-dns
• Service access: Verify port forwarding with minikube service list

Maintenance Best Practices

Regular Updates

# Check for minikube updates
minikube update-check
   
# Remove all clusters and cached images
minikube delete --all --purge

Resource Cleanup

# Delete the current cluster
minikube delete
   
# Clean up unused Docker resources to free disk space
docker system prune

Debugging Techniques

Log Analysis

# View Minikube's internal logs
minikube logs

# View logs for a specific pod
kubectl logs <pod-name>

Status Checking

# Check overall Minikube status
minikube status

# View recent cluster events for troubleshooting
kubectl get events

Best Practices and Tips

Resource Management

Optimal Allocation

• Start with minimum required resources
• Scale based on workload (e.g., minikube start --cpus=2 --memory=4096mb)
• Monitor resource usage regularly with kubectl top nodes and kubectl top pods

Monitoring and Scaling

• Use dashboard for resource visualization
• Implement resource limits in deployment manifests
• Regular performance checks with kubectl describe nodes

Security Considerations

Basic Security Measures

• Enable RBAC with minikube start --extra-config=apiserver.authorization-mode=RBAC
• Implement network policies to restrict pod communication
• Regular security updates with minikube update-check

Access Control

• Use namespaces for isolation: kubectl create namespace <name>
• Implement role-based access with kubectl create role and kubectl create rolebinding
• Secure API server access by avoiding --apiserver-ips flags in production

Performance Optimization

Resource Tuning

• Optimize CPU and memory allocation based on actual usage
• Use appropriate storage drivers for your workload
• Enable caching with --cache-images=true flag

Network Optimization

• Use appropriate CNI plugin for your needs
• Configure DNS properly with CoreDNS settings
• Optimize service discovery with appropriate label selectors

Conclusion

Minikube provides an excellent platform for local Kubernetes development and testing. By following this guide, you can set up and manage a local Kubernetes cluster effectively. The included deployment examples demonstrate how to get started with running real applications in your cluster, and the hot-reload development workflow allows for rapid iteration during development. Continue your Kubernetes journey by:

• Exploring Kubernetes documentation
• Practicing with sample applications
• Joining the Kubernetes community

Glossary of Terms

• Cluster: A set of nodes running containerized applications
• Node: A worker machine in Kubernetes
• Pod: Smallest deployable unit in Kubernetes
• Service: An abstract way to expose applications
• Deployment: A way to manage application scaling and updates
• Namespace: Virtual cluster for resource isolation
• ConfigMap: API object for storing non-confidential data
• Secret: Object containing sensitive information
• Volume: Directory accessible to containers in a pod
• Ingress: API object managing external access to services