Pod 명세 요구 사항¶

목표: 이 스택의 Pod가 요구하는 권한, 포트, 볼륨, CPU, 메모리를 확인하고, 클러스터 정책과 노드의 할당 가능(allocatable) 리소스가 이 요구를 허용하는지 확인합니다.

권한 및 실행 모드¶

1
2
3

helm upgrade --install <release-name> ./coding-assistant-stack -n <ns> \
  -f ./coding-assistant-stack/examples/root-privileged.yaml \
  <values to fill in>

컨테이너 포트¶

NetworkPolicy나 방화벽으로 Pod 간 트래픽을 제한하는 클러스터에서는 다음 표의 포트와 NIXL 사이드 채널 포트로 가는 Pod 간 트래픽을 허용하세요.

다음 표는 레퍼런스 구성 기준입니다. 레퍼런스 구성에서 prefill은 pipeline parallel(PP) 병렬도 4로, decode는 data parallel(DP) 병렬도 4로 실행하고, decode 앞에 라우팅 사이드카를 둡니다. 이름 열은 차트가 선언하는 컨테이너 포트 이름입니다. 병렬도가 다르면 rank 포트 수도 달라집니다(주요 차트 설정 참고).

prefill의 8001, 8002, 8003은 포트 shim이 받습니다. Endpoint Picker(EPP)와 라우팅 사이드카는 prefill에도 decode와 같은 포트 목록(8000, 8001, 8002, 8003)으로 요청을 보냅니다. 그런데 PP로 실행한 prefill의 API 서버는 8000만 엽니다. 그래서 차트가 포트 shim을 실행해 8001, 8002, 8003으로 온 요청을 8000으로 전달합니다.

볼륨¶

스택은 modelserver Pod마다 다음 볼륨을 마운트합니다.

레퍼런스 구성은 Pod를 여러 노드에 배치합니다. 따라서 storage.model과 storage.compileCache에는 ReadWriteMany(RWX)를 지원하는 StorageClass가 필요합니다. 두 볼륨은 다음과 같이 지정하세요.

• storage.model은 반드시 지정하세요. 가중치 위치가 클러스터마다 다르므로 차트에 기본값이 없고, 지정하지 않으면 렌더링이 실패합니다. 레퍼런스 구성은 Secret 및 모델 저장소에서 만든 250Gi PVC를 kind: existingClaim으로 지정합니다. 용량은 모델 가중치 크기에 여유 공간을 더해 정하세요.
• storage.compileCache는 차트가 PVC를 생성합니다. 차트 기본 용량은 200Gi입니다. storageClass를 비워 두면 클러스터 기본 StorageClass를 사용합니다. 용량과 accessModes는 최초 설치 전에 정하세요(PVC 구성, 용량 및 accessModes 참고).

볼륨 소스는 kind만으로 선택합니다. 허용하는 kind 값은 볼륨마다 다릅니다.

차트는 compileCache에 emptyDir를 허용하지 않습니다. modelserver 워크로드는 Deployment라서 복제본별 영속 볼륨이 없고, emptyDir를 쓰면 Pod가 재시작할 때마다 다시 컴파일하기 때문입니다.

storage.dshm에는 kind가 없고, kind를 지정하면 렌더링이 실패합니다. storage.dshm은 항상 메모리 기반 emptyDir입니다. /dev/shm에 쓴 데이터는 modelserver 메모리 제한에 포함됩니다. storage.dshm.size를 높이면 modelserver.resources의 메모리 requests와 limits도 같은 양만큼 높이세요.

1
2
3
4
5

storage:
  modelOffload:
    enabled: true
    storageClass: <sc-name>   # kind: pvc에서 필수입니다. reclaimPolicy: Delete인 StorageClass를 지정하세요.
    size: 512Gi

리소스 및 노드 예산¶

modelserver.resources의 기본값은 CPU 40코어, 메모리 630Gi이며 requests와 limits가 같습니다. prefill과 decode는 같은 modelserver.resources 값을 사용합니다. 메모리 기본값이 630Gi인 이유는 NIXL이 KV 버퍼를 등록할 때 decode가 호스트 메모리를 추가로 사용하기 때문입니다.

설치 전에 각 노드의 할당 가능 메모리와 CPU가 다음 계산식을 충족하는지 확인하세요.

allocatable(memory) ≥ modelserver memory × (pods on that node) + routing sidecar 256Mi × (decode pods on that node) + EPP 8Gi + gateway ~0.2Gi
allocatable(CPU)    ≥ modelserver CPU    × (pods on that node) + routing sidecar 0.2  × (decode pods on that node) + EPP 4 + gateway 0.1

메모리: 가장 놓치기 쉬운 항목은 차트가 함께 실행하는 EPP입니다. EPP를 계산에서 빼면 할당 가능 메모리를 몇 GB 초과해 Pod가 스케줄링되지 않을 수 있습니다. 설치 전 메모리 확인 방법은 노드 메모리 예산 확인을 참고하세요.

CPU: 서빙에는 기본값인 40코어면 충분합니다. 하지만 최초 컴파일은 서빙보다 많은 스레드를 실행합니다. CPU 제한(limit)이 너무 낮으면 cgroup이 컴파일 스레드의 실행을 지연(throttle)시킵니다. throttle은 로그에 아무것도 남기지 않고 시작만 느리게 만듭니다. 컴파일이 시작 예산(시작 및 준비 상태 프로브 참고)을 넘으면 시작 프로브가 실패하고 kubelet이 Pod를 다시 시작합니다.

cpuManagerPolicy: static인 노드에서는 modelserver가 전용 CPU를 받으므로 throttle이 발생하지 않습니다. 모델별 CPU 값은 그 모델 레시피의 values 파일을 사용하세요(차트 준비 및 기본 구성 참고).

노드별 하드웨어 수량은 하드웨어를 참고하세요.

1
2

kubectl get nodes -o json | jq -r '.items[]
  | "\(.metadata.name)\t\(.status.allocatable.memory)"'