[Kubernetes] 로컬에서 쿠버네티스 실습하기 - Minikube 활용

💡 실습 개요

이 글에서는 Mac에서 쿠버네티스(Minikube)를 활용하여 FastAPI 애플리케이션을 배포하는 가장 간단한 방법을 다뤄보려 해요. 쿠버네티스는 애플리케이션을 컨테이너화하고 관리하는 강력한 도구예요. 하지만 처음 사용하기에는  복잡할 수 있죠. 이번 실습에서는 로컬 환경에서 Minikube를 사용하여 쿠버네티스를 경험하고, FastAPI 애플리케이션을 배포하는 기본적인 방법을 학습합니다.

 

✅ 실습 순서

1. 환경 설정
   • Kubernetes(Minikube, kubectl) 설치
   • Minikube 실행 및 클러스터 확인
2. FastAPI 애플리케이션 작성
3. Docker로 컨테이너 빌드 및 실행 테스트
4. Kubernetes에 배포 (deployment.yaml, service.yaml 작성 및 적용)
5. 로컬에서 API 호출 테스트
6. Kubernetes 상태 GUI로 확인하고 분석하기

 

✅  프로젝트 구조

~/k8s-fastapi/
├── main.py          # FastAPI 애플리케이션 코드
├── requirements.txt # 필요한 Python 패키지 목록
├── Dockerfile       # Docker 빌드 설정
└── k8s/             # Kubernetes 관련 설정 파일 디렉터리
    ├── deployment.yaml
    └── service.yaml

---

1. MacBook에 Kubernetes(K8s) 설치

로컬 MacBook에서 Kubernetes를 실행하려면 Minikube를 사용하는 것이 가장 간단합니다.

✅ Homebrew로 Minikube 및 kubectl 설치

brew install minikube kubectl

✅ Minikube 클러스터 실행

minikube start --driver=docker

✅ Minikube 정상 실행 확인

kubectl get nodes

NAME       STATUS   ROLES                  AGE   VERSION
minikube   Ready    control-plane,master   10s   v1.28.0

 

Kubernetes 클러스터가 정상적으로 실행되었습니다!

 

2. FastAPI 애플리케이션 작성

📌 main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello from Kubernetes on MacBook!"}

• 쿠버네티스 실습을 위한 아주 간단한 Restful API를 생성

 

 

📌 requirements.txt

fastapi
uvicorn

 

 

 

3. Docker로 FastAPI 컨테이너 빌드

📌 Dockerfile

FROM python:3.9

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

 

✅ Docker 이미지 빌드

docker build -t fastapi-app .

 

✅ Docker 실행 테스트

docker run -p 8000:8000 fastapi-app

 

 브라우저에서 http://localhost:8000/ 접속하여 응답을 확인하세요.

 

4. Kubernetes 배포 (deployment.yaml, service.yaml)

📌 k8s/deployment.yaml

apiVersion: apps/v1  # API 버전 (Deployment를 정의할 때 사용하는 Kubernetes API 그룹)
kind: Deployment  # 리소스 종류 (Deployment 객체 생성)
metadata:
  name: fastapi-app  # Deployment의 이름 (fastapi-app이라는 이름으로 정의됨)
spec:
  replicas: 2  # Pod을 2개 실행 (수평 확장을 위한 설정)
  selector:
    matchLabels:
      app: fastapi-app  # 이 레이블이 있는 Pod을 관리
  template:
    metadata:
      labels:
        app: fastapi-app  # Pod에 붙일 레이블 (Service에서 Pod을 찾을 때 사용)
    spec:
      containers:
      - name: fastapi-app  # 컨테이너 이름
        image: fastapi-app:latest  # 사용할 Docker 이미지 (로컬에서 빌드한 fastapi-app:latest 사용)
        ports:
        - containerPort: 8000  # 컨테이너 내부에서 노출할 포트 (FastAPI 기본 포트)

 

✅ Deployment 역할

• 컨테이너화된 애플리케이션을 쿠버네티스 클러스터에 배포하는 역할 
• 원하는 개수(replicas)만큼 Pod을 실행하고, 자동으로 관리 및 복구
• 새로운 버전이 배포되면 기존 Pod을 순차적으로 교체하는 롤링 업데이트 기능 제공

✅ Deployment 주요 동작 방식

 

1. Pod 자동 생성 

• replicas: 2 → 동일한 Pod을 2개 실행하여 부하 분산 가능
• Kubernetes가 관리하는 Pod이므로 어떤 Pod이 죽더라도 자동으로 새로운 Pod이 생성됨

2. Label 기반 Pod 관리

