Kubernetes Local Setup Guide for macOS - Using Docker Desktop and Minikube

📖 Table of Contents

• Overview
• Prerequisites
• Step-by-Step Installation Guide
• Installation and Setup Verification
• Useful Commands
• Troubleshooting
• Next Steps

📋 Overview

Kubernetes is an open-source platform for container orchestration, essential for modern cloud-native application development and operations. This post provides a step-by-step guide to install and configure Kubernetes locally on macOS.

🔧 Prerequisites

Before installing Kubernetes on macOS, please verify the following requirements:

System Requirements

• macOS Version: macOS 10.15 (Catalina) or higher
• Memory: Minimum 8GB RAM (16GB recommended)
• Storage: Minimum 20GB free space
• Processor: Intel or Apple Silicon (M1/M2)

Required Software

• Homebrew: Package manager (if not already installed)
• Terminal App: Default Terminal.app or iTerm2

🚀 Step-by-Step Installation Guide

Step 1: Install Homebrew (Optional)

If Homebrew is not installed, you can install it using the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, restart the terminal and verify the installation with:

brew --version

Step 2: Install Docker Desktop

Docker Desktop is the official application for running Docker on macOS.

2-1. Download Docker Desktop

Download Docker Desktop for macOS from the official Docker website.

2-2. Installation and Setup

1. Double-click the downloaded .dmg file to install
2. Drag Docker.app to Applications folder
3. Launch Docker Desktop and complete initial setup
4. Verify Docker is running properly

# Check Docker version
docker --version

# Check Docker daemon status
docker info

# Test with simple container
docker run hello-world

Step 3: Install kubectl

kubectl is the command-line tool for interacting with Kubernetes clusters.

3-1. Installation using Homebrew (Recommended)

brew install kubectl

3-2. Direct Download Installation

If not using Homebrew, you can install with these commands:

# Apple Silicon Mac
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

# Intel Mac
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

# Make executable
chmod +x ./kubectl

# Add to PATH (for zsh)
sudo mv ./kubectl /usr/local/bin/kubectl

3-3. Verify Installation

kubectl version --client

Step 4: Install Minikube

Minikube is a tool that allows you to run a single-node Kubernetes cluster locally.

4-1. Installation using Homebrew (Recommended)

brew install minikube

4-2. Direct Download Installation

# Apple Silicon Mac
curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-darwin-arm64

# Intel Mac
curl -LO https://github.com/kubernetes/minikube/releases/latest/download/minikube-darwin-amd64

# Make executable
chmod +x minikube-darwin-*

# Add to PATH
sudo mv minikube-darwin-* /usr/local/bin/minikube

4-3. Verify Installation

minikube version

Step 5: Start Minikube Cluster

Now you can start a local Kubernetes cluster using Minikube.

5-1. Start Basic Cluster

# Start cluster using Docker driver
minikube start --driver=docker

# Or use default driver (auto-selection)
minikube start

5-2. Check Cluster Status

# Check cluster status
minikube status

# Check node information
kubectl get nodes

# Check pods in all namespaces
kubectl get pods --all-namespaces

✅ Installation and Setup Verification

Let's verify that all installations are complete.

1. Check Docker Status

# Docker daemon status
docker info

# Check running containers
docker ps

2. Check Minikube Status

# Minikube status
minikube status

# Cluster information
minikube cluster-info

3. Verify kubectl Connection

# Check context
kubectl config current-context

# Cluster information
kubectl cluster-info

# Node list
kubectl get nodes

4. Test Simple Application Deployment

# Create nginx deployment
kubectl create deployment nginx --image=nginx

# Check deployment status
kubectl get deployments

# Check pod status
kubectl get pods

# Create service (port forwarding)
kubectl expose deployment nginx --port=80 --type=NodePort

# Check service information
kubectl get services

# Access via local port
minikube service nginx

🛠️ Useful Commands

Here are commonly used commands for daily development tasks.

Cluster Management

# Start cluster
minikube start

# Stop cluster
minikube stop

# Delete cluster
minikube delete

# Restart cluster
minikube restart

Resource Management

# Check all resources
kubectl get all

# Check resources in specific namespace
kubectl get all -n kube-system

# Check resource details
kubectl describe pod [pod-name]

# Check logs
kubectl logs [pod-name]

# Access pod
kubectl exec -it [pod-name] -- /bin/bash

Debugging and Monitoring

# Launch dashboard
minikube dashboard

# Enable metrics server
minikube addons enable metrics-server

# Enable load balancer addon
minikube addons enable ingress

🔧 Troubleshooting

Here are common issues and solutions during installation and execution.

1. Docker Desktop Issues

Issue: Docker Desktop won't start

Solutions:

• Completely close and restart Docker Desktop
• Restart system and launch Docker Desktop
• Check resource allocation in Docker Desktop settings

2. Minikube Issues

Issue: Minikube startup timeout

Solutions:

• Check network connection status
• Verify firewall settings
• If using VPN, disable VPN and retry
• Delete and recreate Minikube

3. kubectl Connection Issues

Issue: kubectl cannot connect to cluster

Solutions:

• Check Minikube status: minikube status
• Check context: kubectl config current-context
• Restart Minikube: minikube restart

🚀 Next Steps

Your local Kubernetes environment is ready! Now you can proceed with the following learning:

Basic Learning

• Understand Kubernetes basic concepts (Pod, Service, Deployment, etc.)
• Learn YAML manifest file writing
• Master kubectl commands

Hands-on Projects

• Deploy simple web applications
• Connect databases with applications
• Utilize ConfigMap and Secret
• Data storage using PersistentVolume

Advanced Topics

• Package management using Helm
• Load balancing using Ingress
• Monitoring and logging setup
• CI/CD pipeline construction

📝 Conclusion

I've provided a step-by-step guide to install and configure Kubernetes locally on macOS. With this environment, you can learn and practice various Kubernetes features.

In future posts, I'll cover various Kubernetes use cases related to data engineering using this local environment. I'll particularly focus on building data pipelines, streaming processing, monitoring systems, and more in Kubernetes environments.