View a markdown version of this page

通过 SageMaker AI 控制台进行推理操作员安装失败 - 亚马逊 SageMaker AI
通过快速安装或自定义安装导致推理运算符插件安装失败由于 Kueue webhook 还没准备好，证书管理器安装失败

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

通过 SageMaker AI 控制台进行推理操作员安装失败

概述：使用 “快速安装” 或 “自定义安装” 通过 SageMaker AI 控制台安装推理运算符时，底层 CloudFormation 堆栈可能会由于各种问题而失败。本节介绍常见的故障场景及其解决方案。

通过快速安装或自定义安装导致推理运算符插件安装失败

问题： HyperPod 集群创建成功完成，但推理运算符插件安装失败。

常见原因：

  • 已超出集群节点上的 Pod 容量限制。推理运算符安装至少需要 13 个 pod。建议的最低实例类型为ml.c5.4xlarge。

  • IAM 权限问题

  • 资源配额限制

  • 网络或 VPC 配置问题

症状和诊断

症状：

  • 推理运算符插件在控制台中显示 CREATE_FAILED 或 DEGRADED

  • CloudFormation 与插件关联的堆栈处于 CREATE_FAILED 状态

  • 安装进度停止或显示错误消息

诊断步骤：

  1. 检查推理运算符插件状态：

    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

  2. 检查 pod 限制问题：

    # 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"

  3. 检查 CloudFormation 堆栈状态（如果使用控制台安装）：

    # 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

解决方案

要解决安装失败，请保存当前配置，删除失败的插件，修复潜在问题，然后通过 SageMaker AI 控制台（推荐）或 CLI AWS 重新安装推理运算符。

步骤 1：保存当前配置

  • 删除前提取并保存插件配置：

    # 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 '.'

步骤 2：删除失败的插件

  • 删除推理运算符插件：

    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

第 3 步：修复潜在问题

根据故障原因选择适当的解决方案：

如果问题是超出了 pod 限制：

# 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

步骤 4：重新安装推理运算符

修复潜在问题后，使用以下方法之一重新安装推理运算符：

步骤 5：验证安装成功

# 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

由于 Kueue webhook 还没准备好，证书管理器安装失败

问题：由于任务管理 (Kueue) webhook 服务没有可用的端点，证书管理器插件安装失败并出现 webhook 错误。这是一种争用条件，当证书管理器在 Task Governance webhook pod 完全运行之前尝试创建资源时。当在集群创建期间与推理运算符一起安装任务治理插件时，可能会发生这种情况。

症状和诊断

错误消息：

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"

根本原因：

  • Task Governance 插件安装并注册一个可拦截所有部署创建的变异 webhook

  • Cert-Manager 插件在任务治理 webhook pod 准备就绪之前尝试创建部署资源

  • Kubernetes 准入控制会调用任务治理 webhook，但它没有端点（Pod 尚未运行）

诊断步骤：

  1. 检查证书管理器插件状态：

    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

解决方案

解决方案：删除并重新安装证书管理器

任务管理 webhook 将在 60 秒内准备就绪。只需删除并重新安装证书管理器插件即可：

  1. 删除失败的证书管理器插件：

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

  2. 等待 30-60 秒让 Task Governance webhook 准备就绪，然后重新安装证书管理器插件：

    sleep 60

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