• selector.matchLabels.app: fastapi-app
• template.metadata.labels.app: fastapi-app
• 이 레이블이 같은 Pod만 관리함. (Service에서도 동일한 방식으로 연결)

3. 컨테이너 설정

• image: fastapi-app:latest → FastAPI 컨테이너 실행
• containerPort: 8000 → 컨테이너 내부에서 사용하는 포트 (서비스 연결 시 필요)

 

📌 k8s/service.yaml

apiVersion: v1  # API 버전 (Service를 정의할 때 사용하는 Kubernetes API 그룹)
kind: Service  # 리소스 종류 (Service 객체 생성)
metadata:
  name: fastapi-service  # Service의 이름
spec:
  type: LoadBalancer  # 외부에서도 접근할 수 있도록 Load Balancer 생성
  selector:
    app: fastapi-app  # 레이블이 fastapi-app인 Pod과 연결
  ports:
  - protocol: TCP  # 네트워크 프로토콜 (TCP 사용)
    port: 80  # 외부에서 접근할 수 있는 포트 (클라이언트가 API를 호출할 때 사용)
    targetPort: 8000  # 내부 컨테이너에서 사용하는 포트 (FastAPI가 실행 중인 포트)

 

✅ Service 역할

• 쿠버네티스의 Pod들은 동적으로 생성/삭제되기 때문에, 직접 접근할 수 있는 고정된 IP가 없음.
• Service는 이러한 Pod들을 Label 기반으로 묶고, 네트워크를 통해 접근할 수 있도록 해주는 역할을 수행
• type: LoadBalancer를 사용하면 외부에서도 API를 호출할 수 있도록 Load Balancer를 자동 생성.

✅ Service 주요 동작 방식

1. Pod과의 연결

• selector.app: fastapi-app → fastapi-app 레이블이 붙은 모든 Pod을 묶어서 서비스로 제공.
• Deployment에서 생성한 Pod과 자동으로 연결됨.

2. 외부 접근을 위한 LoadBalancer 사용

• type: LoadBalancer → 클라우드 환경에서 외부에서 접근 가능한 IP를 자동 할당
• Minikube에서는 LoadBalancer 대신 NodePort 방식으로 서비스에 접근 가능 (minikube service fastapi-service 실행 시 URL 제공).

3. 포트 설정

• port: 80 → 클라이언트가 요청을 보내는 포트 (예: http://EXTERNAL-IP:80/)
• targetPort: 8000 → 실제 FastAPI 애플리케이션이 실행되는 컨테이너 내부 포트
• 즉, 외부에서 80번 포트로 요청을 보내면, 내부적으로 8000번 포트로 전달됨.

 

Deployment + Service 동작 방식 요약

1️⃣ Deployment

• replicas: 2 → Pod을 2개 실행하여 부하 분산.
• image: fastapi-app:latest → FastAPI 컨테이너 실행.
• containerPort: 8000 → 컨테이너 내부에서 실행되는 포트.
• Pod이 죽으면 자동 복구됨.

2️⃣ Service

• type: LoadBalancer → 외부에서도 API를 호출할 수 있도록 설정.
• selector.app: fastapi-app → Deployment에서 실행된 Pod들과 자동 연결.
• port: 80 → targetPort: 8000 → 외부 요청(80번 포트)을 FastAPI 컨테이너 내부(8000번 포트)로 전달.

 

5. Kubernetes 배포 실행

✅ 배포 실행

kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

 

✅ 배포된 리소스 확인

kubectl get pods
kubectl get deployments
kubectl get services

 

 

 

✅ API 호출 테스트

minikube service fastapi-service

| NAMESPACE |      NAME       | TARGET PORT |            URL            |
|-----------|-----------------|-------------|---------------------------|
| default   | fastapi-service |          80 | http://192.168.49.2:32567 |

 

출력된 URL을 사용하여 API를 호출할 수 있어요.

curl http://192.168.49.2:32567/

 

{"message": "Hello from Kubernetes on MacBook!"}

 

 

6. Kubernetes 상태 GUI로 확인하고 분석하기

쿠버네티스 클러스터는 GUI로 여러가지 정보를 확인할 수 있답니다.

minikube dashboard

 

 

이후 브라우저에서 위와 같이 Kubernetes 클러스터의 상태를 시각적으로 확인할 수 있습니다.

✅ Minikube Dashboard에서 확인할 수 있는 정보

1. Pod 상태: FastAPI 컨테이너가 정상적으로 실행 중인지 확인 가능
2. Replica 개수: 원하는 개수만큼 배포되었는지 확인
3. 서비스 노출 상태: LoadBalancer를 통해 API가 외부에 잘 노출되었는지 체크
4. 리소스 사용량: CPU 및 메모리 사용량 분석 가능