HyperPod 推論故障診斷 - Amazon SageMaker AI
由於缺少 CSI 驅動程式，推論附加元件安裝失敗模型部署期間缺少推論自訂資源定義由於缺少 cert-manager，推論附加元件安裝失敗由於缺少 ALB 控制器，推論附加元件安裝失敗由於缺少 KEDA 運算子，推論附加元件安裝失敗憑證下載逾時模型部署停滯在待定狀態模型部署失敗狀態疑難排解檢查模型部署進度VPC ENI 許可問題IAM 信任關係問題缺少 NVIDIA GPU 外掛程式錯誤推論運算子無法啟動

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

HyperPod 推論故障診斷

此疑難排解指南解決了 Amazon SageMaker HyperPod 推論部署和操作期間可能發生的常見問題。這些問題通常涉及 VPC 聯網組態、IAM 許可、Kubernetes 資源管理和運算子連線問題，這些問題可能會阻止成功的模型部署，或導致部署失敗或保持待定狀態。

本故障診斷指南使用以下術語：故障診斷步驟是用於識別和調查問題的診斷程序、解決提供修正已識別問題的特定動作，以及驗證確認解決方案是否正常運作。

快速參考：尋找您的問題

使用以下類別快速找到與您的問題相關的疑難排解區段：

由於缺少 CSI 驅動程式，推論附加元件安裝失敗

問題：推論運算子附加元件建立失敗，因為 EKS 叢集上未安裝所需的 CSI 驅動程式相依性。

症狀和診斷

錯誤訊息：

下列錯誤會出現在附加元件建立日誌或推論運算子日誌中：

S3 CSI driver not installed (missing CSIDriver s3.csi.aws.com). 
Please install the required CSI driver and see the troubleshooting guide for more information.

FSx CSI driver not installed (missing CSIDriver fsx.csi.aws.com). 
Please install the required CSI driver and see the troubleshooting guide for more information.

診斷步驟：

  1. 檢查是否已安裝 CSI 驅動程式：

    # Check for S3 CSI driver
kubectl get csidriver s3.csi.aws.com
kubectl get pods -n kube-system | grep mountpoint

# Check for FSx CSI driver  
kubectl get csidriver fsx.csi.aws.com
kubectl get pods -n kube-system | grep fsx

  2. 檢查 EKS 附加元件狀態：

    # List all add-ons
aws eks list-addons --cluster-name $EKS_CLUSTER_NAME --region $REGION

# Check specific CSI driver add-ons
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION 2>/dev/null || echo "S3 CSI driver not installed"
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION 2>/dev/null || echo "FSx CSI driver not installed"

  3. 檢查推論運算子附加元件狀態：

    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

Resolution

步驟 1：安裝遺失的 S3 CSI 驅動程式

  1. 為 S3 CSI 驅動程式建立 IAM 角色 （如果尚未建立）：

    # Set up service account role ARN (from installation steps)
