3-7. Kubernetes 실행 구조 이해¶
3-7의 목표는 제공된 Kubernetes 매니페스트(manifest)를 읽고 모델 API가 어떤 이미지(image), 환경 변수(env), 준비 상태(readiness) 기준으로 실행되는지 확인하는 것입니다. 클러스터 운영자가 되는 것이 아니라, 배포 환경에서 품질 확인에 필요한 설정을 읽는 데 집중합니다.
이 문서를 읽을 때는 다음 기준을 중심으로 확인합니다.
- 실행 단위: Pod가 어떤 컨테이너(container)를 실행하는지 확인
- 배포 설정: Deployment가 어떤 이미지 태그(image tag)와 준비 상태 점검(readiness probe)을 사용하는지 확인
- 설정 주입: ConfigMap의
MODEL_VERSION,MODEL_THRESHOLD,EVENT_LOG_PATH가 컨테이너 환경 변수로 들어가는지 확인 - 접근 경로: 서비스 포트(service port)와 컨테이너 포트(container port)가 맞는지 확인
3-7-1. Kubernetes가 필요한 이유¶
Kubernetes는 컨테이너를 운영 환경에서 배포하고 상태를 관리하는 도구입니다. 여기서는 Kubernetes 운영법을 깊게 다루지 않습니다. Pod, Deployment, Service, ConfigMap의 역할을 읽고, QA가 어떤 정보를 확인해야 하는지 이해하는 것이 목표입니다.
Docker가 단일 컨테이너 실행에 가깝다면 Kubernetes는 여러 컨테이너를 운영 환경에서 안정적으로 실행하고 교체하는 구조를 제공합니다. AI 서빙에서는 이미지 태그, 환경 변수, 준비 상태 점검(readiness probe), 서비스 포트가 품질 확인과 연결됩니다.
Kubernetes Pod 문서는 Pod를 하나 이상의 컨테이너를 담는 기본 실행 단위로 설명합니다. 중요한 것은 Pod나 Deployment를 운영자가 관리하는 세부 기술로 외우는 것이 아닙니다. QA는 어떤 이미지가 실행되고, 어떤 환경 변수가 주입되며, 준비 상태가 어떤 기준으로 확인되는지 읽을 수 있어야 합니다. 그래야 배포가 “되었다”는 상태와 품질 기준이 “유지된다”는 상태를 구분할 수 있습니다.
수강생이 매니페스트를 직접 작성하지 않고, 제공된 매니페스트를 읽으며 배포 흐름을 확인합니다. 핵심은 “Kubernetes를 잘 쓰는 법”이 아니라 “배포 환경에서 모델 API가 어떤 설정으로 실행되는지 확인하는 법”입니다.
실습용 클러스터가 없거나 공유 클러스터 변경 권한이 불명확하면 kubectl apply를 실행하지 않습니다. 이 장에서는 그런 상황도 정상적인 blocker로 취급하고, 매니페스트 inspection 결과를 보고서 근거로 남깁니다. 독자가 확인해야 할 것은 실제 클러스터 운영 능력이 아니라 이미지, 환경 변수, 준비 상태 기준이 품질 판단과 어떻게 연결되는지입니다.
3-7-2. Pod와 Deployment 역할¶
| 리소스 | 역할 | QA 확인 포인트 |
|---|---|---|
| Pod | 컨테이너 실행 단위 | 어떤 이미지와 환경 변수가 실행되는지 확인 |
| Deployment | Pod 복제와 롤아웃(rollout) 관리 | 이미지 태그와 준비 상태 점검(readiness probe)을 확인 |
| Service | Pod 접근 경로 | 포트(port)와 selector가 맞는지 확인 |
| ConfigMap | 설정값 분리 | 임계값(threshold), 모델 버전(model_version), 로그 경로가 의도와 같은지 확인 |
Pod는 실제 컨테이너가 실행되는 단위입니다. Deployment는 Pod를 원하는 개수만큼 유지하고 새 버전으로 교체하는 역할을 합니다. Service는 외부 또는 클러스터 내부에서 Pod에 접근하는 경로를 제공합니다. ConfigMap은 임계값, 모델 버전, 로그 경로처럼 배포 환경에서 바뀔 수 있는 설정을 코드와 분리합니다.
QA는 이 구조를 읽고 다음 질문에 답할 수 있어야 합니다.
| 질문 | 이유 |
|---|---|
| 배포 이미지 태그 | 모델/코드 버전 확인 |
MODEL_THRESHOLD 주입 위치 |
FP/FN 기준 확인 |
| 준비 상태 점검(readiness probe) 확인 대상 | 트래픽을 받기 전 준비 상태 확인 |
| 서비스 포트와 컨테이너 포트(container port) 일치성 | API 접근 가능성 확인 |
3-7-3. 제공된 매니페스트 구조 확인¶
매니페스트는 demos/ch03_docker_kubernetes/k8s 아래에 있습니다.
| 파일 | 확인할 내용 |
|---|---|
namespace.yaml |
실습 namespace |
configmap.yaml |
MODEL_VERSION, MODEL_THRESHOLD, API_PORT, EVENT_LOG_PATH |
deployment.yaml |
이미지, envFrom, readinessProbe |
service.yaml |
서비스 포트와 targetPort |
매니페스트를 볼 때는 YAML 문법 자체보다 설정값의 흐름을 봐야 합니다. ConfigMap에 정의된 값이 Deployment의 환경 변수로 들어가고, 컨테이너 안의 FastAPI 앱이 그 값을 읽어 응답에 노출하는 흐름입니다.
단, 모든 설정이 ConfigMap에 있는 것은 아닙니다. 이 Demo에서 MODEL_PATH는 Dockerfile의 기본 환경 변수와 이미지에 포함된 모델 산출물(model artifact)에 의존합니다. 따라서 Kubernetes 매니페스트만 보면 모델 버전과 임계값은 확인할 수 있지만, 어떤 모델 파일이 이미지에 들어갔는지는 Dockerfile과 이미지 빌드 과정까지 함께 확인해야 합니다.
QA 확인 포인트는 다음과 같습니다.
| 확인 항목 | 실패 시 영향 |
|---|---|
| 이미지 태그 | 잘못된 코드나 모델이 배포될 수 있음 |
| ConfigMap 값 | 임계값, 모델 버전, 로그 경로가 달라질 가능 |
| readinessProbe | 준비되지 않은 Pod가 트래픽을 받을 가능 |
| service selector | 요청이 Pod로 전달되지 않을 가능 |
3-7-4. 운영 환경과 실습 환경의 차이¶
실제 운영에서는 이미지 레지스트리(image registry), Secret, 리소스 제한(resource limit), 자동 확장(autoscaling), 네트워크 정책(network policy) 등이 추가됩니다. 이 주제들은 간단히 언급만 하고, QA 확인 포인트는 이미지, 환경 변수, 준비 상태, API 계약(contract)에 둡니다.
운영 환경에서는 보안, 권한, 비용, 확장성 같은 주제가 중요하지만, 2일 교육에서 모두 다루면 AI QA의 핵심 흐름이 흐려집니다. 따라서 Kubernetes는 “AI 서비스가 어떤 설정으로 실행되는지 보여주는 배포 구조”로만 사용합니다.
수강생은 다음 정도를 이해하면 충분합니다.
| 이해할 것 | 깊게 다루지 않는 것 |
|---|---|
| Pod, Deployment, Service, ConfigMap 역할 | 클러스터 운영 |
| 이미지와 환경 변수 확인 | autoscaling 세부 설정 |
| 준비 상태와 상태 확인(health check) | Ingress, service mesh |
| 매니페스트 읽기 | 매니페스트 작성 심화 |