Minikube로 로컬 Kubernetes(K8s) 환경 실습하기 — Pod 생성부터 배포까지

Minikube로 로컬 Kubernetes 클러스터를 만들고 Pod, Deployment, Service 흐름을 실습한다.

쿠버네티스를 배운다는 말은 결국 API 서버에 리소스를 만들고, 상태를 확인하고, 문제가 생겼을 때 원인을 추적하는 흐름을 몸에 익힌다는 뜻입니다. 이때 가장 빠르게 실습 환경을 만들 수 있는 도구가 Minikube입니다.

AWS EKS나 GKE 같은 관리형 Kubernetes는 실무 환경에 가깝지만 비용과 설정 부담이 있습니다. 반대로 Minikube는 노트북 한 대에서 단일 노드 클러스터를 띄우기 때문에, Pod 생성 → Deployment 생성 → Service 노출 → 로그 확인 → 정리까지 부담 없이 반복 실습할 수 있습니다.

목차

• 1. Minikube를 쓰는 이유
• 2. 실습 전 준비 사항
• 3. Minikube 클러스터 시작
• 4. Deployment로 첫 애플리케이션 배포
• 5. Service로 외부 노출
• 6. Pod 직접 다뤄보기
• 7. 로그와 이벤트로 상태 확인
• 8. 자원 정리
• 9. 자주 만나는 오류
• 10. 한 장 요약

1. Minikube를 쓰는 이유

Minikube는 로컬 환경에 단일 노드 Kubernetes 클러스터를 만드는 도구입니다. 학습용이라고 해서 가짜 Kubernetes가 아니라, 실제 Kubernetes API 서버와 kubelet, 컨트롤러 컴포넌트를 사용합니다.

• 빠른 시작: Docker Desktop만 있어도 몇 분 안에 클러스터를 만들 수 있습니다.
• 비용 없음: 클라우드 리소스를 만들지 않으므로 학습 비용 부담이 작습니다.
• 실제 명령어 사용: kubectl, YAML, Deployment, Service 등 핵심 흐름은 실무 Kubernetes와 동일합니다.
• 반복 실습에 적합: 클러스터를 지웠다가 다시 만드는 과정이 간단합니다.

2. 실습 전 준비 사항

이 글에서는 Docker 드라이버 기준으로 설명합니다. macOS 기준으로는 Docker Desktop과 Homebrew가 준비되어 있으면 가장 편합니다.

# macOS 예시
brew install minikube kubectl

# 설치 확인
minikube version
kubectl version --client

Windows나 Linux에서도 흐름은 같습니다. 차이가 나는 부분은 설치 방식과 드라이버뿐입니다. Docker 대신 VirtualBox, HyperKit, KVM2 같은 드라이버를 사용할 수도 있습니다.

3. Minikube 클러스터 시작

먼저 로컬 Kubernetes 클러스터를 시작합니다.

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

정상적으로 시작되면 kubectl이 자동으로 Minikube 클러스터를 바라보도록 context가 설정됩니다. 아래 명령으로 현재 context와 노드 상태를 확인합니다.

# 현재 kubectl context 확인
kubectl config current-context

# 노드 상태 확인
kubectl get nodes

출력에서 minikube 노드가 Ready 상태라면 실습 준비가 끝난 것입니다.

4. Deployment로 첫 애플리케이션 배포

이제 테스트 애플리케이션을 Deployment 형태로 배포합니다. Deployment는 Pod를 직접 하나 띄우는 것보다 실무에 가까운 방식입니다. ReplicaSet을 통해 Pod 개수를 유지하고, 장애가 나면 다시 생성해줍니다.

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

생성 후에는 Deployment와 Pod 상태를 확인합니다.

# Deployment 목록
kubectl get deployments

# Pod 목록
kubectl get pods

# 더 자세한 Pod 정보
kubectl get pods -o wide

READY가 1/1이고 STATUS가 Running이면 정상입니다.

5. Service로 외부 노출

Pod는 기본적으로 클러스터 내부 네트워크에서만 접근할 수 있습니다. 로컬 브라우저에서 접속하려면 Service를 만들어 외부로 노출해야 합니다.

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

Service가 생성되었는지 확인합니다.

kubectl get services

클라우드 환경의 LoadBalancer는 외부 IP를 할당받지만, Minikube는 로컬 환경이므로 아래 명령으로 터널링된 접속 URL을 열 수 있습니다.

minikube service hello-node

브라우저가 열리고 테스트 애플리케이션 응답이 보이면 Deployment와 Service 흐름을 성공적으로 연결한 것입니다.

6. Pod 직접 다뤄보기

