3-6. Argo CD GitOps 배포 흐름¶
Argo CD GitOps Lab의 판단 질문은 후보 모델을 Kubernetes에 직접 apply하지 않고 Git에 있는 배포 파일로 올릴 수 있는가입니다. 3-3과 3-4에서 후보 모델은 MLflow Model과 registry alias로 관리되고, 3-5에서 KServe runtime이 실제 endpoint 계층을 맡는다는 점을 확인했습니다. 이제 배포 방식은 kubectl apply가 아니라 Argo CD Application이 Git 경로를 읽고 KServe InferenceService를 동기화하는 구조로 바꿉니다.
이 Lab은 Argo CD 운영자가 되는 시간이 아닙니다. 수강생은 배포 파일과 실제 반영 여부를 확인합니다. 어떤 Git 경로가 배포 기준인지, Argo CD가 어느 namespace에 어떤 resource를 동기화하는지, KServe InferenceService가 후보 모델 artifact를 가리키는지 확인합니다.
| 항목 | 이번 Lab의 기준 |
|---|---|
| 받은 업무 | risk-classifier@candidate를 GitOps 방식으로 dev endpoint에 배포할 수 있는지 확인 |
| 결정 압박 | 직접 apply로 성공한 척하지 않고, Argo CD sync 확인 결과와 미검증 항목을 분리 |
| 확인 증거 | Argo CD Application, Kustomize overlay, KServe InferenceService, observability ConfigMap |
| 판단 산출물 | 후보 모델 배포 경로 확인 결과와 live sync 가능/불가 사유 |
3-6-1. GitOps 배포 단위 확인¶
GitOps 배포에서 첫 번째 확인 대상은 Git에 들어 있는 배포 파일입니다. Argo CD 공식 문서의 Application은 source repository, target revision, path, destination cluster/namespace, sync policy를 선언합니다. 이번 과정에서는 tta-aiqa의 demos/ch03_docker_kubernetes/argocd/application.yaml을 inspection 대상 Application으로 둡니다. 해당 파일이 아직 tta-aiqa에 없다면 이 단계는 실행 완료가 아니라 실습 코드 보강 필요 상태입니다.
이 파일의 repoURL은 교육장마다 달라지므로 기본값은 placeholder입니다. 실제 sync를 하려면 수강생 repository URL로 바꿔야 합니다. placeholder를 그대로 두고 sync가 실패했다면 그것은 실습 실패가 아니라 live sync blocker입니다. 보고서에는 “Application 구조는 확인했지만 repository URL 미설정으로 live sync는 수행하지 않았습니다”라고 기록합니다.
| 확인 항목 | 파일 위치 | 판단 기준 |
|---|---|---|
| Argo CD Application | demos/ch03_docker_kubernetes/argocd/application.yaml |
source.path가 GitOps overlay를 가리키는가 |
| 배포 대상 namespace | 같은 파일 spec.destination.namespace |
ai-quality namespace로 동기화되는가 |
| sync 옵션 | 같은 파일 spec.syncPolicy.syncOptions |
namespace 생성과 out-of-sync 적용 기준이 선언됐는가 |
| revision history | 같은 파일 revisionHistoryLimit |
되돌릴 후보가 남는가 |
이 확인은 “Argo CD가 설치되어 있다”는 사실보다 중요합니다. 설치된 도구가 있어도 Application이 잘못된 Git 경로를 가리키면 candidate와 다른 manifest가 배포될 수 있습니다.
3-6-2. GitHub Deploy key로 repository 연결¶
Argo CD가 private GitHub repository를 읽으려면 repository credential이 필요합니다. 이 과정에서는 tta-aiqa repository 하나를 Argo CD에 연결하므로 GitHub Deploy key를 read-only로 등록하는 방식이 가장 단순합니다. GitHub는 repository마다 Deploy key 등록 위치를 제공하지만, key pair 자체는 로컬에서 생성하고 public key만 GitHub에 등록합니다.
Deploy key 연결에서 봐야 할 핵심은 권한 방향입니다. GitHub에는 public key를 넣고, Argo CD에는 private key를 넣습니다. Argo CD는 Git repository를 읽기만 하면 되므로 Allow write access는 체크하지 않습니다. write 권한을 열면 실습 중 배포 도구가 repository를 수정할 수 있는 것처럼 오해할 수 있고, 최소 권한 원칙에도 맞지 않습니다.
| 위치 | 등록하는 값 | 확인할 기준 |
|---|---|---|
| 로컬 또는 관리자 PC | SSH key pair 생성 | private key와 public key가 분리되어 있는가 |
GitHub tta-aiqa repository |
Deploy keys에 public key 등록 | read-only이며 Allow write access가 꺼져 있는가 |
| Argo CD | repository credential에 private key 등록 | git@github.com:.../tta-aiqa.git URL을 읽을 수 있는가 |
Argo CD Application |
spec.source.repoURL |
Deploy key를 등록한 repository SSH URL과 같은가 |
실습 코드는 tta-aiqa에 준비합니다. Argo CD 관련 세부 작업은 setup_argocd_gitops.sh 하나로 실행합니다. 먼저 key pair를 만들고 public key를 화면에 출력합니다.
cd ../tta-aiqa
demos/ch03_docker_kubernetes/scripts/setup_argocd_gitops.sh key
출력된 public key를 GitHub의 tta-aiqa repository Settings -> Deploy keys에 등록합니다. 등록할 때 제목은 예를 들어 argocd-tta-aiqa로 두고, Allow write access는 체크하지 않습니다. 이 단계는 GitHub UI에서 수행하므로 script가 대신 완료했다고 쓰지 않습니다.
GitHub 등록이 끝나면 Argo CD에 private key를 등록합니다.
cd ../tta-aiqa
demos/ch03_docker_kubernetes/scripts/setup_argocd_gitops.sh connect
이 단계가 성공하면 Argo CD는 tta-aiqa Git repository를 읽을 수 있습니다. 그러나 repository credential 등록은 배포 성공이 아닙니다. 아직 Argo CD Application 등록, diff, sync, KServe Ready 확인이 남아 있습니다.
보고서에는 다음처럼 실행 범위를 제한해서 씁니다.
GitHub `tta-aiqa` repository에 read-only Deploy key의 public key를 등록하고,
Argo CD에는 같은 key pair의 private key를 repository credential로 등록했습니다.
따라서 Argo CD가 Git source를 읽을 수 있는 조건은 확인했지만,
Application sync와 KServe Ready는 별도 단계에서 확인해야 합니다.
3-6-3. KServe 배포 파일 확인¶
KServe 배포 파일의 핵심은 InferenceService가 후보 모델 artifact와 serving runtime 정보를 담는가입니다. 이번 과정의 목표 파일은 tta-aiqa 기준 demos/ch03_docker_kubernetes/gitops/base/inferenceservice.yaml이고, dev 환경에서는 gitops/overlays/dev/kustomization.yaml이 storage URI를 dev 후보로 바꿉니다. 이 파일들은 교재 repo가 아니라 tta-aiqa에서 관리되어야 합니다.
KServe는 추상화만 있는 도구가 아닙니다. InferenceService가 선언되면 KServe controller가 model format과 runtime 설정을 보고 실제 model server container를 준비합니다. scikit-learn 모델은 sklearn server 또는 MLServer 계열 runtime이 후보이며, Triton이나 vLLM은 다른 모델/워크로드에 맞는 runtime입니다. 따라서 수강생은 “KServe로 배포한다”를 “어떤 runtime이 실제 추론을 하는가”로 풀어 말할 수 있어야 합니다.
| 확인 항목 | 기대값 | 보고서에 남길 의미 |
|---|---|---|
| resource kind | InferenceService |
KServe가 처리할 serving 선언 |
| model alias label | ai-quality/model-alias: candidate |
현재 운영 모델이 아니라 후보 모델 endpoint임 |
| MLflow URI annotation | models:/risk-classifier@candidate |
model registry alias와 serving manifest 연결 |
| storage URI | pvc://ai-quality-models/risk-classifier/candidate |
model artifact 로딩 위치 |
| 응답/로그 필드 | request_id, score, prediction, latency_ms 등 |
4장에서 확인할 필드 |
이 표는 live cluster 없이도 확인할 수 있습니다. 다만 파일 inspection만으로는 Pod readiness, runtime image pull, model loading 성공을 말할 수 없습니다. 이 구분이 배포 판단에서 중요합니다.
3-6-4. 실습 목표¶
실습 목표는 Argo CD를 통해 후보 모델 endpoint 배포 경로를 확인하는 것입니다. 클러스터와 권한이 준비되어 있으면 tta-aiqa에서 Application 등록, diff, sync, KServe status 확인까지 진행합니다. 준비되어 있지 않으면 manifest inspection과 dry-run으로 대체하고, 실제 실행 확인이 없다는 사실을 명시합니다.
| 단계 | 실행 또는 확인 경로 | 예상 결과 | 실패 시 확인 |
|---|---|---|---|
| Manifest inspection | setup_argocd_gitops.sh check |
Application, overlay, InferenceService 구조 확인 | 파일 경로, kustomize, kubectl dry-run 조건 |
| Deploy key 생성 | setup_argocd_gitops.sh key |
public key 출력, private key 로컬 보관 | public/private key 방향, .argocd/ gitignore |
| Repository와 Application 등록 | setup_argocd_gitops.sh connect |
Argo CD repo credential과 Application 생성 | GitHub Deploy key 등록, Argo CD login, namespace |
| Diff와 sync | setup_argocd_gitops.sh sync |
out-of-sync 차이 확인 후 sync | argocd login, RBAC, repo credential |
| KServe 상태 | demos/ch03_docker_kubernetes/scripts/check_kserve_endpoint.sh |
InferenceService Ready 상태 확인 |
KServe 설치, storage, runtime, ingress |
이 Lab에서 금지하는 결론은 “script가 끝났으니 운영 배포 가능”입니다. Argo CD sync 성공은 Git의 배포 파일이 클러스터에 반영됐다는 뜻이고, 모델 응답과 운영 관측은 3-9와 4장에서 다시 확인해야 합니다.
3-6-5. 실행 코드¶
이 실행은 live cluster가 없어도 배포 파일 확인 결과를 남기도록 설계되어야 합니다. 먼저 tta-aiqa 루트로 이동한 뒤 manifest inspection을 실행합니다.
cd ../tta-aiqa
demos/ch03_docker_kubernetes/scripts/setup_argocd_gitops.sh check
예상 출력의 핵심은 Argo CD Application, Kustomize overlay, KServe InferenceService 파일이 모두 존재하고, 가능한 경우 kubectl --dry-run=client 또는 kustomize build가 성공한다는 점입니다.
[check] Argo CD Application manifest
[check] Kustomize overlay files
[skip] kubectl is not installed; manifest file inspection completed
[skip] kustomize is not installed; overlay file inspection completed
[done] Argo CD/KServe manifest inspection completed
클러스터가 준비된 교육장에서는 Application을 등록하고 sync를 진행합니다. 이 명령은 클러스터 상태를 변경하므로 shared cluster에서 권한과 namespace 정책을 확인한 뒤 실행합니다.
cd ../tta-aiqa
export ARGOCD_REPO_URL=git@github.com:seungbaeji/tta-aiqa.git
demos/ch03_docker_kubernetes/scripts/setup_argocd_gitops.sh connect
demos/ch03_docker_kubernetes/scripts/setup_argocd_gitops.sh sync
demos/ch03_docker_kubernetes/scripts/check_kserve_endpoint.sh
이 세 명령이 모두 성공하면 보고서에는 실제 sync 확인 결과를 쓸 수 있습니다. 하나라도 권한, repo, storage, runtime 문제로 실패하면 해당 blocker를 기록하고 파일 inspection 근거로 범위를 제한합니다.
3-6-6. 해석과 보고서 사용¶
이 Lab의 판단은 배포 성공 여부를 단정하는 것이 아니라 확인 범위를 나누는 것입니다. GitOps manifest inspection은 “배포 파일이 준비됨”을 보여 주고, Argo CD sync는 “Git의 배포 파일이 클러스터에 반영됨”을 보여 주며, KServe status는 “serving resource가 준비됨”을 보여 줍니다. 세 확인 결과는 서로 대체되지 않습니다.
| 확인한 것 | 쓸 수 있는 문장 | 아직 쓰면 안 되는 문장 |
|---|---|---|
| manifest inspection만 완료 | GitOps 배포 파일은 후보 모델 KServe endpoint를 선언합니다 | 후보 모델 endpoint가 live traffic을 받을 준비가 됐습니다 |
| manifest 없음 | GitOps/KServe 실습 자산이 아직 tta-aiqa에 준비되지 않았습니다 |
배포 파일 구조를 확인했습니다 |
| repository credential 등록 | Argo CD가 Git source를 읽을 credential을 갖습니다 | Application sync가 완료됐습니다 |
| Argo CD sync 완료 | Git의 배포 파일이 클러스터에 반영됐습니다 | 모델 응답 품질이 정상입니다 |
| KServe Ready 확인 | KServe resource가 Ready 상태입니다 | score, threshold, prediction 응답 계약이 충족됐습니다 |
/predict와 로그 확인 |
응답과 로그를 배포 판단에 사용할 수 있습니다 | 장기 운영 안정성이 보장됩니다 |
보고서 문장은 다음처럼 씁니다.
Argo CD Application은 Git 경로 `demos/ch03_docker_kubernetes/gitops/overlays/dev`를 source로 사용하고, KServe `InferenceService`는 `risk-classifier@candidate`와 candidate storage URI를 가리킵니다. 이번 실행에서는 [manifest inspection/live sync/KServe Ready]까지 확인했으며, `/predict` 응답 계약과 운영 관측 증거는 다음 단계에서 확인합니다.