orchestration-server 프로젝트(docker-compose.yml 구성)를 단일 서버 쿠버네티스 클러스터에 올리기 위한 매니페스트 세트와 배포 절차. 모든 의존 서비스(MQTT 브로커, S3 목)를 같은 클러스터 안에 띄우고, 외부 진입은 NodePort로 노출한다.

매니페스트 원본: orchestration-server/deploy/k8s/

• 배포용 YAML 파일 = 쿠버네티스 매니페스트(manifest)
• docker-compose → 매니페스트 전환 = "쿠버네티스로 마이그레이션"
• 매니페스트를 변수화해 패키징한 것 = Helm 차트 (선택, 8절 참고)

트래픽 흐름:

외부 브라우저
   │  http://<서버IP>:30090
   ▼
nginx (NodePort 30090)   ← 유일한 외부 진입점
   ├── /api, /health, /docs, /admin, /ws/ ... → orchestration-server:8080
   ├── /mqtt-ws                              → mosquitto:9001 (websocket)
   ├── /s3/                                  → ministack:4566
   └── /  (그 외)                            → backoffice:80

• 모든 리소스는 orchestration 네임스페이스에 생성.
• 서비스 간 통신은 Service 이름(DNS) 으로 연결 (nginx.conf의 upstream 이름과 정확히 일치).

orchestration-server/deploy/k8s/ — 파일명 앞 번호 순서대로 적용된다.

orchestration-server:local / orchestration-backoffice:local 은 로컬 빌드 이미지라 노드가 레지스트리에서 받아올 수 없다. 노드에 직접 넣어야 한다. 안 하면 ImagePullBackOff.

# 빌드
docker build -t orchestration-server:local .
docker build -t orchestration-backoffice:local ./backoffice

# 노드에 로드 (클러스터 종류에 따라 택1)
# k3s (containerd)
docker save orchestration-server:local | sudo k3s ctr images import -
docker save orchestration-backoffice:local | sudo k3s ctr images import -
# kind
kind load docker-image orchestration-server:local orchestration-backoffice:local
# minikube
minikube image load orchestration-server:local orchestration-backoffice:local

매니페스트는 imagePullPolicy: IfNotPresent 라 노드에 이미지가 있으면 pull을 시도하지 않는다.

11-secret.yaml 의 값들을 실제 값으로. git에 실값을 남기기 싫으면 명령으로 생성:

kubectl create secret generic orchestration-secret -n orchestration \
  --from-literal=LLM_API_KEY=... --from-literal=STT_API_KEY=... \
  --from-literal=S3_ACCESS_KEY=minioadmin --from-literal=S3_SECRET_KEY=minioadmin \
  --from-literal=MQTT_USERNAME= --from-literal=MQTT_PASSWORD=

10-configmap.yaml 의 S3_PUBLIC_BASE_URL 의 <서버IP> 를 실제 노드 IP로. (예: http://192.168.0.10:30090/s3/persona-images)

kubectl apply -f deploy/k8s/

kubectl get all -n orchestration
kubectl get pvc -n orchestration
kubectl logs -n orchestration deploy/orchestration-server -f

접속: http://<서버IP>:30090

• SQLite = 상태(state) 있음: orchestration-server 는 DATABASE_PATH=/data/orchestration.db 파일 DB를 쓴다.
  • replicas: 1 고정 — 2개 이상 늘리면 파일 락 충돌. strategy: Recreate 사용.
  • PVC(ReadWriteOnce)로 영속화 — 없으면 파드 재시작 시 데이터 소실.
  • 스케일아웃이 필요해지면 SQLite → PostgreSQL 등 외부 DB로 전환해야 한다.
• ministack(S3 목) 은 개발/PoC 용. 운영 전환 시 실제 S3 또는 MinIO로 교체하고 S3_ENDPOINT/Secret 을 맞게 수정.
• PVC: 클러스터에 기본 StorageClass 필요. 확인 kubectl get storageclass (k3s는 local-path 기본 제공).
• 방화벽: 노드의 30090 인바운드 허용 필요.

재배포가 잦거나 dev/prod 환경을 나눌 거면 Helm 차트로 감싸는 게 이득이다.

values.yaml로 뺄 만한 값: 노드 IP·NodePort, 이미지 태그, replica·리소스, Secret, ministack.enabled/mosquitto.enabled 토글(외부 S3·브로커 전환 대비).

한 번 올려두고 거의 안 건드릴 거면 raw 매니페스트로 충분하다.