시작 및 준비 상태 프로브¶

목표: Kubernetes가 Pod를 Ready로 판단하는 시점과 시작에 허용되는 시간을 확인합니다.

프로브의 의미와 동작은 Kubernetes Liveness, Readiness and Startup Probes 문서를 참고하세요. 이 문서는 다음 내용을 다룹니다.

차트의 프로브 기본값과 조정 방법
시작 예산에서 계산되는 Deployment 진행 기한
실패한 프로브를 확인하는 명령
종료 유예 시간

차트 기본값 및 조정¶

modelserver 컨테이너의 프로브는 modelserver.probes.{startup,readiness,liveness}로 조정합니다. 세 프로브의 차트 기본값은 다음과 같습니다.

프로브	경로	주기(초)	실패 임계값(회)	타임아웃(초)
`startupProbe`	`/v1/models`	30	240	10
`readinessProbe`	`/v1/models`	15	4	5
`livenessProbe`	`/health`	30	10	10

startupProbe가 Pod 시작에 허용하는 시간을 시작 예산이라고 합니다. 차트 기본값의 시작 예산은 30초 × 240회 = 2시간입니다. 모델 로드와 최초 컴파일은 시작 예산 안에 끝나야 합니다.

컴파일이 시작 예산보다 오래 걸리면 modelserver.probes.startup.failureThreshold를 높이세요. 엔진도 시작을 최대 VLLM_ENGINE_READY_TIMEOUT_S초(modelserver.serveEnv, 기본값 9600) 동안 기다립니다. 시작 예산을 이보다 길게 잡으면 VLLM_ENGINE_READY_TIMEOUT_S도 함께 높이세요.
최초 컴파일의 실측 소요 시간은 최초 시작 시간을 참고하세요.
modelserver 컨테이너의 CPU 제한이 컴파일 시간에 주는 영향은 리소스 및 노드 예산을 참고하세요.

Deployment 진행 기한¶

차트는 모든 modelserver Deployment의 progressDeadlineSeconds를 시작 예산과 같은 값으로 설정합니다.

계산식: initialDelaySeconds + periodSeconds × failureThreshold(modelserver.probes.startup의 값)
차트 기본값: 0 + 30 × 240 = 7200(2시간)
조정: modelserver.probes.startup을 바꾸면 progressDeadlineSeconds도 함께 바뀝니다. progressDeadlineSeconds를 따로 지정하는 values 키는 없습니다.

progressDeadlineSeconds를 Kubernetes 기본값인 600초로 두면, 정상적으로 컴파일 중인 Deployment도 10분 뒤 Progressing=False (ProgressDeadlineExceeded)로 표시됩니다.

현재 값은 다음 명령으로 확인하세요.

kubectl -n <ns> get deploy <release-name>-decode -o jsonpath='{.spec.progressDeadlineSeconds}{"\n"}'   # 7200

프로브 확인¶

Pod가 Ready 상태가 되지 않으면 다음 명령으로 확인하세요.

kubectl -n <ns> get events --field-selector involvedObject.name=<pod>   # 실패한 프로브를 확인합니다.
kubectl -n <ns> get pods -l 'llm-d.ai/role' -w                        # 각 Pod가 Ready 상태가 되는 시점을 확인합니다.

시작 중인 Pod가 반복해서 재시작하면 kubectl describe pod 출력으로 재시작 원인을 다음과 같이 구분합니다.

증상	원인	조치
Pod 이벤트에 `Startup probe failed`가 표시됩니다	Pod의 시작 시간이 시작 예산을 초과했습니다	`modelserver.probes.startup.failureThreshold`를 높이세요
`Startup probe failed` 이벤트 없이 `Last State: Terminated`와 종료 코드가 표시됩니다	컨테이너가 스스로 종료했습니다. 예를 들어 엔트리포인트가 컨테이너의 memlock 제한을 `unlimited`로 올리지 못하면 종료합니다	`kubectl logs --previous`로 이전 컨테이너의 로그를 확인하세요

종료 유예 시간¶

차트는 terminationGracePeriodSeconds를 설정하지 않습니다. 따라서 Kubernetes 기본값인 30초가 적용됩니다.

종료 유예 시간을 변경하려면 modelserver.podOverrides.<role>에 terminationGracePeriodSeconds를 설정하세요. 예제는 차트의 examples/pod-overrides.yaml에 있습니다.

Pod가 종료될 때 그 Pod가 처리하던 요청은 5xx 오류로 실패합니다.