Diagnosticar o estado do gateway Add-on problemas de instalação InferenceGatewayConfig não está se tornando pronto Per-scheduler fracassos O Scheduler RolloutState está degradado Endpoint obsoleto após a reinicialização de um pod modelo A autenticação JWT retorna 401 ou 403 Métricas ausentes nos painéis Falhas na solicitação Seleção de endpoints de depuração Ciclo de vida e limpeza Coletar registros

Guia de solução de problemas do Inference Gateway

Visão geral: O HyperPod Inference Gateway roteia o tráfego por meio de três camadas: o Body-Based roteador (BBR), o gateway com HTTPRoute e o seletor de endpoint (EPP). A configuração incorreta em qualquer camada pode resultar em solicitações fracassadas, tráfego chegando ao modelo errado ou carga desigual nos pods que servem o modelo. Esta seção aborda problemas com o gateway, o BBR, o gateway eHTTPRoute,InferencePool, e o EPP, e quaisquer problemas decorrentes deles.

Diagnosticar o estado do gateway

Use os comandos a seguir para inspecionar o gateway e os recursos que ele gerencia.

Liste todos os InferenceGatewayConfig recursos em namespaces:


kubectl get inferencegatewayconfig -A

Mostre mensagens detalhadas de status, estado de lançamento por agendador e condição para um gateway específico:


kubectl describe inferencegatewayconfig <name> -n <namespace>

Verifique o controlador do gateway e os pods Body-Based do roteador:


kubectl get pods -n hyperpod-inference-system

Verifique os recursos de roteamento downstream gerados pelo controlador:


kubectl get httproute,inferencepool,securitypolicy -A

Inspecione status.conditions o de cada agendador rolloutState (Pending, ProgressingAvailable, ouDegraded). Os motivos de falha acionáveis estão na mensagem de condição correspondente.

Add-on problemas de instalação

Problema: os recursos do gateway estão ausentes ou eles não GatewayClass são aceitos após a instalação do complemento HyperPod Inference Amazon EKS.

Sintomas e resolução: kubectl get gatewayclass inference-gateway retorna NotFound ou mostra o recursoACCEPTED=False. Isso indica que o complemento não está instalado ou que a instalação não foi concluída. Reinstale ou atualize o complemento:


aws eks update-addon --cluster-name $CLUSTER --region $REGION \
  --addon-name amazon-sagemaker-hyperpod-inference \
  --resolve-conflicts OVERWRITE

Em seguida, confirme se o controlador do gateway está em execução:


kubectl rollout status deploy/inference-gateway-controller \
  -n hyperpod-inference-system --timeout=150s

InferenceGatewayConfig não está se tornando pronto

Problema: Um InferenceGatewayConfig é criado, mas seu status.conditions show Accepted=False orReady=False, ou the kubectl apply é totalmente rejeitado pela validação.

Sintomas e resolução:

kubectl applyfalha combbr must be enabled when more than one scheduler is defined. O Body-Based roteador é necessário sempre que mais de um agendador é definido. Defina spec.bbr.enabled como true.
kubectl applyfalha commodelName must be unique across schedulers. Dois programadores declaram o mesmomodelName. Renomeie um para que cada agendador tenha um diferente. modelName
Accepted=False,Reason=InvalidLoraAdapters. Um nome de adaptador LoRa declarado em spec.schedulers[].loraAdapters é uma duplicata entre os agendadores ou colide com o de um agendador. modelName Inspecione a mensagem de condição em busca do nome ofensivo:
```
kubectl describe inferencegatewayconfig <name> -n <namespace>
```
Accepted=False,Reason=ResourceNamingViolation. O nome concatenado <config-name>-<scheduler-name> excede o limite de 63 caracteres do rótulo do Kubernetes. Reduza o nome da configuração ou do agendador.
Ready=False,Reason=GatewayNotProgrammed. O gateway ainda não provisionou o balanceador de carga. Inspecione o gateway principal:
```
kubectl get gateway -n hyperpod-inference-system
kubectl describe gateway <name> -n hyperpod-inference-system
```
AdmissionBlocked=True,Reason=WebhookDenied. Um webhook de admissão de cluster está rejeitando o pod do gateway. A mensagem de condição nomeia o webhook ofensivo. Remova ou corrija o webhook e reinicie a implantação do gateway para que o pod seja recriado imediatamente. O nome da implantação é gerado, então consulte-o primeiro:
```
kubectl -n hyperpod-inference-system get deploy \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
```
Em seguida, reinicie-o:
```
kubectl -n hyperpod-inference-system rollout restart deploy/<gateway-deployment>
```

Per-scheduler fracassos

Problema: A condição de um agendador específico (BackendsReady,LoraSupported, ouPoolReady) indica que o agendador não está totalmente pronto.

