As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Inferir falhas na instalação do operador por meio do console de SageMaker IA
<a name="sagemaker-hyperpod-model-deployment-ts-console-cfn-failures"></a>

**Visão geral:** ao instalar o operador de inferência por meio do console de SageMaker IA usando a instalação rápida ou a instalação personalizada, as CloudFormation pilhas subjacentes podem falhar devido a vários problemas. Esta seção aborda cenários de falha comuns e suas resoluções.

## Falha na instalação do complemento do operador de inferência por meio da instalação rápida ou personalizada
<a name="sagemaker-hyperpod-model-deployment-ts-console-cfn-stack-failed"></a>

**Problema:** a criação do HyperPod cluster é concluída com êxito, mas a instalação do complemento do operador de inferência falha.

**Causas comuns:**
+ Os limites de capacidade do pod foram excedidos nos nós do cluster. A instalação do operador de inferência requer um mínimo de 13 pods. O tipo mínimo de instância recomendado é`ml.c5.4xlarge`.
+ Problemas de permissão do IAM
+ Restrições de cota de recursos
+ Problemas de configuração de rede ou VPC

### Sintomas e diagnóstico
<a name="sagemaker-hyperpod-model-deployment-ts-console-cfn-symptoms"></a>

**Sintomas:**
+ O complemento do operador de inferência mostra o status CREATE\$1FAILED ou DEGRADED no console
+ CloudFormation a pilha associada ao complemento está no estado CREATE\$1FAILED
+ O progresso da instalação é interrompido ou mostra mensagens de erro

**Etapas de diagnóstico:**

1. Verifique o status do complemento do operador de inferência:

   ```
   aws eks describe-addon \
       --cluster-name $EKS_CLUSTER_NAME \
       --addon-name amazon-sagemaker-hyperpod-inference \
       --region $REGION \
       --query "addon.{Status:status,Health:health,Issues:issues}" \
       --output json
   ```

1. Verifique se há problemas de limite de pods:

   ```
   # Check current pod count per node
   kubectl get nodes -o json | jq '.items[] | {name: .metadata.name, allocatable: .status.allocatable.pods, capacity: .status.capacity.pods}'
   
   # Check pods running on each node
   kubectl get pods --all-namespaces -o wide | awk '{print $8}' | sort | uniq -c
   
   # Check for pod evictions or failures
   kubectl get events --all-namespaces --sort-by='.lastTimestamp' | grep -i "pod\|limit\|quota"
   ```

1. Verifique o status da CloudFormation pilha (se estiver usando a instalação do console):

   ```
   # List CloudFormation stacks related to the cluster
   aws cloudformation list-stacks \
       --region $REGION \
       --query "StackSummaries[?contains(StackName, '$EKS_CLUSTER_NAME') && StackStatus=='CREATE_FAILED'].{Name:StackName,Status:StackStatus,Reason:StackStatusReason}" \
       --output table
   
   # Get detailed stack events
   aws cloudformation describe-stack-events \
       --stack-name <stack-name> \
       --region $REGION \
       --query "StackEvents[?ResourceStatus=='CREATE_FAILED']" \
       --output table
   ```

### Resolução
<a name="sagemaker-hyperpod-model-deployment-ts-console-cfn-resolution"></a>

Para resolver a falha na instalação, salve a configuração atual, exclua o complemento com falha, corrija o problema subjacente e reinstale o operador de inferência por meio do console de SageMaker IA (recomendado) ou da CLI. AWS 

**Etapa 1: Salvar a configuração atual**
+ Extraia e salve a configuração do complemento antes da exclusão:

  ```
  # Save the current configuration
  aws eks describe-addon \
      --cluster-name $EKS_CLUSTER_NAME \
      --addon-name amazon-sagemaker-hyperpod-inference \
      --region $REGION \
      --query 'addon.configurationValues' \
      --output text > addon-config-backup.json
  
  # Verify the configuration was saved
  cat addon-config-backup.json
  
  # Pretty print for readability
  cat addon-config-backup.json | jq '.'
  ```

**Etapa 2: excluir o complemento com falha**
+ Exclua o complemento do operador de inferência:

  ```
  aws eks delete-addon \
      --cluster-name $EKS_CLUSTER_NAME \
      --addon-name amazon-sagemaker-hyperpod-inference \
      --region $REGION
  
  # Wait for deletion to complete
  echo "Waiting for add-on deletion..."
  aws eks wait addon-deleted \
      --cluster-name $EKS_CLUSTER_NAME \
      --addon-name amazon-sagemaker-hyperpod-inference \
      --region $REGION 2>/dev/null || sleep 60
  ```

**Etapa 3: corrigir o problema subjacente**

Escolha a resolução apropriada com base na causa da falha:

Se o problema for que o limite de pods foi excedido:

