ORCHESTRATION_K8S_DEPLOYMENT

오케스트레이션 서버 쿠버네티스 배포 (단일 노드 / NodePort)

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

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

---

1. 용어 정리

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

---

2. 아키텍처

트래픽 흐름:

외부 브라우저
   │  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 이름과 정확히 일치).

---

3. 매니페스트 세트

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

파일	리소스	역할
00-namespace.yaml	Namespace	orchestration 네임스페이스
10-configmap.yaml	ConfigMap	서버 일반 환경변수
11-secret.yaml	Secret	API 키·비번 (실값으로 채워야 함)
20-mosquitto.yaml	ConfigMap/PVC/Deployment/Service	MQTT 브로커 (1883, 9001)
21-ministack.yaml	PVC/Deployment/Service	S3 목 서버 (4566)
30-server.yaml	PVC/Deployment/Service	Go API 서버 (8080, SQLite)
40-backoffice.yaml	Deployment/Service	정적 프론트 (80)
50-nginx.yaml	ConfigMap/Deployment/Service	리버스 프록시 + 외부 진입점 NodePort 30090

---

4. docker-compose → 매니페스트 매핑

docker-compose	쿠버네티스 매니페스트	비고
services: 각 컨테이너	Deployment	실행 단위
ports / expose	Service	내부/외부 접근
environment: (일반 값)	ConfigMap	APP_PORT, S3_ENDPOINT 등
environment: (비밀 값)	Secret	LLM_API_KEY, MQTT_PASSWORD, S3_SECRET_KEY, STT_API_KEY
volumes: (데이터 영속)	PVC	/data(SQLite·로그), mosquitto/ministack 데이터
./nginx.conf:...:ro	ConfigMap → volumeMount	설정 파일 마운트
host.docker.internal:9001	mosquitto:9001	클러스터 내부 Service 참조로 교정
외부 노출(nginx)	NodePort Service (30090)

---

5. 배포 전 필수 작업

5.1 로컬 이미지를 노드에 로드 (가장 중요)

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을 시도하지 않는다.

5.2 Secret 실값 채우기

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=

5.3 외부 접근 URL 수정

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

---

6. 배포 & 확인

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

---

7. 주의사항

• 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 인바운드 허용 필요.

---

8. Helm 전환 (선택)

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

	raw 매니페스트	Helm 차트
배포	kubectl apply -f deploy/k8s/	helm install orchestration ./chart
값 변경	각 yaml 직접 편집	values.yaml 한 곳 / --set
업그레이드·롤백	수동	helm upgrade / helm rollback
환경별 값	파일 복사	-f values-prod.yaml
전체 삭제	리소스 개별	helm uninstall orchestration

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

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