Sintomas e resolução:

BackendsReady=False, Reason=NoModelPods ouReason=NoReadyModelPods. Nenhum pods coincide ou spec.schedulers[].modelSelector os pods correspondentes ainda não estão prontos. Compare os rótulos nos pods que servem o modelo com o seletor do agendador:
```
kubectl get pods -n <namespace> --show-labels
```
Implante os pods que servem o modelo e espere que estejam prontos antes de aplicar o. InferenceGatewayConfig
BackendsReady=False,Reason=InvalidModelSelector. A parte matchExpressions inferior matchLabels ou inferior modelSelector está malformada. Corrija o seletor na configuração.
LoraSupported=False,Reason=ModelServerLoraDisabled. O servidor modelo que suporta esse agendador não foi iniciado com o suporte LoRa ativado. Ative o sinalizador equivalente no servidor do modelo (por exemplo, --enable-lora para vLLM) e reinicie os pods do modelo.
PoolReady=False, Reason=NotFound ouReason=NotAccepted. O InferencePool ou seus HTTPRoute ainda não foram reconciliados ou aceitos pelo gateway. Inspecione ambos:
```
kubectl get inferencepool,httproute -n <namespace>
```
Se algum deles ainda estiver ausente alguns minutos após a aplicação da configuração, descreva o Gateway principal para verificar se há erros de admissão:
```
kubectl describe gateway -n hyperpod-inference-system
```

O Scheduler RolloutState está degradado

Problema: A implantação do Endpoint Picker para um agendador está travada e não se torna disponível.

Sintomas e resolução: A EPPReady condição no agendador carrega o motivo acionável. As causas comuns incluem:

A imagem do contêiner não pode ser extraída.
Os pods estão em loop de falha.
O contêiner tem um erro de configuração, como uma variável de ambiente inválida, montagem de volume ou referência secreta.
A implantação excedeu seu prazo de progresso.

Use os comandos a seguir para identificar o agendador com falha e inspecionar sua implantação:


# List the schedulers reporting Degraded
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -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 <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

Endpoint obsoleto após a reinicialização de um pod modelo

Problema: depois que um pod modelo é excluído e um pod substituto fica pronto, o Endpoint Picker continua roteando para o endereço IP do pod excluído. As solicitações retornam HTTP 503 ou a conexão é recusada, e a condição não se recupera sozinha.

Resolução: adicione uma sonda de prontidão ao pod modelo para que o Kubernetes marque o pod NotReady antes que seu IP seja removido do pool e anuncie o pod substituto somente quando ele estiver atendendo totalmente ao tráfego. portDefina para o endpoint de integridade do agendador targetPort e path do seu servidor modelo:


readinessProbe:
  httpGet:
    path: /health
    port: 8000

Solução alternativa: se você não conseguir reimplantar o pod modelo imediatamente, reinicie o Seletor de Endpoint do agendador para forçá-lo a reconstruir sua lista de endpoints a partir do conjunto de pod atual:


kubectl rollout restart deploy -n <namespace> \
  -l inference.sagemaker.aws.amazon.com/scheduler=<scheduler-name>

A autenticação JWT retorna 401 ou 403

Problema: spec.auth.jwt está configurado e as solicitações são rejeitadas antes de chegarem a um modelo, ou o gateway nunca fica pronto depois que a autenticação JWT é ativada.

Sintomas e resolução:

