기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # Inference Gateway 문제 해결 가이드 **개요:** HyperPod 추론 게이트웨이는 본문 기반 라우터(BBR),를 사용하는 게이트웨이`HTTPRoute`, 엔드포인트 선택기(EPP)의 세 계층을 통해 트래픽을 라우팅합니다. 계층을 잘못 구성하면 요청 실패, 트래픽이 잘못된 모델에 도달 또는 모델 서비스 포드 간에 고르지 않은 로드가 발생할 수 있습니다. 이 섹션에서는 게이트웨이, BBR, 게이트웨이 및 `HTTPRoute`, `InferencePool`, EPP 관련 문제와 이로 인해 발생하는 모든 문제를 다룹니다. ## 게이트웨이 상태 진단 다음 명령을 사용하여 게이트웨이와 게이트웨이가 관리하는 리소스를 검사합니다. 네임스페이스의 모든 `InferenceGatewayConfig` 리소스를 나열합니다. ``` kubectl get inferencegatewayconfig -A ``` 특정 게이트웨이에 대한 세부 상태, 스케줄러별 롤아웃 상태 및 조건 메시지를 표시합니다. ``` kubectl describe inferencegatewayconfig -n ``` 게이트웨이 컨트롤러와 본문 기반 라우터 포드를 확인합니다. ``` kubectl get pods -n hyperpod-inference-system ``` 컨트롤러에서 생성된 다운스트림 라우팅 리소스를 확인합니다. ``` kubectl get httproute,inferencepool,securitypolicy -A ``` `status.conditions` 및 각 스케줄러의 `rolloutState` (`Pending`, `Available`, 또는 `Degraded`)`Progressing`를 검사합니다. 실행 가능한 실패 이유는 해당 조건 메시지에 있습니다. ## 추가 기능 설치 문제 **문제:** 게이트웨이 리소스가 누락되었거나 HyperPod 추론 Amazon EKS 추가 기능을 설치한 후가 수락`GatewayClass`되지 않습니다. **증상 및 해결 방법:**가를 `kubectl get gatewayclass inference-gateway` 반환`NotFound`하거나 리소스에가 표시됩니다`ACCEPTED=False`. 이는 추가 기능이 설치되지 않았거나 설치가 완료되지 않았음을 나타냅니다. 추가 기능을 다시 설치하거나 업데이트합니다. ``` aws eks update-addon --cluster-name $CLUSTER --region $REGION \ --addon-name amazon-sagemaker-hyperpod-inference \ --resolve-conflicts OVERWRITE ``` 그런 다음 게이트웨이 컨트롤러가 실행 중인지 확인합니다. ``` kubectl rollout status deploy/inference-gateway-controller \ -n hyperpod-inference-system --timeout=150s ``` ## InferenceGatewayConfig가 준비되지 않음 **문제:** `InferenceGatewayConfig`가 생성되었지만 `Accepted=False` 또는가 `status.conditions` 표시`Ready=False`되거나 검증에 의해 `kubectl apply`가 완전히 거부됩니다. **증상 및 해결 방법:** + **`kubectl apply`는에서 실패합니다`bbr must be enabled when more than one scheduler is defined`.** 둘 이상의 스케줄러가 정의될 때마다 본문 기반 라우터가 필요합니다. `spec.bbr.enabled`를 `true`으로 설정합니다. + **`kubectl apply` 에서는가 실패합니다`modelName must be unique across schedulers`.** 두 스케줄러가 동일한를 선언합니다`modelName`. 모든 스케줄러에 고유한이 있도록 이름을 바꿉니다`modelName`. + **`Accepted=False`, `Reason=InvalidLoraAdapters`.** 아래에 선언된 LoRA 어댑터 이름은 스케줄러 간에 `spec.schedulers[].loraAdapters` 중복되거나 스케줄러의와 충돌합니다`modelName`. 조건 메시지에 문제가 되는 이름이 있는지 검사합니다. ``` kubectl describe inferencegatewayconfig -n ``` + **`Accepted=False`, `Reason=ResourceNamingViolation`.** 연결된 이름이 Kubernetes 63자 레이블 제한을 `-` 초과합니다. 구성 또는 스케줄러 이름을 줄입니다. + **`Ready=False`, `Reason=GatewayNotProgrammed`.** 게이트웨이가 아직 로드 밸런서를 프로비저닝하지 않았습니다. 상위 게이트웨이를 검사합니다. ``` kubectl get gateway -n hyperpod-inference-system kubectl describe gateway -n hyperpod-inference-system ``` + **`AdmissionBlocked=True`, `Reason=WebhookDenied`.** 클러스터 승인 웹후크가 게이트웨이 포드를 거부하고 있습니다. 조건 메시지는 불쾌한 웹후크의 이름을 지정합니다. 웹후크를 제거하거나 수정한 다음 포드가 즉시 다시 생성되도록 게이트웨이 배포를 다시 시작합니다. 배포 이름이 생성되므로 먼저 조회합니다. ``` kubectl -n hyperpod-inference-system get deploy \ -l gateway.envoyproxy.io/owning-gateway-name= ``` 그런 다음 다시 시작합니다. ``` kubectl -n hyperpod-inference-system rollout restart deploy/ ``` ## 스케줄러별 실패 **문제:** 특정 스케줄러의 조건(`BackendsReady`, `LoraSupported`또는 `PoolReady`)은 스케줄러가 완전히 준비되지 않았음을 나타냅니다. **증상 및 해결 방법:** + **`BackendsReady=False`, `Reason=NoModelPods` 또는 `Reason=NoReadyModelPods`.** 일치하는 포드가 없거나 `spec.schedulers[].modelSelector`일치하는 포드가 아직 준비되지 않았습니다. 모델 서비스 포드의 레이블을 스케줄러의 선택기와 비교합니다. ``` kubectl get pods -n --show-labels ``` 모델 서비스 포드를 배포하고를 적용하기 전에 준비 상태가 될 때까지 기다립니다`InferenceGatewayConfig`. + **`BackendsReady=False`, `Reason=InvalidModelSelector`.** `matchLabels` `matchExpressions` 이하의 형식`modelSelector`이 잘못되었습니다. 구성에서 선택기를 수정합니다. + **`LoraSupported=False`, `Reason=ModelServerLoraDisabled`.** 이 스케줄러를 지원하는 모델 서버가 LoRA 지원이 활성화된 상태로 시작되지 않았습니다. 모델 서버에서 동일한 플래그(예: vLLM`--enable-lora`의 경우)를 활성화하고 모델 포드를 다시 시작합니다. + **`PoolReady=False`, `Reason=NotFound` 또는 `Reason=NotAccepted`.** 게이트웨이에서 `InferencePool` 또는를 아직 조정하거나 수락`HTTPRoute`하지 않았습니다. 다음 두 가지를 모두 검사합니다. ``` kubectl get inferencepool,httproute -n ``` 구성이 적용된 후 몇 분 후에도 둘 중 하나가 여전히 누락된 경우 상위 게이트웨이를 설명하여 승인 오류를 확인합니다. ``` kubectl describe gateway -n hyperpod-inference-system ``` ## 스케줄러 rolloutState 성능 저하됨 **문제:** 스케줄러에 대한 엔드포인트 선택기 배포가 중단되어 사용 가능 상태가 되지 않습니다. **증상 및 해결 방법:** 스케줄러의 `EPPReady` 조건에는 실행 가능한 이유가 포함됩니다. 일반적인 사용 사례는 다음과 같습니다. + 컨테이너 이미지는 가져올 수 없습니다. + 포드가 충돌 루프 상태입니다. + 컨테이너에 잘못된 환경 변수, 볼륨 마운트 또는 보안 암호 참조와 같은 구성 오류가 있습니다. + 배포가 진행 기한을 초과했습니다. 다음 명령을 사용하여 실패한 스케줄러를 식별하고 배포를 검사합니다. ``` # List the schedulers reporting Degraded kubectl get inferencegatewayconfig -n \ -o jsonpath='{range .status.schedulers[?(@.rolloutState=="Degraded")]}{.name}{"\n"}{end}' # Describe the scheduler's Endpoint Picker Deployment for pod events and container errors kubectl describe deploy -n \ -l inference.sagemaker.aws.amazon.com/scheduler= ``` ## 모델 포드 재시작 후 오래된 엔드포인트 **문제:** 모델 포드가 삭제되고 대체 포드가 준비 상태가 되면 엔드포인트 선택기는 삭제된 포드의 IP 주소로 계속 라우팅됩니다. 요청은 HTTP 503을 반환하거나 연결이 거부되고 조건은 자체적으로 복구되지 않습니다. **해결 방법:** 풀에서 IP가 제거되기 전에 Kubernetes가 포드 NotReady를 표시하고 트래픽이 완전히 제공되면 교체 포드만 알리도록 모델 포드에 준비 프로브를 추가합니다. `port`를 스케줄러의 로 `targetPort` 설정하고 `path`를 모델 서버의 상태 엔드포인트로 설정합니다. ``` readinessProbe: httpGet: path: /health port: 8000 ``` **해결 방법:** 모델 포드를 즉시 재배포할 수 없는 경우 스케줄러의 엔드포인트 선택기를 다시 시작하여 현재 포드 세트에서 엔드포인트 목록을 강제로 다시 빌드합니다. ``` kubectl rollout restart deploy -n \ -l inference.sagemaker.aws.amazon.com/scheduler= ``` ## JWT 인증에서 401 또는 403 반환 **문제:** 모델에 도달하기 전에 `spec.auth.jwt`가 구성되고 요청이 거부되거나 JWT 인증이 활성화된 후 게이트웨이가 준비 상태가 되지 않습니다. **증상 및 해결 방법:** + **HTTP 401.** 토큰이 누락되었거나, 만료되었거나, 형식이 잘못되었거나, `iss` 클레임이 구성된 공급자와 일치하지 않습니다. 클라이언트가 `Authorization: Bearer ` 헤더를 전송하는지 확인하고 JWT를 디코딩하여 `iss` 클레임을와 비교합니다`spec.auth.jwt.provider.issuer`. + **HTTP 403.** 서명 검증에 실패했거나 토큰의 `aud` 또는 `requiredClaims`가 공급자 구성과 일치하지 않습니다. 공급자 구성을 검사하고 토큰`aud`과 `requiredClaims` 일치하는 모든 항목을 확인합니다. ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.auth.jwt.provider}' ``` + **JWT가 활성화된 상태에서는 게이트웨이가 준비 상태가 되지 않습니다.** 생성된 `SecurityPolicy`는 게이트웨이에서 수락되지 않습니다. SecurityPolicy 리소스에서 실패 이유를 검사합니다. ``` kubectl get securitypolicy -A kubectl describe securitypolicy -n ``` 게이트웨이에서 연결할 수 `spec.auth.jwt.provider.remoteJWKS.uri` 없는 것이 일반적인 원인입니다. URI가 유효한 JWKS 문서를 확인하고 반환하는지 확인합니다. ## 대시보드에서 누락된 지표 **문제:** 엔드포인트 선택기 또는 본문 기반 라우터 지표가 모니터링 대시보드에 표시되지 않습니다. **증상 및 해결 방법:** 지표 수집은 기본적으로 활성화되어 있으므로 일반적으로 OpenTelemetry Collector 사이드카가 있습니다. 사이드카가 두 포드 유형 모두에서 실행 중인지, 지표가 명시적으로 비활성화되었는지 확인합니다. 바디 기반 라우터 포드에서 사이드카를 확인합니다. ``` kubectl -n hyperpod-inference-system get pods \ -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel ``` 엔드포인트 선택기 포드에서 사이드카를 확인합니다. ``` kubectl -n get pods \ -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel ``` 지표가 명시적으로 비활성화되었는지 확인합니다. ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.observability.metrics.enabled}' ``` 마지막 명령의 빈 출력은 필드가 설정되지 않았고 지표가 활성화되었음을 의미합니다. 명시적 만 사이드카를 `false` 비활성화합니다. 값이 인 경우 필드를 로 `false`설정`true`하거나 제거하면 컨트롤러가 다음 조정 시 사이드카를 주입합니다. ## 요청 실패 **문제:** 게이트웨이가 준비되었지만 추론 요청이 실패합니다. **증상 및 해결 방법:** + **알려진 모델에 대한 HTTP 404입니다.** 요청 본문의 `model` 값이 스케줄러의와 정확히 일치하지 않거나 `modelName`요청된 모델이에서 선언되지 않은 LoRA 어댑터를 통해 제공됩니다`spec.schedulers[].loraAdapters`. 요청된 모델과 일치하는 스케줄러가 없고 설정되지 않은 경우 게이트웨이`spec.bbr.defaultBackend`는 404를 반환합니다. 구성된 모델 이름과 어댑터 이름을 확인합니다. ``` kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.schedulers[*].modelName}' kubectl get inferencegatewayconfig -n \ -o jsonpath='{.spec.schedulers[*].loraAdapters}' ``` + **요청이 중단된 다음 시간 초과됩니다.** 모델 서비스 포드가 아직 모델 가중치를 로드하고 있거나에 준비된 엔드포인트`InferencePool`가 없습니다. 게이트웨이 엔드포인트를 호출하기 전에 모델 포드가 준비 상태가 될 때까지 기다립니다. 의 스케줄러 `modelSelector` 레이블을 선택기`InferenceGatewayConfig`로 사용합니다. ``` kubectl get pods -n -l = kubectl logs -n ``` ## 엔드포인트 선택 디버깅 **문제:** 소수의 모델 포드에 대한 트래픽 스큐 또는 어댑터를 호스팅하지 않는 포드로 LoRA 요청이 라우팅됩니다. **해결 방법:** 엔드포인트 선택기의 로그 세부 정보를 일시적으로 높여 점수 결정 사항을 검사합니다. 스케줄러`logLevel`에서를 설정합니다. ``` spec: schedulers: - name: logLevel: 4 ``` 로그 수준 의미: + `1` - 수명 주기 이벤트를 요청합니다. + `2` - 기본값입니다. 경고 및 승인 거부. + `3` - 선택한 엔드포인트 및 점수별 요약. + `4` - 엔드포인트별, 점수별 점수 및 가중치 기반 합계. + `5` - 프로토콜 수준 추적(구체적). 엔드포인트 선택기 로그를 검사합니다. ``` kubectl logs -n -l app=-epp -c epp --tail=200 -f ``` 초과 로그 볼륨`logLevel`을 방지하기 위해 조사가 완료되면 기본값으로 돌아갑니다. ## 수명 주기 및 정리 **문제:** HyperPod Inference Amazon EKS 추가 기능을 제거 또는 업그레이드하면 분리된 리소스가 클러스터에 남거나 후속 설치가 차단됩니다. **해결 방법:** 추가 기능을 제거하거나 업그레이드하기 전에 항상 모든 `InferenceGatewayConfig` 리소스를 삭제합니다. `InferenceGatewayConfig`가 있는 동안 추가 기능을 제거하면 리소스의 최종 사용자를 소유한 컨트롤러가 제거되어 해당 리소스가에 멈춰 있습니다`Terminating`. ``` kubectl delete inferencegatewayconfig --all -A kubectl get inferencegatewayconfig -A ``` 추가 기능 작업을 계속하기 전에 두 번째 명령이 행을 반환하지 않는지 확인합니다. 추가 기능을 다시 설치한 후 게이트웨이 네임스페이스에 리소스를 나열하고 더 이상 라이브에 매핑되지 않는 모든 항목을 제거합니다`InferenceGatewayConfig`. ``` kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \ -n hyperpod-inference-system ``` 컨트롤러에서 발급한 ACM 인증서는 추가 기능 제거로 삭제되지 않습니다. 이를 제거하려면 AWS Resource Groups Tagging API에서 태그를 기준으로 ACM 인증서를 필터링`CreatedBy=HyperPodInference`하고 더 이상 필요하지 않은 인증서를 삭제합니다. ## 로그 수집 다음 명령을 사용하여 각 게이트웨이 구성 요소에서 로그를 검색합니다. ``` # Gateway controller kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller # Body-Based Router (deployment name is -bbr) kubectl logs -n hyperpod-inference-system deploy/-bbr -c bbr # Endpoint Picker for a specific scheduler kubectl logs -n -l app=-epp -c epp ```