03. MLflow 모델을 Argo CD와 KServe로 배포하기¶
3장은 학습한 모델을 실제 서비스 endpoint로 올리는 흐름을 확인하는 장입니다. 2장에서 데이터 검증 결과와 MLflow 평가 기록을 확인했다면, 이제 risk-classifier@candidate 모델을 Git에 선언하고 Argo CD가 KServe InferenceService로 반영하는 과정을 봅니다.
이번 장의 받은 업무는 “새 모델을 바로 운영에 올려라”가 아닙니다. 받은 업무는 후보 모델이 어디에서 왔고, 어떤 배포 파일로 올라가며, KServe에서 어떤 runtime이 실제 추론을 수행하는지 확인하는 것입니다.
| 기준 | 내용 |
|---|---|
| 받은 업무 | risk-classifier@candidate를 Argo CD 경로로 KServe에 배포할 수 있는지 확인 |
| 결정 압박 | 모델 파일을 손으로 복사하지 않고 Git과 Argo CD로 배포해야 함 |
| 이번 장에서 확인할 것 | MLflow model URI, Docker image, Argo CD Application, KServe InferenceService, sync 결과 |
| 이번 장의 산출물 | 배포 파일 확인 결과와 실제 sync/endpoint 확인 여부 |
| 다음 장으로 넘길 질문 | 배포된 endpoint의 응답과 로그가 확인되는가 |
1. 3장의 역할¶
3장의 핵심은 모델 파일이 실제 endpoint로 이어지는 경로를 끊기지 않게 보는 것입니다. MLflow Registry에 모델이 있다는 사실만으로 배포가 끝나지 않습니다. Argo CD가 바라보는 Git 경로에 KServe manifest가 있어야 하고, 그 manifest가 어떤 model URI와 runtime, storage URI를 사용하는지 확인할 수 있어야 합니다.
이번 과정에서는 Tree 기반 분류모델을 새 모델로 바꾸지 않습니다. 모델 자체는 2장에서 만든 scikit-learn 계열 모델로 두고, 배포 방식만 현대화합니다. 새 모델을 추가로 만드는 대신, 기존 모델을 MLflow Model, Registry alias, Git manifest, KServe InferenceService로 이어 붙입니다.
2. 다섯 단계¶
3장은 다섯 단계만 기억하면 됩니다. Docker로 실행 환경을 묶고, MLflow에서 배포할 모델을 확인하고, Argo CD가 Git의 배포 파일을 반영하고, KServe가 endpoint를 만들고, 마지막으로 응답과 로그를 확인합니다.
| 단계 | 확인할 것 | 왜 필요한가 |
|---|---|---|
| Docker | 이미지와 실행 설정 | 같은 조건으로 모델을 실행하기 위해 |
| MLflow | model URI와 version | 어떤 모델을 배포하는지 헷갈리지 않기 위해 |
| Argo CD | Application과 Git 경로 |
배포 파일을 Git 기준으로 관리하기 위해 |
| KServe | InferenceService와 runtime |
모델을 endpoint로 제공하기 위해 |
| 응답 확인 | request_id, model_version, score, prediction |
배포 후 결과를 추적하기 위해 |
이 표의 결론은 “도구를 많이 넣는다”가 아닙니다. 수강생은 모델이 어떤 파일에서 왔고, 어떤 설정으로 배포됐고, 어떤 응답을 돌려주는지만 설명할 수 있으면 됩니다.
3. 기본 실습 경로¶
3장의 기본 실습은 tta-aiqa 루트에서 실행하는 자산을 기준으로 정리합니다. FastAPI 계약 확인, Dockerfile과 Compose 기반 serving 확인, MLflow container 확인, Argo CD와 KServe manifest inspection을 분리해서 진행합니다. 교재 저장소의 JupyterLite notebook은 설치 없이 구조를 읽는 보조 경로입니다.
| 구분 | tta-aiqa 기준 경로 |
확인할 것 |
|---|---|---|
| FastAPI 계약 확인 | labs/ch03_serving/fastapi_serving_lab.ipynb, labs/ch03_serving/check_serving_contract.py |
요청 payload, 응답 schema, 오류 응답, train-serving 계약 |
| Docker/Compose 확인 | demos/ch03_docker_kubernetes/Dockerfile, compose.yaml |
컨테이너 이미지 포함물, serving-api, mlflow service |
| MLflow 확인 | compose.yaml, labs/ch02_model_quality/5_mlflow_tracking_lab.ipynb |
MLflow tracking server와 candidate 평가 기록 |
| Argo CD/KServe manifest 확인 | demos/ch03_docker_kubernetes/argocd/, demos/ch03_docker_kubernetes/gitops/, setup_argocd_gitops.sh check |
Application, KServe InferenceService, storage URI, render 결과 |
| 브라우저 보조 확인 | 교재 site의 jupyterlite/files/03_serving/ |
Dockerfile, MLflow URI, manifest 구조를 installation 없이 inspection |
이 구분은 초보자에게 특히 중요합니다. MLflow는 모델 출처와 평가 기록을 설명하고, Docker/Compose는 로컬에서 같은 실행 조건을 확인하며, Argo CD는 Git의 배포 의도를 클러스터에 반영하고, KServe는 실제 serving resource를 선언합니다. 세 도구를 한 셀에서 한꺼번에 확인하면 “무엇이 모델 출처이고 무엇이 배포 실행인지”가 섞입니다.
4. Argo CD를 쓰는 이유¶
Argo CD는 Git에 있는 배포 파일을 클러스터에 반영하는 도구입니다. 이 과정에서는 복잡한 운영 설정을 다루지 않고, “모델 배포 파일이 Git에 있고 Argo CD가 그 파일을 반영한다”는 흐름만 확인합니다.
수업에서는 kubectl apply -f kserve.yaml을 모델 배포의 기본 경로로 쓰지 않습니다. kubectl apply는 Argo CD Application을 등록하는 초기 작업에만 사용하고, 모델 serving resource는 Argo CD가 Git 경로를 sync해서 반영합니다.
| 작업 | 직접 적용 방식 | Argo CD 방식 |
|---|---|---|
| 배포 의도 | 로컬 YAML을 apply한 사람의 터미널에 남음 | Git path와 commit에 남음 |
| 변경 검토 | apply 전후 차이를 놓치기 쉬움 | argocd app diff로 desired/live 차이 확인 |
| 배포 실행 | kubectl apply 실행자 권한에 의존 |
argocd app sync 또는 sync policy로 실행 |
| 되돌림 | 이전 파일을 찾아 재적용 | 이전 Git revision 또는 이전 manifest로 되돌림 |
| 확인 결과 | 명령 실행 여부 중심 | repo URL, revision, sync status, health를 함께 기록 |
5. 실행 환경이 없을 때의 기준¶
Argo CD와 KServe는 실제 Kubernetes 클러스터가 있어야 끝까지 확인할 수 있습니다. 교육장에 준비된 클러스터와 model storage가 있으면 tta-aiqa의 GitOps manifest를 기준으로 argocd app sync까지 실행합니다. 준비되지 않았으면 배포 파일 확인, Kustomize render, client dry-run으로 대체하고 실제 endpoint 확인은 미확인으로 기록합니다.
| 상황 | 실행 경로 | 보고서에 쓸 수 있는 문장 |
|---|---|---|
| Argo CD와 KServe 모두 준비 | setup_argocd_gitops.sh check → key → connect → sync → check_kserve_endpoint.sh |
GitOps sync와 KServe resource health를 확인했습니다 |
| Kubernetes는 있으나 Argo CD 없음 | setup_argocd_gitops.sh check와 manifest inspection |
GitOps manifest 구조는 확인했지만 Argo CD live sync는 미확인입니다 |
| 클러스터 없음 | YAML, Kustomize, prepared artifact inspection | 배포 파일과 확인 항목은 정리했지만 실제 endpoint는 운영 환경에서 다시 확인해야 합니다 |
이 기준은 실습을 약하게 만드는 장치가 아닙니다. 실행하지 않은 것을 실행한 것처럼 쓰지 않게 만드는 안전장치입니다.
6. 문서 목록¶
문서 목록은 모델이 운영 endpoint가 되기까지의 실제 순서입니다. 3장이 끝나면 수강생은 Docker, MLflow, Argo CD, KServe, 응답 확인이 각각 무엇을 확인하는지 설명할 수 있어야 합니다.
| 순서 | 문서 | 확인할 내용 |
|---|---|---|
| 1 | 컨테이너 기본 개념 | 실행 환경과 모델 artifact를 이미지 단위로 고정하는 이유 |
| 2 | Docker 기반 모델 컨테이너 실행 | local smoke test와 이미지 계약 |
| 3 | MLflow 모델 배포 기준 | MLflow Model, Registry alias, model URI |
| 4 | 모델 학습 loop 고도화 | train, evaluate, register, 후보 모델 선택 |
| 5 | ML Serving 구조와 runtime 선택 | API wrapper, model server, KServe runtime 책임 분리 |
| 6 | Argo CD GitOps 배포 흐름 | Argo CD Application, diff, sync, fallback |
| 7 | Kubernetes와 KServe 실행 구조 | InferenceService, ServingRuntime, storage URI, readiness |
| 8 | 모델 배포 흐름 확인 | MLflow 모델에서 Argo CD sync와 KServe endpoint까지 연결 |
| 9 | 요청과 응답 흐름 이해 | endpoint response와 로그 필드 |
| 10 | 3장 마무리 | 4장으로 넘길 배포 확인 결과 |