HTTP 401. O token está ausente, expirou, está malformado ou sua iss declaração não corresponde ao provedor configurado. Confirme se o cliente envia um Authorization: Bearer <token> cabeçalho e decodifique o JWT para comparar sua iss reivindicação. spec.auth.jwt.provider.issuer
HTTP 403. A validação da assinatura falhou ou o token corresponde aud ou requiredClaims não à configuração do provedor. Inspecione a configuração do provedor e confirme o token aud e todas as entradas requiredClaims correspondentes:
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.auth.jwt.provider}'
```
O gateway nunca fica pronto com o JWT ativado. Um gerado não SecurityPolicy é aceito pelo gateway. Inspecione os SecurityPolicy recursos pelo motivo da falha:
```
kubectl get securitypolicy -A
kubectl describe securitypolicy <name> -n <namespace>
```
Uma causa comum spec.auth.jwt.provider.remoteJWKS.uri é que ela não pode ser acessada pelo gateway. Confirme se o URI resolve e retorna um documento JWKS válido.

Métricas ausentes nos painéis

Problema: as métricas do Endpoint Picker ou do Body-Based Router não aparecem em seu painel de monitoramento.

Sintomas e resolução: a coleta de métricas é ativada por padrão, então o sidecar OpenTelemetry Collector normalmente está presente. Confirme se o sidecar está sendo executado nos dois tipos de pod e se as métricas foram explicitamente desativadas.

Verifique o sidecar nos pods Body-Based do roteador:


kubectl -n hyperpod-inference-system get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

Verifique o sidecar nos pods do Endpoint Picker:


kubectl -n <namespace> get pods \
  -o jsonpath='{.items[*].spec.containers[*].name}' | tr ' ' '\n' | grep otel

Verifique se as métricas foram explicitamente desativadas:


kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.observability.metrics.enabled}'

A saída vazia do último comando significa que o campo não está definido e as métricas estão ativadas. Somente uma opção explícita false desativa o sidecar. Se o valor forfalse, defina-o como true ou remova o campo, e o controlador injeta o sidecar na próxima reconciliação.

Falhas na solicitação

Problema: O gateway está pronto, mas as solicitações de inferência falham.

Sintomas e resolução:

HTTP 404 para um modelo conhecido. O model valor no corpo da solicitação não corresponde exatamente ao de nenhum agendadormodelName, ou o modelo solicitado é servido por meio de um adaptador LoRa que não está declarado em. spec.schedulers[].loraAdapters Se nenhum agendador corresponder ao modelo solicitado e não spec.bbr.defaultBackend estiver definido, o gateway retornará 404. Verifique os nomes dos modelos e adaptadores configurados:
```
kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].modelName}'

kubectl get inferencegatewayconfig <name> -n <namespace> \
  -o jsonpath='{.spec.schedulers[*].loraAdapters}'
```
As solicitações são suspensas e, em seguida, expiram. Model-serving os pods ainda estão carregando pesos do modelo ou não InferencePool têm endpoints prontos. Aguarde até que os pods do modelo estejam prontos antes de invocar o endpoint do gateway. Use os modelSelector rótulos do seu agendador InferenceGatewayConfig como seletor:
```
kubectl get pods -n <namespace> -l <key>=<value>
kubectl logs <pod> -n <namespace>
```

Seleção de endpoints de depuração

Problema: o tráfego é distorcido para um pequeno número de modelos de pods ou uma solicitação LoRa é roteada para um pod que não hospeda o adaptador.

Resolução: aumente temporariamente a verbosidade do log do Endpoint Picker para inspecionar suas decisões de pontuação. Defina logLevel no agendador:


spec:
  schedulers:
    - name: <scheduler-name>
      logLevel: 4

Significados em nível de registro:

1- Solicite eventos do ciclo de vida.
2- Padrão. Advertências e rejeições de admissão.
3- Resumos selecionados do endpoint e por pontuador.
4- Per-endpoint, pontuações por marcador e totais ponderados.
5- Protocol-level traço (detalhado).

Inspecione os registros do Endpoint Picker:


kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp --tail=200 -f

Retorne logLevel ao padrão quando a investigação for concluída para evitar um volume excessivo de registros.

Ciclo de vida e limpeza

Problema: desinstalar ou atualizar o complemento HyperPod Inference Amazon EKS deixa os recursos órfãos no cluster ou bloqueia uma instalação subsequente.

Resolução: sempre exclua todos os InferenceGatewayConfig recursos antes de desinstalar ou atualizar o complemento. A desinstalação do complemento enquanto um ainda InferenceGatewayConfig está presente remove o controlador que possui os finalizadores do recurso, o que deixa esses recursos presos. Terminating


kubectl delete inferencegatewayconfig --all -A
kubectl get inferencegatewayconfig -A

Confirme se o segundo comando não retorna nenhuma linha antes de continuar com a operação adicional.

Depois de reinstalar o complemento, liste os recursos no namespace do gateway e remova qualquer coisa que não seja mais mapeada para uma versão ativa: InferenceGatewayConfig


kubectl get deploy,svc,httproute,inferencepool,gateway,configmap \
  -n hyperpod-inference-system

Os certificados ACM emitidos pelo controlador não são excluídos por uma desinstalação adicional. Para removê-los, filtre os certificados do ACM na API AWS Resource Groups Tagging pela tag CreatedBy=HyperPodInference e exclua os certificados que você não precisa mais.

Coletar registros

Use os comandos a seguir para recuperar registros de cada componente do gateway:


# Gateway controller
kubectl logs -n hyperpod-inference-system deploy/inference-gateway-controller

# Body-Based Router (deployment name is <gateway-name>-bbr)
kubectl logs -n hyperpod-inference-system deploy/<gateway-name>-bbr -c bbr

# Endpoint Picker for a specific scheduler
kubectl logs -n <namespace> -l app=<scheduler-name>-epp -c epp

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Problemas de implantação de pré-preenchimento e decodificação desagregados (DPD)

Pesos do modelo e armazenamento em cache de imagens