📖 Table of Contents

📋 Overview

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

🎯 What This Guide Covers

  • Docker Desktop installation and configuration
  • Kubernetes cluster setup using Minikube
  • kubectl command-line tool installation
  • Basic Kubernetes resource creation and management
  • Tips for utilizing in local development environment

🔧 Prerequisites

Before installing Kubernetes on macOS, please check the following:

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 with 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 Docker official website.

2-2. Install and Run

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

# Check Docker daemon status
docker info

# Test simple container execution
docker run hello-world

💡 Tip You can adjust memory and CPU allocation in Docker Desktop’s resource settings. If you plan to run a Kubernetes cluster, it’s recommended to allocate at least 4GB of memory.

Step 3: Install kubectl

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

brew install kubectl

3-2. Direct Download Installation

If not using Homebrew, you can install with the following 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"

# Grant execution permission
chmod +x ./kubectl

# Add to PATH (when using 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.

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

# Grant execution permission
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-selected)
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

⚠️ Note The first run may take time as Minikube downloads necessary images. Depending on network conditions, it may take 5-10 minutes.

✅ Installation and Configuration 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 work.

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 detailed resource information
kubectl describe pod [pod-name]

# Check logs
kubectl logs [pod-name]

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

Debugging and Monitoring

# Run dashboard
minikube dashboard

# Enable metrics server
minikube addons enable metrics-server

# Enable load balancer addon
minikube addons enable ingress

🔧 Troubleshooting

Here are common problems and solutions that occur during installation and execution.

Problem: Docker Desktop won’t start

Solutions:

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

Problem: Timeout occurs when starting Minikube

Solutions:

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

3. kubectl Connection Issues

Problem: 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 to write YAML manifest files
  • Master kubectl commands

Practice Projects

  • Deploy simple web applications
  • Connect database and application
  • Utilize ConfigMap and Secret
  • Use PersistentVolume for data storage

Advanced Topics

  • Package management using Helm
  • Load balancing using Ingress
  • Monitoring and logging setup
  • Build CI/CD pipelines

📝 Conclusion

We’ve provided a step-by-step guide to installing and configuring Kubernetes locally on macOS. Through this environment, you can learn and practice various Kubernetes features.

In future posts, we’ll cover various Kubernetes use cases related to data engineering using this local environment. We’ll particularly look at how to build data pipelines, streaming processing, and monitoring systems in Kubernetes environments.