export S3_CSI_ROLE_ARN=$(aws iam get-role --role-name $S3_CSI_ROLE_NAME --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found")
echo "S3 CSI Role ARN: $S3_CSI_ROLE_ARN"

  2. 安裝 S3 CSI 驅動程式附加元件：

    aws eks create-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name aws-mountpoint-s3-csi-driver \
    --addon-version v1.14.1-eksbuild.1 \
    --service-account-role-arn $S3_CSI_ROLE_ARN \
    --region $REGION

  3. 驗證 S3 CSI 驅動程式安裝：

    # Wait for add-on to be active
aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION

# Verify CSI driver is available
kubectl get csidriver s3.csi.aws.com
kubectl get pods -n kube-system | grep mountpoint

步驟 2：安裝缺少的 FSx CSI 驅動程式

  1. 為 FSx CSI 驅動程式建立 IAM 角色 （如果尚未建立）：

    # Set up service account role ARN (from installation steps)
export FSX_CSI_ROLE_ARN=$(aws iam get-role --role-name $FSX_CSI_ROLE_NAME --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found")
echo "FSx CSI Role ARN: $FSX_CSI_ROLE_ARN"

  2. 安裝 FSx CSI 驅動程式附加元件：

    aws eks create-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name aws-fsx-csi-driver \
    --addon-version v1.6.0-eksbuild.1 \
    --service-account-role-arn $FSX_CSI_ROLE_ARN \
    --region $REGION

# Wait for add-on to be active
aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION

# Verify FSx CSI driver is running
kubectl get pods -n kube-system | grep fsx

驗證所有相依性

安裝缺少的相依性後，請先確認它們執行正確，再重試推論運算子安裝：

# Check all required add-ons are active
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-mountpoint-s3-csi-driver --region $REGION
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name aws-fsx-csi-driver --region $REGION
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name metrics-server --region $REGION
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION

# Verify all pods are running
kubectl get pods -n kube-system | grep -E "(mountpoint|fsx|metrics-server)"
kubectl get pods -n cert-manager

模型部署期間缺少推論自訂資源定義

問題：當您嘗試建立模型部署時，缺少自訂資源定義 (CRDs)。此問題會在您之前安裝並刪除推論附加元件，而未清除具有定案器的模型部署時發生。

症狀和診斷

根本原因：

如果您在未先移除所有模型部署的情況下刪除推論附加元件，具有定案器的自訂資源會保留在叢集中。這些最終處理程式必須先完成，您才能刪除 CRDs。附加元件刪除程序不會等待 CRD 刪除完成，這會導致 CRDs保持終止狀態，並防止新的安裝。

診斷此問題

  1. 檢查 CRDs是否存在。

    kubectl get crd | grep inference.sagemaker.aws.amazon.com

  2. 檢查是否有凍結的自訂資源。

    # Check for JumpStartModel resources
kubectl get jumpstartmodels -A

# Check for InferenceEndpointConfig resources
kubectl get inferenceendpointconfigs -A

  3. 檢查停滯資源上的定案者。

    # Example for a specific JumpStartModel
kubectl get jumpstartmodels <model-name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

# Example for a specific InferenceEndpointConfig
kubectl get inferenceendpointconfigs <config-name> -n <namespace> -o jsonpath='{.metadata.finalizers}'

Resolution

從移除推論附加元件時未刪除的所有模型部署手動移除定案器。為每個停滯的自訂資源完成以下步驟。

從 JumpStartModel 資源中移除定案器

  1. 列出所有命名空間的所有 JumpStartModel 資源。

    kubectl get jumpstartmodels -A

  2. 對於每個 JumpStartModel 資源，修補資源以將 metadata.finalizer 設定為空白陣列，以移除最終版本。

    kubectl patch jumpstartmodels <model-name> -n <namespace> -p '{"metadata":{"finalizers":[]}}' --type=merge

    下列範例示範如何修補名為 kv-l1-only 的資源。

    kubectl patch jumpstartmodels kv-l1-only -n default -p '{"metadata":{"finalizers":[]}}' --type=merge

  3. 確認已刪除模型執行個體。

    kubectl get jumpstartmodels -A

    清除所有資源時，您應該會看到下列輸出。

    Error from server (NotFound): Unable to list "inference.sagemaker.aws.amazon.com/v1, Resource=jumpstartmodels": the server could not find the requested resource (get jumpstartmodels.inference.sagemaker.aws.amazon.com)

  4. 確認 JumpStartModel CRD 已移除。

    kubectl get crd | grep jumpstartmodels.inference.sagemaker.aws.amazon.com

    如果成功移除 CRD，此命令不會傳回任何輸出。

從 InferenceEndpointConfig 資源中移除定案者

  1. 列出所有命名空間的所有 InferenceEndpointConfig 資源。

    kubectl get inferenceendpointconfigs -A

  2. 針對每個 InferenceEndpointConfig 資源，移除定稿器。

    kubectl patch inferenceendpointconfigs <config-name> -n <namespace> -p '{"metadata":{"finalizers":[]}}' --type=merge

    下列範例示範如何修補名為 my-inference-config 的資源。

    kubectl patch inferenceendpointconfigs my-inference-config -n default -p '{"metadata":{"finalizers":[]}}' --type=merge

  3. 確認組態執行個體已刪除。

    kubectl get inferenceendpointconfigs -A

    清除所有資源時，您應該會看到下列輸出。

    Error from server (NotFound): Unable to list "inference.sagemaker.aws.amazon.com/v1, Resource=inferenceendpointconfigs": the server could not find the requested resource (get inferenceendpointconfigs.inference.sagemaker.aws.amazon.com)

  4. 確認 InferenceEndpointConfig CRD 已移除。

    kubectl get crd | grep inferenceendpointconfigs.inference.sagemaker.aws.amazon.com

    如果成功移除 CRD，此命令不會傳回任何輸出。

重新安裝推論附加元件

清除所有停滯的資源並確認 CRDs已移除後，請重新安裝推論附加元件。如需詳細資訊，請參閱使用 EKS 附加元件安裝推論運算子。

驗證

  1. 確認已成功安裝推論附加元件。

    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

    狀態應為 ACTIVE，運作狀態應為 HEALTHY。

  2. 確認 CRDs已正確安裝。

    kubectl get crd | grep inference.sagemaker.aws.amazon.com

    您應該會看到輸出中列出的推論相關 CRDs。

  3. 測試建立新的模型部署，以確認問題已解決。

    # Create a test deployment using your preferred method
kubectl apply -f <your-model-deployment.yaml>

預防

為避免此問題，請先完成下列步驟，再解除安裝推論附加元件。

  1. 刪除所有模型部署。

    # Delete all JumpStartModel resources
kubectl delete jumpstartmodels --all -A

# Delete all InferenceEndpointConfig resources
kubectl delete inferenceendpointconfigs --all -A

# Wait for all resources to be fully deleted
kubectl get jumpstartmodels -A
kubectl get inferenceendpointconfigs -A

  2. 確認已刪除所有自訂資源。

  3. 確認所有資源都已清除後，請刪除推論附加元件。

由於缺少 cert-manager，推論附加元件安裝失敗

問題：推論運算子附加元件建立失敗，因為未安裝 cert-manager EKS 附加元件，導致缺少自訂資源定義 (CRDs)。

症狀和診斷

錯誤訊息：

下列錯誤會出現在附加元件建立日誌或推論運算子日誌中：

Missing required CRD: certificaterequests.cert-manager.io. 
The cert-manager add-on is not installed. Please install cert-manager and see the troubleshooting guide for more information.

診斷步驟：

  1. 檢查是否已安裝 cert-manager：

    # Check for cert-manager CRDs
kubectl get crd | grep cert-manager
kubectl get pods -n cert-manager

# Check EKS add-on status
aws eks describe-addon --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION 2>/dev/null || echo "Cert-manager not installed"

  2. 檢查推論運算子附加元件狀態：

    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

Resolution

步驟 1：安裝 cert-manager 附加元件

  1. 安裝 cert-manager EKS 附加元件：

    aws eks create-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name cert-manager \
    --addon-version v1.18.2-eksbuild.2 \
    --region $REGION

  2. 驗證 cert-manager 安裝：

    # Wait for add-on to be active
aws eks wait addon-active --cluster-name $EKS_CLUSTER_NAME --addon-name cert-manager --region $REGION

# Verify cert-manager pods are running
kubectl get pods -n cert-manager

# Verify CRDs are installed
kubectl get crd | grep cert-manager | wc -l
# Expected: Should show multiple cert-manager CRDs

步驟 2：重試推論運算子安裝

  1. 安裝 cert-manager 之後，請重試推論運算子安裝：

    # Delete the failed add-on if it exists
aws eks delete-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name amazon-sagemaker-hyperpod-inference \
    --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation"

# Wait for deletion to complete
sleep 30

# Reinstall the inference operator add-on
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.json \
    --region $REGION

  2. 監控 安裝：

    # Check installation 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 inference operator pods are running
kubectl get pods -n hyperpod-inference-system

由於缺少 ALB 控制器，推論附加元件安裝失敗

問題：推論運算子附加元件建立失敗，因為未安裝或未針對推論附加元件正確設定 AWS Load Balancer控制器。

症狀和診斷

錯誤訊息：

下列錯誤會出現在附加元件建立日誌或推論運算子日誌中：

ALB Controller not installed (missing aws-load-balancer-controller pods). 
Please install the Application Load Balancer Controller and see the troubleshooting guide for more information.

診斷步驟：

  1. 檢查是否已安裝 ALB 控制器：

    # Check for ALB Controller pods
kubectl get pods -n kube-system | grep aws-load-balancer-controller
kubectl get pods -n hyperpod-inference-system | grep aws-load-balancer-controller

# Check ALB Controller service account
kubectl get serviceaccount aws-load-balancer-controller -n kube-system 2>/dev/null || echo "ALB Controller service account not found"
kubectl get serviceaccount aws-load-balancer-controller -n hyperpod-inference-system 2>/dev/null || echo "ALB Controller service account not found in inference namespace"

  2. 檢查推論運算子附加元件組態：

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

Resolution

根據您的設定選擇下列其中一個選項：

選項 1：讓推論附加元件安裝 ALB 控制器 （建議）

  • 請確定已在附加元件組態中建立並正確設定 ALB 角色：

    # Verify ALB role exists
export ALB_ROLE_ARN=$(aws iam get-role --role-name alb-role --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found")
echo "ALB Role ARN: $ALB_ROLE_ARN"

# Update your addon-config.json to enable ALB
cat > addon-config.json << EOF
{
  "executionRoleArn": "$EXECUTION_ROLE_ARN",
  "tlsCertificateS3Bucket": "$BUCKET_NAME",
  "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN",
  "alb": {
    "enabled": true,
    "serviceAccount": {
      "create": true,
      "roleArn": "$ALB_ROLE_ARN"
    }
  },
  "keda": {
    "auth": {
      "aws": {
        "irsa": {
          "roleArn": "$KEDA_ROLE_ARN"
        }
      }
    }
  }
}
EOF

選項 2：使用現有的 ALB 控制器安裝

  • 如果您已安裝 ALB 控制器，請將 附加元件設定為使用現有的安裝：

    # Update your addon-config.json to disable ALB installation
cat > addon-config.json << EOF
{
  "executionRoleArn": "$EXECUTION_ROLE_ARN",
  "tlsCertificateS3Bucket": "$BUCKET_NAME",
  "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN",
  "alb": {
    "enabled": false
  },
  "keda": {
    "auth": {
      "aws": {
        "irsa": {
          "roleArn": "$KEDA_ROLE_ARN"
        }
      }
    }
  }
}
EOF

步驟 3：重試推論運算子安裝

  1. 使用更新的組態重新安裝推論運算子附加元件：

    # Delete the failed add-on if it exists
aws eks delete-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name amazon-sagemaker-hyperpod-inference \
    --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation"

# Wait for deletion to complete
sleep 30

# Reinstall with updated configuration
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.json \
    --region $REGION

  2. 驗證 ALB 控制器是否正常運作：

    # Check ALB Controller pods
kubectl get pods -n hyperpod-inference-system | grep aws-load-balancer-controller
kubectl get pods -n kube-system | grep aws-load-balancer-controller

# Check service account annotations
kubectl describe serviceaccount aws-load-balancer-controller -n hyperpod-inference-system 2>/dev/null
kubectl describe serviceaccount aws-load-balancer-controller -n kube-system 2>/dev/null

由於缺少 KEDA 運算子，推論附加元件安裝失敗

問題：推論運算子附加元件建立失敗，因為未安裝或未針對推論附加元件正確設定 KEDA (Kubernetes Event Driven Autoscaler) 運算子。

症狀和診斷

錯誤訊息：

下列錯誤會出現在附加元件建立日誌或推論運算子日誌中：

KEDA operator not installed (missing keda-operator pods). 
KEDA can be installed separately in any namespace or via the Inference addon.

診斷步驟：

  1. 檢查是否已安裝 KEDA 運算子：

    # Check for KEDA operator pods in common namespaces
kubectl get pods -n keda-system | grep keda-operator 2>/dev/null || echo "KEDA not found in keda-system namespace"
kubectl get pods -n kube-system | grep keda-operator 2>/dev/null || echo "KEDA not found in kube-system namespace"
kubectl get pods -n hyperpod-inference-system | grep keda-operator 2>/dev/null || echo "KEDA not found in inference namespace"

# Check for KEDA CRDs
kubectl get crd | grep keda 2>/dev/null || echo "KEDA CRDs not found"

# Check KEDA service account
kubectl get serviceaccount keda-operator -A 2>/dev/null || echo "KEDA service account not found"

  2. 檢查推論運算子附加元件組態：

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

Resolution

根據您的設定選擇下列其中一個選項：

選項 1：讓推論附加元件安裝 KEDA （建議）

  • 請確定已在附加元件組態中建立並正確設定 KEDA 角色：

    # Verify KEDA role exists
export KEDA_ROLE_ARN=$(aws iam get-role --role-name keda-operator-role --query 'Role.Arn' --output text 2>/dev/null || echo "Role not found")
echo "KEDA Role ARN: $KEDA_ROLE_ARN"

# Update your addon-config.json to enable KEDA
cat > addon-config.json << EOF
{
  "executionRoleArn": "$EXECUTION_ROLE_ARN",
  "tlsCertificateS3Bucket": "$BUCKET_NAME",
  "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN",
  "alb": {
    "serviceAccount": {
      "create": true,
      "roleArn": "$ALB_ROLE_ARN"
    }
  },
  "keda": {
    "enabled": true,
    "auth": {
      "aws": {
        "irsa": {
          "roleArn": "$KEDA_ROLE_ARN"
        }
      }
    }
  }
}
EOF

選項 2：使用現有的 KEDA 安裝

  • 如果您已安裝 KEDA，請將附加元件設定為使用現有的安裝：

    # Update your addon-config.json to disable KEDA installation
cat > addon-config.json << EOF
{
  "executionRoleArn": "$EXECUTION_ROLE_ARN",
  "tlsCertificateS3Bucket": "$BUCKET_NAME",
  "hyperpodClusterArn": "$HYPERPOD_CLUSTER_ARN",
  "alb": {
    "serviceAccount": {
      "create": true,
      "roleArn": "$ALB_ROLE_ARN"
    }
  },
  "keda": {
    "enabled": false
  }
}
EOF

步驟 3：重試推論運算子安裝

  1. 使用更新的組態重新安裝推論運算子附加元件：

    # Delete the failed add-on if it exists
aws eks delete-addon \
    --cluster-name $EKS_CLUSTER_NAME \
    --addon-name amazon-sagemaker-hyperpod-inference \
    --region $REGION 2>/dev/null || echo "Add-on not found, proceeding with installation"

# Wait for deletion to complete
sleep 30

# Reinstall with updated configuration
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.json \
    --region $REGION

  2. 驗證 KEDA 是否正常運作：

    # Check KEDA pods
kubectl get pods -n hyperpod-inference-system | grep keda
kubectl get pods -n kube-system | grep keda
kubectl get pods -n keda-system | grep keda 2>/dev/null

# Check KEDA CRDs
kubectl get crd | grep scaledobjects
kubectl get crd | grep scaledjobs

# Check KEDA service account annotations
kubectl describe serviceaccount keda-operator -n hyperpod-inference-system 2>/dev/null
kubectl describe serviceaccount keda-operator -n kube-system 2>/dev/null
kubectl describe serviceaccount keda-operator -n keda-system 2>/dev/null

憑證下載逾時

部署 SageMaker AI 端點時，建立程序會失敗，因為無法在 VPC 環境中下載憑證授權單位 (CA) 憑證。如需詳細的組態步驟，請參閱 管理員指南。

錯誤訊息：

下列錯誤會出現在 SageMaker AI 端點 CloudWatch 日誌中：

Error downloading CA certificate: Connect timeout on endpoint URL: "https://****.s3.<REGION>.amazonaws.com/****/***.pem"

根本原因：

  • 當推論運算子無法存取 VPC 內 Amazon S3 中的自我簽署憑證時，就會發生此問題

  • Amazon S3 VPC 端點的適當組態對於憑證存取至關重要

解決方法：

  1. 如果您沒有 Amazon S3 VPC 端點：

    • 依照 管理員指南第 5.3 節中的組態建立 Amazon S3 VPC 端點。

  2. 如果您已經有 Amazon S3 VPC 端點：

    • 確定子網路路由表已設定為指向 VPC 端點 （如果使用閘道端點），或介面端點已啟用私有 DNS。

    • Amazon S3 VPC 端點應類似於第 5.3 節端點建立步驟中提到的組態

模型部署停滯在待定狀態

部署模型時，部署會長時間保持「待定」狀態。這表示推論運算子無法在 HyperPod 叢集中啟動模型部署。

受影響的元件：

在正常部署期間，推論運算子應該：

  • 部署模型 Pod

  • 建立負載平衡器

  • 建立 SageMaker AI 端點

故障診斷步驟：

  1. 檢查推論運算子 Pod 狀態：

    kubectl get pods -n hyperpod-inference-system

    預期的輸出範例：

    NAME                                                           READY   STATUS    RESTARTS   AGE
hyperpod-inference-operator-controller-manager-65c49967f5-894fg   1/1     Running   0         6d13h

  2. 檢閱推論運算子日誌，並檢查運算子日誌是否有錯誤訊息：

    kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system

要尋找的內容：

  • 運算子日誌中的錯誤訊息

  • 運算子 Pod 的狀態

  • 任何部署相關的警告或失敗

注意

運作狀態良好的部署應該會在合理的時間內超過「待定」狀態。如果問題仍然存在，請檢閱推論運算子日誌以取得特定錯誤訊息，以判斷根本原因。

模型部署失敗狀態疑難排解

當模型部署進入「失敗」狀態時，故障可能發生在三個元件的其中之一：

  • 模型 Pod 部署

  • 建立負載平衡器

  • SageMaker AI 端點建立

故障診斷步驟：

  1. 檢查推論運算子狀態：

    kubectl get pods -n hyperpod-inference-system

    預期的輸出結果：

    NAME                                                           READY   STATUS    RESTARTS   AGE
hyperpod-inference-operator-controller-manager-65c49967f5-894fg   1/1     Running   0         6d13h

  2. 檢閱運算子日誌：

    kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system

要尋找的內容：

運算子日誌會指出哪個元件失敗：

  • 模型 Pod 部署失敗

  • 負載平衡器建立問題

  • SageMaker AI 端點錯誤

檢查模型部署進度

若要監控模型部署進度並識別潛在問題，您可以使用 kubectl 命令來檢查各種元件的狀態。這有助於判斷部署是否正常進行，或在模型 Pod 建立、負載平衡器設定或 SageMaker AI 端點組態階段期間遇到問題。

方法 1：檢查 JumpStart 模型狀態

kubectl describe jumpstartmodel.inference.sagemaker.aws.amazon.com/<model-name> -n <namespace>

要監控的關鍵狀態指示燈：

  1. 部署狀態

    • 尋找 Status.State：應會顯示 DeploymentComplete

    • 檢查 Status.Deployment Status.Available Replicas

    • 監控Status.Conditions部署進度

  2. SageMaker AI 端點狀態

    • 檢查 Status.Endpoints.Sagemaker.State：應會顯示 CreationCompleted

    • 驗證 Status.Endpoints.Sagemaker.Endpoint Arn

  3. TLS 憑證狀態

    • 檢視Status.Tls Certificate詳細資訊

    • 檢查 中的憑證過期 Last Cert Expiry Time

方法 2：檢查推論端點組態

kubectl describe inferenceendpointconfig.inference.sagemaker.aws.amazon.com/<deployment_name> -n <namespace>

常見狀態狀態：

  • DeploymentInProgress：初始部署階段

  • DeploymentComplete：成功部署

  • Failed：部署失敗

注意

監控事件區段是否有任何警告或錯誤。檢查複本計數是否符合預期的組態。確認Status: True針對運作狀態良好的部署顯示所有條件。

VPC ENI 許可問題

由於在 VPC 中建立網路介面的許可不足，SageMaker AI 端點建立失敗。

錯誤訊息：

Please ensure that the execution role for variant AllTraffic has sufficient permissions for creating an endpoint variant within a VPC

根本原因：

推論運算子的執行角色缺少在 VPC 中建立網路介面 (ENI) 所需的 Amazon EC2 許可。

解決方法：

將下列 IAM 許可新增至推論運算子的執行角色：

{
    "Effect": "Allow",
    "Action": [
        "ec2:CreateNetworkInterfacePermission",
        "ec2:DeleteNetworkInterfacePermission"
     ],
    "Resource": "*"
}

驗證：

新增 許可之後：

  1. 刪除失敗的端點 （如果存在）

  2. 重試建立端點

  3. 監控部署狀態是否成功完成

注意

此許可對於在 VPC 模式下執行的 SageMaker AI 端點至關重要。確定執行角色也具有所有其他必要的 VPC 相關許可。

IAM 信任關係問題

HyperPod 推論運算子無法從 STS AssumeRoleWithWebIdentity 錯誤開始，表示 IAM 信任關係組態問題。

錯誤訊息：

failed to enable inference watcher for HyperPod cluster *****: operation error SageMaker: UpdateClusterInference, 
get identity: get credentials: failed to refresh cached credentials, failed to retrieve credentials, 
operation error STS: AssumeRoleWithWebIdentity, https response error StatusCode: 403, RequestID: ****, 
api error AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity

解決方法：

使用下列組態更新推論運算子 IAM 執行角色的信任關係。

取代下列預留位置：

  • <ACCOUNT_ID>： AWS 您的帳戶 ID

  • <REGION>：您的 AWS 區域

  • <OIDC_ID>：Amazon EKS 叢集的 OIDC 提供者 ID

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
            "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<namespace>:<service-account-name>",
                    "oidc.eks.us-east-2.amazonaws.com/id/<OIDC_ID>:aud": "sts.amazonaws.com"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "sagemaker.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

驗證：

更新信任關係之後：

  1. 在 IAM 主控台中驗證角色組態

  2. 視需要重新啟動推論運算子

  3. 監控運算子日誌以成功啟動

缺少 NVIDIA GPU 外掛程式錯誤

即使有可用的 GPU 節點，模型部署仍會因 GPU 不足錯誤而失敗。當 NVIDIA 裝置外掛程式未安裝在 HyperPod 叢集中時，就會發生這種情況。

錯誤訊息：

0/15 nodes are available: 10 node(s) didn't match Pod's node affinity/selector, 
5 Insufficient nvidia.com/gpu. preemption: 0/15 nodes are available: 
10 Preemption is not helpful for scheduling, 5 No preemption victims found for incoming pod.

根本原因：

  • Kubernetes 無法在沒有 NVIDIA 裝置外掛程式的情況下偵測 GPU 資源

  • 導致 GPU 工作負載的排程失敗

解決方法：

執行下列動作來安裝 NVIDIA GPU 外掛程式：

kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/refs/tags/v0.17.1/deployments/static/nvidia-device-plugin.yml

驗證步驟：

  1. 檢查外掛程式部署狀態：

    kubectl get pods -n kube-system | grep nvidia-device-plugin

  2. 確認 GPU 資源現在可見：

    kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\\.com/gpu

  3. 重試模型部署

注意

確保 NVIDIA 驅動程式安裝在 GPU 節點上。外掛程式安裝是每個叢集的一次性設定。可能需要叢集管理員權限才能安裝。

推論運算子無法啟動

推論運算子 Pod 無法啟動，並造成下列錯誤訊息。此錯誤是因為運算子執行角色的許可政策未獲授權執行 sts:AssumeRoleWithWebIdentity。因此，在控制平面上執行的運算子部分不會啟動。

錯誤訊息：

Warning Unhealthy 5m46s (x22 over 49m) kubelet Startup probe failed: Get "http://10.1.100.59:8081/healthz": context deadline exceeded (Client.Timeout exceeded while awaiting headers)

根本原因：

  • 推論運算子執行角色的許可政策未設定為存取 資源的授權字符。

解決方法：

為 HyperPod 推論運算子設定 執行角色EXECUTION_ROLE_ARN的下列政策：

HyperpodInferenceAccessPolicy-ml-cluster to include all resources
JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        }
    ]
}

驗證步驟：

  1. 變更政策。

  2. 終止 HyperPod 推論運算子 Pod。

  3. Pod 將重新啟動，而不會擲回任何例外狀況。