📖 목차

📋 개요

쿠버네티스(Kubernetes)는 컨테이너 오케스트레이션을 위한 오픈소스 플랫폼으로, 현대적인 클라우드 네이티브 애플리케이션 개발과 운영에 필수적인 기술입니다. 이 포스트에서는 macOS 환경에서 쿠버네티스를 로컬에 설치하고 설정하는 방법을 단계별로 안내합니다.

🎯 이 가이드에서 다룰 내용

  • Docker Desktop 설치 및 설정
  • Minikube를 사용한 쿠버네티스 클러스터 구축
  • kubectl 명령어 도구 설치
  • 기본적인 쿠버네티스 리소스 생성 및 관리
  • 로컬 개발 환경에서의 활용 팁

🔧 사전 요구사항

macOS에서 쿠버네티스를 설치하기 전에 다음 사항들을 확인해주세요:

시스템 요구사항

  • macOS 버전: macOS 10.15 (Catalina) 이상
  • 메모리: 최소 8GB RAM (16GB 권장)
  • 저장공간: 최소 20GB 여유 공간
  • 프로세서: Intel 또는 Apple Silicon (M1/M2)

필요한 소프트웨어

  • Homebrew: 패키지 관리자 (설치되어 있지 않은 경우)
  • 터미널 앱: 기본 Terminal.app 또는 iTerm2

🚀 단계별 설치 가이드

1단계: Homebrew 설치 (선택사항)

Homebrew가 설치되어 있지 않다면 다음 명령어로 설치할 수 있습니다:

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

설치 후 터미널을 재시작하고 다음 명령어로 설치를 확인합니다:

brew --version

2단계: Docker Desktop 설치

Docker Desktop은 macOS에서 Docker를 실행하기 위한 공식 애플리케이션입니다.

2-1. Docker Desktop 다운로드

Docker 공식 웹사이트에서 macOS용 Docker Desktop을 다운로드합니다.

2-2. 설치 및 실행

  1. 다운로드한 .dmg 파일을 더블클릭하여 설치
  2. Applications 폴더로 Docker.app을 드래그하여 설치
  3. Docker Desktop을 실행하고 초기 설정 완료
  4. Docker가 정상적으로 실행되고 있는지 확인
# Docker 버전 확인
docker --version

# Docker 데몬 상태 확인
docker info

# 간단한 컨테이너 실행 테스트
docker run hello-world

💡 팁 Docker Desktop의 리소스 설정에서 메모리와 CPU 할당량을 조정할 수 있습니다. 쿠버네티스 클러스터를 실행할 예정이라면 메모리를 최소 4GB 이상 할당하는 것을 권장합니다.

3단계: kubectl 설치

kubectl은 쿠버네티스 클러스터와 상호작용하는 명령줄 도구입니다.

3-1. Homebrew를 사용한 설치 (권장)

brew install kubectl

3-2. 직접 다운로드 설치

Homebrew를 사용하지 않는 경우 다음 명령어로 설치할 수 있습니다:

# 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"

# 실행 권한 부여
chmod +x ./kubectl

# PATH에 추가 (zsh 사용 시)
sudo mv ./kubectl /usr/local/bin/kubectl

3-3. 설치 확인

kubectl version --client

4단계: Minikube 설치

Minikube는 로컬에서 단일 노드 쿠버네티스 클러스터를 실행할 수 있게 해주는 도구입니다.

4-1. Homebrew를 사용한 설치 (권장)

brew install minikube

4-2. 직접 다운로드 설치

# 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

# 실행 권한 부여
chmod +x minikube-darwin-*

# PATH에 추가
sudo mv minikube-darwin-* /usr/local/bin/minikube

4-3. 설치 확인

minikube version

5단계: Minikube 클러스터 시작

이제 Minikube를 사용하여 로컬 쿠버네티스 클러스터를 시작할 수 있습니다.

5-1. 기본 클러스터 시작

# Docker 드라이버를 사용하여 클러스터 시작
minikube start --driver=docker

# 또는 기본 드라이버 사용 (자동 선택)
minikube start

5-2. 클러스터 상태 확인

# 클러스터 상태 확인
minikube status

# 노드 정보 확인
kubectl get nodes

# 모든 네임스페이스의 파드 확인
kubectl get pods --all-namespaces

