[MacOS][Python] 쿠버 환경에서 파이썬 어플리케이션 가동하기

ShinMinChul·2025년 4월 6일

How to eat Python deliciously

목록 보기

2/2

MacOS 환경에서 로컬 쿠버네티스(Minikube)를 구성하고, 파이썬 애플리케이션을 컨테이너로 만들어 실제로 Pod로 실행하기까지의 과정을 정리해보았습니다. Flask, FastAPI, 혹은 일반적인 Python 스크립트를 쿠버네티스에서 가동해야 할 때 참고할 수 있습니다.

1. Minikube 준비

1.1 Homebrew 설치 확인

터미널을 열고 Homebrew가 깔려 있는지 확인합니다.

brew --version

설치되어 있지 않다면 아래 명령어로 설치해 주세요.

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

1.2 Minikube 설치

Homebrew가 준비되었다면, 터미널에서 다음 명령어로 Minikube를 설치합니다.

brew install minikube

1.3 Minikube 클러스터 시작

Minikube를 시작합니다.

minikube start

원하는 드라이버(예: VirtualBox)가 있다면 --driver 옵션을 사용할 수 있습니다.

minikube start --driver=virtualbox

성공적으로 시작되었다면, 다음 명령어로 클러스터 정보와 노드를 확인해봅니다.

kubectl cluster-info
kubectl get nodes

현재 컨텍스트가 minikube인지도 확인해봅니다.

kubectl config current-context

결과가 minikube라면 준비가 완료된 것입니다.

2. Python 애플리케이션 도커라이징

2.1 프로젝트 구조 예시

flaskSample/
  ├── main.py
  ├── requirements.txt
  ├── Dockerfile
  └── entrypoint.sh (선택 사항)

main.py : Flask나 FastAPI 등 실행 스크립트.
requirements.txt : 필요한 Python 패키지 목록.
Dockerfile : 이미지를 빌드하기 위한 설정.
entrypoint.sh : 컨테이너 시작 시 실행될 명령어(필요에 따라 사용).

2.2 requirements.txt

Flask==2.2.2
requests==2.28.1
# 필요한 라이브러리 버전을 지정

(예시로 Flask와 requests만 기재)

2.3 Dockerfile 예시


# 예: Python 3.11 이미지를 베이스로 사용
FROM python:3.11

# 작업 디렉토리 생성
WORKDIR /app

# 의존성 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 애플리케이션 소스 복사
COPY . .

# 실행 스크립트(쉘 스크립트)에 실행권한 부여 (필요 시)
# RUN chmod +x entrypoint.sh

# 컨테이너 실행 시 entrypoint.sh 또는 main.py 실행
CMD ["python", "main.py"]

만약 Flask 애플리케이션이라면 main.py가 app.run(host="0.0.0.0", port=8080)로 설정되어 있어야 외부에서 접속할 수 있습니다.
FastAPI라면 uvicorn을 활용해 "uvicorn main:app --host 0.0.0.0 --port 8080" 을 CMD로 두는 방식도 가능합니다.

2.4 로컬에서 Docker 빌드하기

cd flaskSample
docker build -t my-python-app:latest .

빌드가 성공하면 docker images 명령어로 my-python-app 이미지를 확인합니다.

3. Minikube와 Docker 연동

로컬 Docker에서 빌드한 이미지를 Minikube 클러스터에서 사용하려면 다음 두 가지 방법이 있습니다.

3.1 Minikube Docker 환경에서 직접 빌드

Minikube 시작:

minikube start

현재 쉘 세션을 Minikube의 Docker 데몬과 연결:

eval $(minikube docker-env)

Docker 빌드(이제 Minikube 내부에서 빌드됨):

docker build -t my-python-app:latest .

이 상태에서 쿠버네티스가 my-python-app:latest를 바로 사용 가능.

3.2 로컬 빌드 후 Minikube로 로드

이미 로컬에서 빌드된 이미지를 Minikube로 로드할 수 있습니다.

minikube image load my-python-app:latest

그럼 Minikube 노드가 이 이미지를 인식하게 됩니다.

4. Kubernetes 배포(YAML) 작성

예시로 Deployment를 작성해 봅시다. 파일명 deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: python-flask-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: python-flask-pod
  template:
    metadata:
      labels:
        app: python-flask-pod
    spec:
      containers:
        - name: flask-container
          image: my-python-app:latest
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080

replicas: 3 → 파드를 3개 생성.
imagePullPolicy: IfNotPresent → 이미 로컬(노드)에 이미지가 있으면 pull 생략.

4.1 Deployment 적용

kubectl apply -f deployment.yaml

이후 상태를 확인합니다.

kubectl get deployments
kubectl get pods

파드가 Running 상태가 되어야 합니다.

5. 파드 접근하기

파드 내에서 127.0.0.1:8080으로 서버가 올라가 있어도, 이는 파드 내부 주소입니다. 외부(호스트)에서 접근하려면 포트 포워딩 혹은 Service 리소스가 필요합니다.

5.1 Port Forwarding

kubectl port-forward <pod-name> 8081:8080

이렇게 하면 로컬 포트 8081이 파드의 8080과 연결됩니다.
웹 브라우저에서 http://localhost:8081을 열면 파드의 Flask 서버에 접근 가능합니다.

5.2 Service 생성

NodePort나 LoadBalancer 타입으로 파드를 노출할 수 있습니다. 간단히 NodePort 예시:

apiVersion: v1
kind: Service
metadata:
  name: flask-service
spec:
  type: NodePort
  selector:
    app: python-flask-pod
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30080

배포 후 minikube ip 확인 → <minikube-ip>:30080으로 접속 가능.

6. 디버깅 팁

6.1 로그 확인

파드 로그:

kubectl logs <pod-name>

특정 컨테이너만 여러 개 있을 때:

kubectl logs <pod-name> -c <container-name>

6.2 파드 내부 들어가기

Shell이 있는 경우:

kubectl exec -it <pod-name> -- /bin/bash

또는

kubectl exec -it <pod-name> -- /bin/sh

6.3 CrashLoopBackOff 이슈

애플리케이션 실행 명령(main.py, uvicorn 등)이 즉시 종료되는 경우 → 컨테이너가 종료되어 재시작을 반복.
kubectl logs와 kubectl describe pod로 에러 확인 후, 앱이 계속 동작하도록 수정.

마무리

이렇게 MacOS 환경에서 Minikube를 통해 Python 애플리케이션을 쿠버네티스에 배포하는 과정을 살펴봤습니다.

Minikube로 로컬 쿠버 환경 구성
Dockerfile 작성해 파이썬 애플리케이션을 컨테이너화
Image를 Minikube가 인식하도록 (빌드 or 로드)
Deployment, Service 등 Kubernetes 리소스를 작성해 배포 및 노출
파드/로그/포트 포워딩 등을 통해 디버깅

실무에서는 각 환경(클라우드, 사설 클러스터 등)에 맞춰 레지스트리 설정, SSL, 모니터링, 로깅 등을 추가로 구성할 수 있습니다. 하지만 위 과정을 통해 간단한 로컬 테스트 및 애플리케이션 배포가 가능하므로, 쿠버네티스의 기본적인 워크플로우를 이해하는 데 도움이 되길 바랍니다.

Tip: 로컬 환경에서만 사용하지 않고, 실제 클라우드(Kubernetes in AWS, GCP, Azure 등)로 배포하려면, 이미지를 Docker Hub나 사설 레지스트리에 푸시하고, kubeconfig를 클라우드 클러스터에 연결하는 방식으로 확장할 수 있습니다.

ShinMinChul

개발은 예술이며, 나는 예술가다.

이전 포스트