현대 웹 서비스는 빠른 개발과 유연한 배포를 동시에 요구받고 있다. FastAPI는 이 요구에 완벽히 부합하는 Python 기반 비동기 웹 프레임워크이며, Kubernetes는 이러한 서비스를 유연하게 운영할 수 있는 컨테이너 오케스트레이션 플랫폼이다. 이 글에서는 로컬 개발 환경에서 FastAPI를 Docker로 컨테이너화한 후, Ubuntu 24.04 기반 서버에서 k3s를 활용해 쿠버네티스 환경에 배포하는 전체 과정을 다룬다. 이는 소규모 프로젝트나 개인 서버에서도 엔터프라이즈 수준의 인프라 구성 경험을 가능하게 해주는 접근이다.
1. FastAPI: 현대적인 웹 프레임워크의 선택
FastAPI는 ASGI(Asynchronous Server Gateway Interface)를 기반으로 하여 고성능 비동기 처리를 지원하며, 자동 문서화(Swagger/OpenAPI), 타입 기반 검증, 높은 실행 속도로 주목받고 있다. 특히 RESTful API 개발에 있어서는 Python 진영에서 거의 독보적인 위치를 차지하고 있다. 프로젝트 구조가 명확하고, Uvicorn 같은 서버와 결합할 경우 최소 리소스로도 충분한 성능을 낼 수 있다는 점은 클라우드 네이티브 아키텍처에 적합한 요소다.
2. 컨테이너화: FastAPI를 Docker로 감싸다
FastAPI는 Uvicorn과 함께 실행되는 간단한 Python 애플리케이션 형태로 작성된다. 이를 컨테이너로 만들기 위해서는 Dockerfile만 잘 구성하면 된다. 기본적으로 Python 3.11-slim 베이스 이미지를 사용해 경량화된 이미지를 만들고, 필요한 패키지를 requirements.txt로 관리한다.
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY ./app ./app
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
이렇게 구성된 Docker 이미지는 로컬 환경에서 docker build로 생성하고, 필요 시 Docker Hub 등 외부 레지스트리에 푸시할 수 있다. 하지만 자체 서버 기반 운영을 고려한다면, 로컬에서 직접 Kubernetes 노드에 이미지를 등록하는 방식도 가능하다.
3. 로컬 서버 기반 Kubernetes: k3s의 선택
전통적인 Kubernetes 설치는 복잡한 설정과 높은 리소스를 요구하지만, Rancher Labs의 k3s는 경량화된 Kubernetes 배포판으로 이러한 문제를 해결한다. 단일 바이너리로 동작하며, 설치도 매우 간단하다.
curl -sfL https://get.k3s.io | sh -
설치 후 kubectl 명령어로 클러스터 상태를 바로 확인할 수 있다. 이 방식은 단일 노드 환경에서도 무중단 운영과 서비스 복원력 확보를 가능하게 하며, 다중 노드 확장도 지원한다.
4. 이미지 배포 전략: 로컬에서 containerd로 직접 import
k3s는 Docker 대신 containerd를 기본 컨테이너 런타임으로 사용한다. 따라서 Docker에서 빌드한 이미지를 직접 사용할 수는 없고, containerd에 import 해주는 과정이 필요하다. 이때 docker save와 ctr images import를 이용한다.
docker save fastapi-app > fastapi-app.tar
sudo k3s ctr images import fastapi-app.tar
이 과정을 통해 외부 레지스트리 없이도 로컬 환경만으로 완전한 컨테이너 기반 서비스를 구축할 수 있다.
5. FastAPI 서비스의 쿠버네티스 리소스 구성
이미지 배포 후에는 Deployment와 Service 리소스를 정의해 애플리케이션을 클러스터 내에 배치한다. Deployment는 애플리케이션의 실행 전략과 파드를 정의하고, Service는 외부 접근을 위한 포트를 설정한다.
# fastapi-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: fastapi
spec:
replicas: 1
selector:
matchLabels:
app: fastapi
template:
metadata:
labels:
app: fastapi
spec:
containers:
- name: fastapi
image: fastapi-app
ports:
- containerPort: 80
# fastapi-service.yaml
apiVersion: v1
kind: Service
metadata:
name: fastapi-service
spec:
selector:
app: fastapi
ports:
- protocol: TCP
port: 80
targetPort: 80
type: NodePort
Service의 type: NodePort 설정을 통해 외부에서 해당 파드에 접근할 수 있으며, 이는 작은 서버 환경에서 매우 유용하다. 배포는 간단한 kubectl apply -f 명령으로 완료된다.
6. 테스트와 운영: 최소한의 인프라로 실서비스 구현
쿠버네티스가 동작하는 서버의 IP와 할당된 NodePort를 이용하면 바로 FastAPI에 접근 가능하다. 이는 개발, 테스트, 운영을 하나의 환경에서 통합하는 로컬 DevOps 파이프라인으로 확장할 수 있다. 또한 Ingress Controller, cert-manager, Helm 등을 추가적으로 구성하면 도메인, HTTPS, 지속적 배포 전략까지 갖춘 완전한 운영 환경이 마련된다.
결론
FastAPI와 k3s를 결합한 쿠버네티스 환경은 단순한 웹 애플리케이션을 엔터프라이즈 수준의 인프라 위에서 구동할 수 있는 가능성을 보여준다. 이는 클라우드 리소스에 의존하지 않으면서도 탄력적이고 자동화된 운영을 가능하게 하는 접근이다. 서버 한 대로 시작하더라도, 이 구조는 추후 클러스터 확장과 마이크로서비스 분리에 자연스럽게 적응할 수 있다. 결국 중요한 건 복잡하지 않게 시작하되, 유연하고 표준화된 인프라를 바탕으로 성장 가능성을 확보하는 것이다.
답글 남기기