Kubernetes 배포 구조¶
로컬 Compose가 정상이어도 대상 환경이 같은 이미지와 모델 패키지를 실행한다는 보장은 없습니다. 앞 페이지에서 확인한 것은 로컬 API의 모델 정보와 파일 지문이며, Candidate B의 모델 승인은 그대로 두되 대상 실행은 아직 미확인입니다. 이 페이지의 역할은 배포 파일이 컨테이너와 모델을 어떻게 배치하려는지를 읽고, 그 선언을 실제 실행 성공으로 바꾸지 않는 것입니다.
수강생은 공동 클러스터에 적용하거나 동기화, 되돌리기를 실행하지 않습니다. 제공된 선언 파일과 로컬 렌더링 결과만 읽고, 확인한 범위와 아직 보지 못한 범위를 나란히 적습니다. Git 기록이 클러스터에 반영됐는지는 다음 확인에서 다룹니다.
배포 선언을 읽는 기준
- 배포 파일은 실행하려는 상태를 보여 주고, 실제 Pod와 API 응답은 관측한 상태를 보여 줍니다.
- 파일에 경로나 개수가 적혀 있어도 지금 실행 중이거나 요청이 성공한 것은 아닙니다.
- 수강생은 공동 환경을 바꾸지 않고, 선언이 가리키는 이미지와 모델 폴더를 기록합니다.
컨테이너를 실행하는 Pod¶
이미지는 실행 재료이고, 실행 단위(Pod)는 그 재료로 지금 프로세스를 돌리는 Kubernetes의 기본 단위입니다. 이미지 이름만 같다고 실행이 시작된 것은 아니며, 상태와 로그는 이미지 설명이 아니라 Pod 경계에 남습니다. 앞 페이지에서 고정한 실행 환경과 모델 파일을 대상에 두려면, 먼저 그 실행이 어느 Pod에서 일어나는지를 나눠 봐야 합니다.
Risk API Pod와 예측 서버 Pod는 서로 다른 실행 경계입니다. Risk API Pod는 HTTP 요청을 받아 입력을 검사하고, 예측 서버 Pod는 KServe 모델 요청으로 점수를 계산합니다. KServe는 Kubernetes에서 모델 추론 서비스를 제공하는 도구이며, 예측 서버는 InferenceService mortality-risk가 만들도록 선언됩니다. 두 컨테이너가 항상 한 Pod 안에 있는 것은 아닙니다.
역할을 한 Pod로 합치면, 요청 검사 실패와 모델 파일 읽기 실패를 같은 원인으로 적게 됩니다. 아래 표는 현재 구성에서 두 Pod가 맡는 일과, 그 Pod만으로 아직 모르는 일을 나눕니다.
| 실행 단위 | 안에서 도는 컨테이너 | 맡는 일 | 이 단위만으로 아직 모르는 것 |
|---|---|---|---|
| Risk API Pod | risk-api |
공개 요청을 받고 입력을 검사하며 예측 서버를 호출함 | 예측 서버가 같은 Pod에 있는지, 지금 실행 중인지 |
| 예측 서버 Pod | kserve-container |
검사를 통과한 입력으로 모델 파일을 읽어 점수를 계산함 | 외부 호출자가 이 Pod를 직접 부르는지 |
두 Pod를 한 실행 단위로 보지 않아야 실패 위치를 고를 수 있습니다. Risk API가 떠 있어도 예측 서버가 없거나 준비되지 않으면 점수는 계산되지 않고, 반대도 마찬가지입니다. 이 절에서 말할 수 있는 것은 실행 경계가 둘로 나뉜다는 선언이며, 어느 Pod가 지금 준비됐는지는 아직 확인하지 않습니다.
Pod 상태를 유지하는 Deployment¶
배포 유지 자원(Deployment)은 어떤 Pod를 몇 개 유지할지의 목표를 적는 자원이며, 그 숫자가 지금 실행 중임을 증명하지 않습니다. Kubernetes는 원하는 상태와 실제 상태를 맞추려 하지만, 이미지 다운로드나 설정, 자원 문제로 실제 개수가 목표에 못 미칠 수 있습니다. 파일에 replicas가 있으면 이미 Pod가 떠 있다고 단정하지 않습니다.
현재 구성에서 risk-api Deployment는 Pod 한 개를 원하는 상태로 적습니다. 실행 이미지는 태그 이름이 아니라 내용 지문으로 고정하고, 준비 상태 확인은 /health/ready를 보도록 선언합니다. Deployment는 직접 컨테이너를 실행하지 않고, 다시 맞추는 규칙을 거쳐 Pod 목표를 유지합니다.
예측 서버는 이 Deployment가 만들지 않습니다. 예측 서버의 최소 개수는 InferenceService의 minReplicas로 따로 적혀 있으며, 기본값도 한 개입니다. 따라서 Risk API Deployment가 정상이어도 예측 서버가 준비됐다고 확장하지 않습니다.
선언한 목표와 지금 관측한 실행은 다른 자료입니다. 아래 표는 risk-api Deployment 파일에서 읽는 값과, 그 값만으로 닫히지 않는 질문을 나눕니다.
| 파일에 적힌 값 | 이 값이 뜻하는 것 | 이 값만으로 단정하지 않는 것 |
|---|---|---|
replicas: 1 |
Risk API Pod를 한 개 유지하려는 목표 | 지금 한 개가 실행 중이고 요청을 받을 수 있음 |
| 고정한 실행 이미지 | 어떤 코드와 라이브러리로 프로세스를 시작하려 함 | 이미지가 이미 내려받아져 컨테이너가 떠 있음 |
/health/ready |
준비 여부를 이 경로로 확인하도록 선언함 | 지금 그 확인이 성공했음 |
목표 개수가 1이어도 실제 실행 수는 0일 수 있습니다. 보고서에 적을 수 있는 문장은 “Risk API는 Pod 한 개를 유지하도록 선언되어 있다”까지이며, “지금 한 개가 실행 중이다”는 대상 환경의 별도 확인이 필요합니다.
일정한 접속 주소를 제공하는 Service¶
호출자는 바뀌는 Pod 주소를 직접 외우지 않고, 고정 접속 주소(Service)의 이름과 포트를 부릅니다. Pod는 다시 만들어질 때마다 주소가 바뀔 수 있으므로, 일정한 입구가 없으면 같은 서비스를 반복해 확인할 수 없습니다. risk-api Service는 포트 80으로 받아 컨테이너의 HTTP 포트로 넘기도록 선언되어 있습니다.
Service는 연결 규칙으로 요청을 받을 Pod를 고릅니다. 현재 규칙은 app.kubernetes.io/name: risk-api이며, 이 이름에 맞는 Risk API Pod만 후보가 됩니다. 지금 어느 Pod가 응답하는지는 실제로 연결된 대상을 봐야 알 수 있고, 파일의 규칙만으로 특정 Pod 주소가 영구히 보장되지는 않습니다.
Service가 있다고 항상 정상 Pod로 보낸다고 보장하지 않습니다. 준비 확인을 통과한 Pod만 요청을 받도록 연결되어 있으며, 준비된 Pod가 없으면 Service 이름은 남아도 요청은 실패할 수 있습니다. 예측 서버는 mortality-risk-predictor라는 내부 주소를 쓰도록 Risk API 설정에 적혀 있고, 이 주소는 공개 입구가 아닙니다.
고정 입구와 실제 전달은 다른 확인입니다. 아래 표는 Service가 보여 주는 사실의 범위를 나눕니다.
| 확인 대상 | 선언에서 읽는 값 | 이 값만으로 아직 모르는 것 |
|---|---|---|
risk-api Service |
이름 risk-api, 포트 80, Risk API Pod를 고르는 규칙 |
지금 준비된 Pod가 있는지 |
| 내부 예측 주소 | mortality-risk-predictor를 가리키는 Risk API 설정 |
예측 서버가 그 이름으로 응답하는지 |
| Pod 주소 | 다시 만들어지면 바뀔 수 있음 | 특정 주소를 다음에 다시 써도 되는지 |
Service 정상은 모델 품질도, 예측 서버 준비도 대신하지 않습니다. 공개 예측은 이 고정 입구를 거쳐 Risk API로 들어가도록 선언되어 있으며, 실제 전달 성공은 아직 확인하지 않습니다.
배포 파일과 실제 실행 상태¶
배포 YAML은 만들려는 객체와 설정을 적은 목표 상태이며, 클러스터의 현재 실행 상태가 아닙니다. 파일을 읽거나 로컬에서 렌더링해 통과했다고 대상 환경 배포가 끝난 것은 아닙니다. 적용 전 설정 검사는 “무엇을 실행하려 하는가”만 보여 주고, 목표 반영과 준비 결과가 없으면 실행 중이라고 말하지 않습니다.
로컬 렌더링은 클러스터를 바꾸지 않고 선택한 설정을 펼쳐 보는 검사입니다. tta-aiqa 저장소 루트에서 아래 명령을 쓰면 Candidate B를 실행하려는 상태가 표준 출력으로 나옵니다. 이 명령은 적용, 동기화, 되돌리기가 아닙니다.
kubectl kustomize deploy/k8s/candidate-b
렌더링 결과에서 확인할 것은 선택한 모델 폴더와 예상 모델 SHA-256이 한 묶음으로 바뀌는가입니다. 결과가 파일로만 남아도 대상 Pod가 준비됐다는 뜻은 아니며, kubectl이 없으면 같은 overlay 파일을 직접 읽고 렌더링하지 못한 이유를 남깁니다. 계약 검사 명령과 기록 칸은 서빙 실습을 따릅니다.
설정 검사와 실행 확인을 한 단계로 합치면, 선언만 보고 배포 완료를 쓰게 됩니다. 아래 표는 지금 이 페이지에서 할 수 있는 확인과 할 수 없는 확인을 나눕니다.
| 확인 | 볼 수 있는 것 | 보고할 수 있는 문장 |
|---|---|---|
| 배포 파일 읽기 | 목표 개수, 이미지, 경로, 예상 해시 | “대상에 실행하려는 상태가 이렇게 적혀 있다.” |
| 로컬 렌더링 | 공통 설정에 overlay를 더한 결과 | “이 설정은 승인된 모델 폴더를 가리키도록 펼쳐진다.” |
| 대상 실행 상태 | 이 페이지의 범위 밖 | 성공을 추정하지 않고 미확인으로 남김 |
정적 검사 통과는 준비된 선언이 맞다는 뜻입니다. 대상 환경의 반영, 준비, 요청 성공은 다른 자료이므로, 이 절의 결과를 배포 완료로 올리지 않습니다.
공통 설정과 환경별 설정¶
환경별 설정(overlay)은 공통 구조 위에 이번 배포에서 바꿀 값만 덧붙이며, 파일 이름이 실제 배포나 되돌리기 완료를 뜻하지는 않습니다. 공통 설정(base)에는 Risk API, 예측 서비스, 모델 저장소, 설정값이 함께 있습니다. 세 overlay는 그 공통 구조에서 출발하지만, 해시와 경로를 모두 바꾸지는 않습니다.
기준 모델 overlay는 릴리스 주석만 더하고, 모델 폴더와 예상 모델 파일 지문(SHA-256)은 공통 설정의 기준 모델 값을 그대로 씁니다. Candidate B overlay만 예상 SHA-256과 Risk API, 예측 서버의 선택 경로를 Candidate B 폴더로 바꿉니다. 되돌리기 overlay는 모델 폴더와 해시를 다시 쓰지 않고 공통 설정의 기준 모델을 유지한 채, 되돌리기 동작 주석을 더합니다. Candidate B와 되돌리기 overlay는 관측 수집 구성도 덧붙이지만, 이 교시에서 모델 선택은 경로와 예상 지문으로 봅니다.
세 파일이 서로 다른 목표를 표현한다고 해서 세 목표가 이미 적용된 것은 아닙니다. 아래 표는 실제 overlay 파일을 렌더링해 확인한 차이입니다.
| overlay | 실제로 바꾸는 값 | 바꾸지 않는 값 |
|---|---|---|
| 기준 모델 | 릴리스 주석 baseline-f2576f12512a |
모델 경로, 예상 SHA-256, 실행 이미지 |
| Candidate B | 선택 경로 physionet-2012/v2/candidate-b-c712a8e52344, 예상 SHA-256 c712a8e52344..., 릴리스 주석 |
실행 이미지 내용 지문 |
| 되돌리기 | 릴리스 주석과 되돌리기 동작 표시 | 모델 경로와 예상 SHA-256은 기준 모델 유지, 실행 이미지 |
Candidate B overlay 파일에 후보 경로가 있고 되돌리기 overlay에 기준 모델 이름이 있어도, 그 사실이 대상에 반영됐거나 되돌리기가 끝났다는 뜻은 아닙니다. 로컬 계약 검사는 승인되지 않은 후보 경로가 선언에 섞이지 않았는지만 보며, 대상 적용 성공은 다음 확인의 자료입니다.
모델 저장소와 선택 경로¶
모델 파일은 한 저장소에 두고, 컨테이너가 읽을 폴더만 고르는 방식이 실행 모델을 가릅니다. 저장소 요청(PersistentVolumeClaim, PVC) 이름은 course-models이며, Risk API와 예측 서버가 같은 저장소를 각자의 경로로 연결하도록 선언되어 있습니다. 파일에 경로가 적혀 있다고 그 폴더가 이미 붙어 준비된 것은 아닙니다.
컨테이너가 읽을 하위 폴더를 고르는 값이 subPath이며, 이 선택이 실행 모델을 가릅니다. 공통 설정은 physionet-2012/v2/baseline-f2576f12512a를 읽고, Candidate B overlay만 physionet-2012/v2/candidate-b-c712a8e52344로 바꿉니다. Risk API는 이 폴더의 metadata.json을, 예측 서버는 같은 폴더의 model.joblib을 읽도록 경로가 적혀 있습니다.
경로 선언과 실제 연결은 다른 확인입니다. 아래 표는 저장소, 선택 경로, 컨테이너 위치가 각각 보여 주는 범위를 나눕니다.
| 대상 | 선언에서 읽는 값 | 이 값만으로 단정하지 않는 것 |
|---|---|---|
| 모델 저장소 | course-models |
저장소에 해당 폴더와 파일이 실제로 있는지 |
| 선택 경로 | 기준 모델 또는 Candidate B 폴더 | 그 경로가 지금 컨테이너에 붙어 있는지 |
| 컨테이너 위치 | /runtime/model |
파일이 열려 점수를 계산할 준비가 됐는지 |
subPath가 맞다고 마운트가 끝난 것은 아닙니다. 경로만 확인하고 준비 상태까지 통과했다고 쓰면, 빈 폴더나 다른 파일을 읽는 실패를 놓칩니다. 이 절의 판단은 “선언이 어느 폴더를 고르는가”이며, 연결 완료와 준비 완료는 대상 환경의 별도 자료입니다.
컨테이너 이미지와 모델 파일의 두 지문¶
실행 이미지의 내용 지문과 모델 파일의 내용 지문은 서로 다른 대상을 가리키므로 한 값으로 합치지 않습니다. 이미지 내용 지문(digest)은 코드와 라이브러리가 담긴 실행 꾸러미를 식별하고, 모델 SHA-256은 학습 결과 파일 내용을 식별합니다. 모델 지문 하나가 이미지와 배포 과정까지 자동으로 보장하지는 않습니다.
공통 설정은 두 실행 이미지를 이미지 digest로 고정합니다. Risk API 이미지 앞자리는 20f47861095b이고, 예측 서버 이미지 앞자리는 63ff48ef3310입니다. 세 overlay를 렌더링해도 이 이미지 지문은 바뀌지 않으며, 모델 폴더를 바꿔도 실행 코드 꾸러미가 같이 바뀌지는 않습니다.
모델 지문은 ConfigMap model-identity의 예상 SHA-256으로 선언됩니다. 기준 모델과 되돌리기는 f2576f12512a...를 유지하고, Candidate B overlay만 c712a8e52344...로 바꿉니다. 예측 서버는 이 예상값과 읽은 파일 내용이 다를 때 준비 상태로 올라가지 않도록 선언되어 있습니다.
두 지문을 한 이름으로 부르면, 이미지는 맞는데 모델 폴더가 다른 상태를 통과로 읽게 됩니다. 아래 표는 대조 단위를 나눕니다.
| 지문 | 식별하는 대상 | 현재 선언에서 읽는 위치 | 이 지문이 대신하지 않는 것 |
|---|---|---|---|
| 이미지 digest | Risk API와 예측 서버의 실행 꾸러미 | 각 컨테이너의 고정 이미지 | 연결한 모델 파일이 같은지 |
| 모델 SHA-256 | model.joblib 내용 |
model-identity의 예상값과 선택한 폴더 |
이미지가 같고 배포가 끝났는지 |
이미지가 같아도 선택한 모델 경로가 다르면 예측 규칙이 달라집니다. 보고서에 두 지문을 나란히 적고, 한쪽이 맞다고 다른 쪽과 대상 실행까지 통과했다고 쓰지 않습니다.
외부 요청이 모델까지 가는 경로¶
외부 예측 요청은 모델 파일을 직접 읽지 않고, Risk API Service와 Pod를 거쳐 내부 예측 서버와 모델 폴더로 이어지도록 선언되어 있습니다. 이 그림은 배포 파일이 정한 경로이며, 실제 요청 성공을 증명하지 않습니다. API와 모델 계산은 다른 실행 경계이므로, 공개 입구의 응답만 보고 모델 파일이 열렸다고 단정하지 않습니다.
선언 경로는 고정 입구에서 모델 폴더까지 네 칸이며, 한 칸의 파일만으로 전체가 성공한 것은 아닙니다. 호출자는 risk-api Service로 들어가고, 연결 규칙이 준비된 Risk API Pod로 보냅니다. Risk API는 입력을 검사한 뒤 설정에 적힌 mortality-risk-predictor 주소로 점수 계산을 넘기고, 예측 서버가 /runtime/model/model.joblib을 읽습니다.
이 경로의 한 칸이 비어도 요청은 실패할 수 있습니다. Service만 있고 Pod가 없거나, Risk API는 떠 있는데 예측 서버가 준비되지 않았거나, 폴더가 선언만 되고 파일이 없으면 결과는 달라집니다. 아래 표는 선언 경로의 칸과, 그 칸만으로 말할 수 없는 성공을 나눕니다.
| 순서 | 선언된 다음 칸 | 이 칸의 파일이 증명하는 것 | 이 칸만으로 증명하지 않는 것 |
|---|---|---|---|
| 1 | risk-api Service |
외부 요청이 들어올 고정 이름과 포트 | 지금 요청이 이 입구를 통과함 |
| 2 | Risk API Pod | 입력 검사와 내부 호출을 맡을 실행 단위 | 그 Pod가 준비되어 응답함 |
| 3 | KServe 예측 서버 | 점수 계산을 맡을 실행 단위와 내부 주소 | 예측 서버가 요청을 받아 계산함 |
| 4 | 모델 폴더 | 읽을 파일 위치 /runtime/model |
파일이 열려 같은 내용인지 |
선언 경로가 이어져 보여도 실제 200은 별도 확인입니다. 로컬 Compose의 성공이나 overlay 렌더링을 이 경로의 대상 성공으로 옮기지 않으며, 보지 못한 칸은 미확인으로 남깁니다.
Kubernetes 전체 배포 관계¶
지금까지의 자원은 한 요청 흐름의 역할과 목표 상태이며, 관계 그림이 대상 환경의 준비와 배포 완료를 증명하지는 않습니다. 요청은 Service로 들어가 Deployment가 유지하는 Risk API로 가고, Risk API는 입력을 검사한 뒤 InferenceService가 맡은 예측 단위에 점수 계산을 요청합니다. PVC는 모델 폴더를 연결하고, 이미지 인증 Secret은 실행 이미지를 받는 데 쓰입니다.
각 자원의 준비와 내용 확인은 관계와 따로 봐야 합니다. Service가 있어도 준비된 Pod가 없으면 요청은 멈추고, 예측 서버가 떠 있어도 선택한 폴더의 파일 내용이 다르면 같은 모델이 아닙니다. 실행 이미지 digest와 모델 SHA-256은 이 관계 위에서 서로 대신할 수 없는 두 지문으로 남습니다.
대상 환경을 보기 전에는 선언 관계만 보고한 상태입니다. 아래 표는 한 요청을 구성하는 자원과, 그 자원이 닫지 않는 확인을 모읍니다.
| 자원 | 요청 경로에서 맡는 일 | 아직 별도로 확인할 것 |
|---|---|---|
risk-api Service |
외부 요청의 고정 입구 | 지금 준비된 Pod로 전달되는지 |
risk-api Deployment |
Risk API Pod 목표 유지 | 선언한 개수가 실제로 실행 중인지 |
InferenceService |
예측 서버와 모델 연결 | 예측 단위가 요청을 받을 준비가 됐는지 |
course-models PVC |
모델 폴더 보관과 선택 경로 | 해당 폴더가 붙어 파일이 열리는지 |
| 이미지 인증 Secret | 고정 이미지를 받기 위한 자격 | 이미지가 내려받아져 지문이 같은지 |
지금은 선언이 승인된 모델 폴더를 가리킨다는 문장까지만 쓸 수 있습니다. “Candidate B overlay는 승인된 모델 폴더와 예상 SHA-256을 가리키도록 선언되어 있으나, 대상 환경의 준비 상태와 요청 성공은 확인하지 못했다.” 대상 확인 상태는 target_pending으로 두고, 공동 클러스터를 직접 바꾸지 않습니다. 다음 확인은 GitOps와 배포 상태에서 Git에 적은 목표와 클러스터 현재 상태를 자료로 나눕니다.