```
# The inference operator requires a minimum of 13 pods.
# The minimum recommended instance type is ml.c5.4xlarge.
#
# Option 1: Add instance group with higher pod capacity
# Different instance types support different maximum pod counts
# For example: m5.large (29 pods), m5.xlarge (58 pods), m5.2xlarge (58 pods)
aws sagemaker update-cluster \
    --cluster-name $HYPERPOD_CLUSTER_NAME \
    --region $REGION \
    --instance-groups '[{"InstanceGroupName":"worker-group-2","InstanceType":"ml.m5.xlarge","InstanceCount":2}]'

# Option 2: Scale existing node group to add more nodes
aws eks update-nodegroup-config \
    --cluster-name $EKS_CLUSTER_NAME \
    --nodegroup-name <nodegroup-name> \
    --scaling-config minSize=2,maxSize=10,desiredSize=5 \
    --region $REGION

# Option 3: Clean up unused pods
kubectl delete pods --field-selector status.phase=Failed --all-namespaces
kubectl delete pods --field-selector status.phase=Succeeded --all-namespaces
```

**Etapa 4: reinstalar o operador de inferência**

Depois de corrigir o problema subjacente, reinstale o operador de inferência usando um dos seguintes métodos:
+ **SageMaker Console de IA com instalação personalizada (recomendado):** reutilize as funções do IAM e o bucket TLS existentes da sua instalação anterior. Para obter as etapas, consulte [Método 1: instalar o complemento de HyperPod inferência por meio do console de SageMaker IA (recomendado)](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui).
+ **AWS CLI com configuração salva: use a configuração** da qual você fez backup na Etapa 1 para reinstalar o complemento. Para ver as etapas completas de instalação da CLI, consulte. [Método 2: Instalando o operador de inferência usando a CLI AWS](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-addon)

  ```
  aws eks create-addon \
      --cluster-name $EKS_CLUSTER_NAME \
      --addon-name amazon-sagemaker-hyperpod-inference \
      --addon-version v1.0.0-eksbuild.1 \
      --configuration-values file://addon-config-backup.json \
      --region $REGION
  ```
+ **SageMaker Console de IA com instalação rápida:** cria automaticamente novas funções do IAM, bucket TLS e complementos de dependência. Para obter as etapas, consulte [Método 1: instalar o complemento de HyperPod inferência por meio do console de SageMaker IA (recomendado)](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui).

**Etapa 5: verificar se a instalação foi bem-sucedida**

```
# Check add-on status
aws eks describe-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name amazon-sagemaker-hyperpod-inference \
    --region $REGION \
    --query "addon.{Status:status,Health:health}" \
    --output table

# Verify pods are running
kubectl get pods -n hyperpod-inference-system

# Check operator logs
kubectl logs -n hyperpod-inference-system deployment/hyperpod-inference-controller-manager --tail=50
```

## A instalação do Cert-manager falhou devido ao webhook Kueue não estar pronto
<a name="sagemaker-hyperpod-model-deployment-ts-console-kueue-webhook-race"></a>

**Problema:** A instalação do complemento cert-manager falha com um erro de webhook porque o serviço de webhook do Task Governance (Kueue) não tem endpoints disponíveis. Essa é uma condição de corrida que ocorre quando o cert-manager tenta criar recursos antes que os pods de webhook do Task Governance estejam totalmente em execução. Isso pode acontecer quando o complemento Task Governance está sendo instalado junto com o operador Inference durante a criação do cluster.

### Sintomas e diagnóstico
<a name="sagemaker-hyperpod-model-deployment-ts-console-kueue-symptoms"></a>

**Mensagem de erro:**

```
AdmissionRequestDenied
Internal error occurred: failed calling webhook "mdeployment.kb.io": failed to call webhook: 
Post "https://kueue-webhook-service.kueue-system.svc:443/mutate-apps-v1-deployment?timeout=10s": 
no endpoints available for service "kueue-webhook-service"
```

**Causa raiz:**
+ O complemento Task Governance instala e registra um webhook mutante que intercepta todas as criações de implantação
+ O complemento Cert-Manager tenta criar recursos de implantação antes que os pods de webhook do Task Governance estejam prontos
+ O controle de admissão do Kubernetes chama o webhook de Governança de Tarefas, mas ele não tem endpoints (os pods ainda não estão em execução)

**Etapa de diagnóstico:**

1. Verifique o status do complemento cert-manager:

   ```
   aws eks describe-addon \
       --cluster-name $EKS_CLUSTER_NAME \
       --addon-name cert-manager \
       --region $REGION \
       --query "addon.{Status:status,Health:health,Issues:issues}" \
       --output json
   ```

### Resolução
<a name="sagemaker-hyperpod-model-deployment-ts-console-kueue-resolution"></a>

**Solução: exclua e reinstale o cert-manager**

O webhook de Governança de Tarefas fica pronto em 60 segundos. Basta excluir e reinstalar o complemento cert-manager:

1. Exclua o complemento cert-manager com falha:

   ```
   aws eks delete-addon \
       --cluster-name $EKS_CLUSTER_NAME \
       --addon-name cert-manager \
       --region $REGION
   ```

1. Aguarde de 30 a 60 segundos para que o webhook de Governança de Tarefas fique pronto e reinstale o complemento cert-manager:

   ```
   sleep 60
   
   aws eks create-addon \
       --cluster-name $EKS_CLUSTER_NAME \
       --addon-name cert-manager \
       --region $REGION
   ```