Deployment가 실무 권장 방식이라면, kubectl run은 Pod 단위 동작을 빠르게 확인할 때 유용합니다.

6-1. nginx Pod 생성

kubectl run nginx --image=nginx

6-2. Pod 상세 정보 확인

kubectl describe pod nginx

describe 출력에서는 Pod가 어떤 노드에 배치되었는지, 어떤 이미지를 사용했는지, 이벤트 단계에서 어떤 일이 있었는지 확인할 수 있습니다. 특히 Events 영역은 이미지 풀 실패, 스케줄링 실패, 재시작 원인을 볼 때 가장 먼저 확인하는 곳입니다.

6-3. create deployment와 run의 차이

# 실무에 가까운 방식: Deployment + ReplicaSet + Pod 생성
kubectl create deployment nginx --image=nginx

# 학습/테스트용: Pod 하나만 생성
kubectl run nginx --image=nginx

명령어	생성 리소스	용도
kubectl create deployment	Deployment, ReplicaSet, Pod	배포, 스케일링, 자가 치유
kubectl run	Pod	간단한 테스트, 일회성 실습

7. 로그와 이벤트로 상태 확인

Kubernetes 실습에서 중요한 습관은 리소스를 만든 뒤 바로 상태를 확인하는 것입니다.

# 클러스터 이벤트 확인
kubectl get events --sort-by=.metadata.creationTimestamp

# 특정 Pod 로그 확인
kubectl logs <pod-name>

# 특정 Pod 상세 정보 확인
kubectl describe pod <pod-name>

Pod가 Pending, ImagePullBackOff, CrashLoopBackOff 상태라면 get events와 describe를 먼저 보는 것이 좋습니다.

8. 자원 정리

실습이 끝났다면 리소스를 정리합니다. 로컬 환경이라도 불필요한 Pod와 Service가 계속 남아 있으면 다음 실습에서 헷갈릴 수 있습니다.

# 애플리케이션 리소스 삭제
kubectl delete service hello-node
kubectl delete deployment hello-node
kubectl delete pod nginx

# 클러스터 중지
minikube stop

# 클러스터 완전 삭제
minikube delete

minikube stop은 클러스터를 멈추는 것이고, minikube delete는 클러스터 자체를 제거하는 명령입니다. 다시 처음부터 실습하고 싶다면 delete까지 수행하면 됩니다.

9. 자주 만나는 오류

9-1. Docker가 켜져 있지 않음

Exiting due to DRV_NOT_RUNNING

Docker 드라이버를 사용할 때 Docker Desktop이 꺼져 있으면 Minikube가 시작되지 않습니다. Docker를 먼저 실행한 뒤 다시 minikube start --driver=docker를 실행합니다.

9-2. Pod가 ImagePullBackOff 상태

이미지 이름이 틀렸거나 레지스트리 접근에 실패한 경우입니다. kubectl describe pod <pod-name>에서 Events 영역을 확인합니다.

9-3. Service 접속이 안 됨

Minikube에서는 단순히 kubectl get services에 보이는 포트만으로 접근이 안 될 수 있습니다. minikube service <service-name>를 사용하면 로컬 접속 URL을 자동으로 열어줍니다.

10. 한 장 요약

# 1. 클러스터 시작
minikube start --driver=docker

# 2. 앱 배포
kubectl create deployment hello-node \
  --image=registry.k8s.io/e2e-test-images/agnhost:2.39 \
  -- /agnhost netexec --http-port=8080

# 3. 상태 확인
kubectl get deployments
kubectl get pods -o wide

# 4. 외부 노출
kubectl expose deployment hello-node --type=LoadBalancer --port=8080
minikube service hello-node

# 5. 로그/이벤트 확인
kubectl logs <pod-name>
kubectl get events

# 6. 정리
kubectl delete service hello-node
kubectl delete deployment hello-node
minikube stop

마무리

Minikube의 가장 큰 장점은 작은 로컬 환경에서도 Kubernetes의 핵심 흐름을 그대로 연습할 수 있다는 점입니다. 여기서 익힌 kubectl, Deployment, Service, 로그 확인 방식은 EKS, GKE, AKS 같은 관리형 Kubernetes에서도 거의 그대로 이어집니다.

처음에는 명령어를 외우려고 하기보다 리소스를 만든다 → 상태를 본다 → 외부로 노출한다 → 문제가 생기면 이벤트와 로그를 본다 → 정리한다는 운영 흐름을 익히는 것이 중요합니다.

---

다음 글

다음 글에서는 Kubernetes 네트워킹의 핵심인 Pod 네트워크, Service, ClusterIP, NodePort, LoadBalancer 구조를 정리합니다.