React, FastAPI 환경의 K8s 배포 구조

React, FastAPI 환경의 K8s 배포 구조

1. 개요

이 문서는 new-x-rag-frontend 프로젝트의 Kubernetes 배포 구조(k8s 폴더 내부)와 핵심 동작을 정리한 문서입니다.

2. k8s 폴더 구조

k8s/
├─ deploy-frontend.sh
├─ app/
│  ├─ configmap.yaml
│  ├─ deployment.yaml
│  └─ service.yaml
├─ ingress/
│  └─ ingress.yaml
└─ namespace/
   └─ namespace.yaml

3. 파일별 역할

namespace.yaml

• 네임스페이스(namespace): 클러스터 내부 리소스를 논리적으로 나누는 단위
• 리소스를 논리적으로 분리해 관리 범위를 명확히 함

configmap.yaml

• Nginx 설정(default.conf)을 ConfigMap으로 관리(Nginx 설정 파일을 컨테이너에 주입하는 용도로 사용)
• 비밀정보가 아닌 설정 데이터 저장 객체
• 정적 파일 서빙, SPA fallback, API 리버스 프록시, SSE/스트리밍 대응, 캐시/보안 헤더 정책 포함
  • SPA: Single Page Application
  • SPA fallback: 서버에 실제 파일이 없는 경로 요청 시 index.html을 반환하고, 이후 라우팅은 브라우저 JS(React Router 등)가 처리
  • 리버스 프록시: 클라이언트 요청을 앞단에서 받아 내부 백엔드로 전달, 경로 분기, 보안/로깅/제어 정책을 한 지점에서 통합 관리

deployment.yaml

• 프론트엔드 컨테이너(Pod) 실행
• 이미지, 리소스 요청/제한, 프로브(liveness/readiness), ConfigMap 마운트 정의
  • livenessProbe: 컨테이너 생존 여부 확인, 실패 누적 시 재시작
  • readinessProbe: 트래픽 수신 준비 상태 확인, 실패 시 라우팅 대상에서 제외

service.yaml

• Pod를 ClusterIP 서비스로 내부 노출
• 고정된 서비스 이름으로 Pod 집합에 접근 가능하게 함

ingress.yaml

• 외부 HTTP 요청을 Service로 전달하는 Ingress 규칙 정의
• ingress.class(예: nginx) 기반으로 Controller가 실제 라우팅 수행

deploy-frontend.sh

• Namespace → ConfigMap → Deployment(+rollout restart) → Service → Ingress 순으로 배포 자동화
  • Namespace 존재 확인 후 없으면 생성
  • ConfigMap 적용
  • Deployment 적용
  • Deployment rollout restart
  • Service 적용
  • Ingress 적용

4. 트래픽 흐름 (Mermaid)

sequenceDiagram
    participant U as 사용자 브라우저
    participant I as 인그레스 컨트롤러
    participant S as 서비스 (ClusterIP, Ingress)
    participant N as 프론트엔드 (React)
    participant B as 백엔드 (FastAPI)

    U->>I: GET /chat/123
    I->>S: 인그레스 규칙 기반 실행
    S->>N: 요청 전달
    N-->>U: index.html + static assets (SPA)

    U->>I: GET /api/chat
    I->>S: 인그레스 규칙 기반 실행
    S->>N: 요청 전달
    N->>B: proxy_pass /api/chat
    B-->>N: API/SSE response
    N-->>U: Stream/Response

5. 참고 정보

• Ingress는 규칙이고, 실제 처리는 Ingress Controller가 수행함
• IngressClass 이름은 클러스터에 설치된 클래스명과 일치해야 함
  • 클러스터에 무언가를 설치할 때, helm 쿠버네티스 패키지 매니저를 사용함
• SSE/스트리밍은 Nginx 프록시 버퍼링 및 timeout 설정 영향이 큼
• 정적 자원 캐시는 브라우저/중간망(CDN 등)에서 동작함