클러스터 기반 구성¶

목표: 서빙 스택을 설치할 클러스터 기반 구성과 스택이 사용할 Secret 및 모델 저장소를 준비합니다.

Gateway API 및 Gateway API Inference Extension CRD¶

Kubernetes Gateway API CustomResourceDefinition(CRD)와 InferencePool을 정의하는 Kubernetes Gateway API Inference Extension(GAIE) CRD를 설치하세요. Gateway API CRD와 GAIE CRD가 없으면 차트 설치가 no matches for kind ... 오류와 함께 즉시 실패합니다.

1
2
3
4

GATEWAY_API_VERSION=v1.5.1
GAIE_VERSION=v1.5.0
kubectl apply -f "https://github.com/kubernetes-sigs/gateway-api/releases/download/${GATEWAY_API_VERSION}/standard-install.yaml"
kubectl apply -f "https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/${GAIE_VERSION}/v1-manifests.yaml"

GatewayClass provider¶

레퍼런스 구성은 GatewayClass provider로 Istio를 사용합니다. llm-d의 Istio 가이드에 따라 GAIE를 활성화해 Istio를 설치하세요. Target Configuration 검증에서는 Istio 1.30.0을 사용했습니다.

차트는 기본으로 GatewayClass istio를 사용합니다. 따라서 Istio를 사용하면 차트 values에서 GatewayClass를 따로 지정하지 않아도 됩니다.

provider가 없거나 Istio에서 GAIE가 활성화되지 않아도 차트 설치는 성공합니다. 대신 다음 상태가 나타납니다.

Endpoint Picker(EPP), InferencePool, HTTPRoute는 helm install을 실행할 때 차트가 함께 생성합니다. 따라서 이 문서에서는 CRD와 GatewayClass provider만 준비합니다.

agentgateway(Unverified): GAIE 지원을 활성화해 agentgateway를 설치하고, 차트에 examples/gateway-agentgateway.yaml을 -f로 적용하세요.

Secret 및 모델 저장소¶

디바이스 할당에서 생성한 네임스페이스에 Image Pull Secret, HF 토큰 Secret, 모델 PersistentVolumeClaim(PVC)를 생성하세요. 차트는 Image Pull Secret, HF 토큰 Secret, 모델 PVC를 만들지 않고 이름으로 참조합니다. Image Pull Secret, HF 토큰 Secret, 모델 PVC가 없을 때의 증상은 장애 대응 › 증상별 진단을 참고하세요.

1
2
3
4
5
6

# Image Pull Secret을 생성합니다.
kubectl -n <ns> create secret docker-registry <pull-secret-name> \
  --docker-server=<registry> --docker-username=<user> --docker-password=<token>

# HF 토큰 Secret을 생성합니다. EPP가 HF 토큰 Secret을 llm-d-hf-token 이름으로 참조합니다.
kubectl -n <ns> create secret generic llm-d-hf-token --from-literal=HF_TOKEN=<token>

HF 토큰 Secret의 이름을 바꾸려면 llm-d-router-gateway.router.epp.env 전체를 덮어쓰세요. llm-d-router-gateway.router.epp.env 배열에 Secret 이름이 들어 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 모델 저장소: 가중치를 보관할 PVC
kubectl -n <ns> apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: model-cache
spec:
  accessModes: ["ReadWriteMany"]
  storageClassName: <sc-name>
  resources:
    requests:
      storage: 250Gi
EOF

PVC 예제의 250Gi는 MiniMax-M2.7 가중치 크기(약 234 GB)에 여유 공간을 더한 값입니다. 볼륨별 용량 및 accessModes 요구 사항은 볼륨을 참고하세요.

모델 가중치를 미리 적재하세요. 차트는 모델 가중치가 모델 볼륨에 이미 있다고 가정합니다. model-cache PVC를 임시 Pod에 마운트하고, 볼륨의 .cache/huggingface 아래에 HuggingFace 캐시 구조로 모델을 다운로드하세요. 차트는 HF_HOME을 <mountPath>/.cache/huggingface로 설정합니다. 다운로드 명령은 HuggingFace CLI 가이드를 참고하세요.

modelserver 컨테이너가 볼륨의 모델 디렉터리 전체를 읽을 수 있게 하세요. 기본 실행 모드인 non-root에서 차트는 modelserver Pod에 runAsUser: 2000, runAsGroup: 0, fsGroup: 2000을 설정합니다. modelserver 컨테이너가 가중치를 읽지 못하면 엔진이 가중치를 로드하지 못해 시작에 실패합니다.

클러스터 확인 및 주요 설정¶

다음 명령으로 클러스터 기반 구성이 준비되었는지 확인하세요.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Kubernetes 버전과 DRA API를 확인합니다.
kubectl version
kubectl get --raw /apis/resource.k8s.io/v1 >/dev/null && echo "DRA ok"

# Kubernetes Gateway API CRD / Kubernetes GAIE CRD / provider를 확인합니다.
kubectl get crd gatewayclasses.gateway.networking.k8s.io
kubectl get crd inferencepools.inference.networking.k8s.io
kubectl get gatewayclass

# 워크로드 리소스를 확인합니다.
kubectl -n <ns> get secret,pvc
kubectl get storageclass

모든 확인 명령이 성공하고 DRA ok가 출력되면 클러스터 기반 구성이 준비된 것입니다. 결과가 다르면 다음과 같이 조치하세요.

Image Pull Secret과 모델 PVC의 이름을 다음 차트 values에 지정하세요. storage.model은 기본값이 없으므로 storage.model을 반드시 지정해야 합니다. 네임스페이스는 helm install -n <ns>로 지정합니다.

1
2
3
4
5
6
7
8

imagePullSecrets:
  - <pull-secret-name>
storage:
  model:
    kind: existingClaim
    existingClaim: model-cache
  compileCache:
    storageClass: <sc-name>  # 비워 두면 클러스터 기본 StorageClass를 사용합니다.