⚠️ 주의사항 첫 번째 실행 시 Minikube가 필요한 이미지들을 다운로드하므로 시간이 걸릴 수 있습니다. 네트워크 상태에 따라 5-10분 정도 소요될 수 있습니다.

✅ 설치 및 설정 확인

모든 설치가 완료되었는지 확인해보겠습니다.

1. Docker 상태 확인

# Docker 데몬 상태
docker info

# 실행 중인 컨테이너 확인
docker ps

2. Minikube 상태 확인

# Minikube 상태
minikube status

# 클러스터 정보
minikube cluster-info

3. kubectl 연결 확인

# 컨텍스트 확인
kubectl config current-context

# 클러스터 정보
kubectl cluster-info

# 노드 목록
kubectl get nodes

4. 간단한 애플리케이션 배포 테스트

# nginx 디플로이먼트 생성
kubectl create deployment nginx --image=nginx

# 디플로이먼트 상태 확인
kubectl get deployments

# 파드 상태 확인
kubectl get pods

# 서비스 생성 (포트 포워딩)
kubectl expose deployment nginx --port=80 --type=NodePort

# 서비스 정보 확인
kubectl get services

# 로컬 포트로 접근
minikube service nginx

🛠️ 유용한 명령어들

일상적인 개발 작업에서 자주 사용하는 명령어들을 정리했습니다.

클러스터 관리

# 클러스터 시작
minikube start

# 클러스터 중지
minikube stop

# 클러스터 삭제
minikube delete

# 클러스터 재시작
minikube restart

리소스 관리

# 모든 리소스 확인
kubectl get all

# 특정 네임스페이스의 리소스 확인
kubectl get all -n kube-system

# 리소스 상세 정보 확인
kubectl describe pod [pod-name]

# 로그 확인
kubectl logs [pod-name]

# 파드에 접속
kubectl exec -it [pod-name] -- /bin/bash

디버깅 및 모니터링

# 대시보드 실행
minikube dashboard

# 메트릭 서버 활성화
minikube addons enable metrics-server

# 로드밸런서 애드온 활성화
minikube addons enable ingress

🔧 문제 해결

설치 및 실행 과정에서 자주 발생하는 문제들과 해결 방법을 정리했습니다.

1. Docker Desktop 관련 문제

문제: Docker Desktop이 시작되지 않음

해결 방법:

  • Docker Desktop을 완전히 종료하고 재시작
  • 시스템 재부팅 후 Docker Desktop 실행
  • Docker Desktop 설정에서 리소스 할당량 확인

2. Minikube 관련 문제

문제: Minikube 시작 시 타임아웃 발생

해결 방법:

  • 네트워크 연결 상태 확인
  • 방화벽 설정 확인
  • VPN 사용 중인 경우 VPN 해제 후 재시도
  • Minikube 삭제 후 재생성

3. kubectl 연결 문제

문제: kubectl이 클러스터에 연결되지 않음

해결 방법:

  • Minikube 상태 확인: minikube status
  • 컨텍스트 확인: kubectl config current-context
  • Minikube 재시작: minikube restart

🚀 다음 단계

로컬 쿠버네티스 환경이 준비되었습니다! 이제 다음과 같은 학습을 진행할 수 있습니다:

기초 학습

  • 쿠버네티스 기본 개념 이해 (Pod, Service, Deployment 등)
  • YAML 매니페스트 파일 작성법
  • kubectl 명령어 마스터하기

실습 프로젝트

  • 간단한 웹 애플리케이션 배포
  • 데이터베이스와 애플리케이션 연동
  • ConfigMap과 Secret 활용
  • PersistentVolume을 사용한 데이터 저장

고급 주제

  • Helm을 사용한 패키지 관리
  • Ingress를 사용한 로드밸런싱
  • 모니터링 및 로깅 설정
  • CI/CD 파이프라인 구축

📝 마무리

macOS 환경에서 쿠버네티스를 로컬에 설치하고 설정하는 방법을 단계별로 안내했습니다. 이 환경을 통해 쿠버네티스의 다양한 기능을 학습하고 실습할 수 있습니다.

앞으로의 포스트에서는 이 로컬 환경을 활용하여 데이터 엔지니어링과 관련된 다양한 쿠버네티스 활용 사례들을 다룰 예정입니다. 특히 데이터 파이프라인, 스트리밍 처리, 모니터링 시스템 등을 쿠버네티스 환경에서 구축하는 방법을 살펴보겠습니다.