本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 通过 SageMaker AI 控制台进行推理操作员安装失败 **概述：**使用 “快速安装” 或 “自定义安装” 通过 SageMaker AI 控制台安装推理运算符时，底层 CloudFormation 堆栈可能会由于各种问题而失败。本节介绍常见的故障场景及其解决方案。 ## 通过快速安装或自定义安装导致推理运算符插件安装失败 **问题：** HyperPod 集群创建成功完成，但推理运算符插件安装失败。 **常见原因：** + 已超出集群节点上的 Pod 容量限制。推理运算符安装至少需要 13 个 pod。建议的最低实例类型为`ml.c5.4xlarge`。 + IAM 权限问题 + 资源配额限制 + 网络或 VPC 配置问题 ### 症状和诊断 **症状：** + 推理运算符插件在控制台中显示 CREATE\$1FAILED 或 DEGRADED + CloudFormation 与插件关联的堆栈处于 CREATE\$1FAILED 状态 + 安装进度停止或显示错误消息 **诊断步骤：** 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 ``` 1. 检查 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" ``` 1. 检查 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 \ --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 \ --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：重新安装推理运算符** 修复潜在问题后，使用以下方法之一重新安装推理运算符： + **SageMaker 带有自定义安装功能的 AI 控制台（推荐）：**重复使用之前安装的现有 IAM 角色和 TLS 存储桶。要查看步骤，请参阅[方法 1：通过 SageMaker AI 控制台安装 HyperPod 推理插件（推荐）](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui)。 + **AWS 带有已保存配置的 CLI：**使用您在步骤 1 中备份的配置重新安装附加组件。有关完整的 CLI 安装步骤，请参阅[方法 2：使用 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 带快速安装功能的 AI 控制台：**自动创建新的 IAM 角色、TLS 存储桶和依赖插件。要查看步骤，请参阅[方法 1：通过 SageMaker AI 控制台安装 HyperPod 推理插件（推荐）](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-ui)。 **步骤 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 ``` 1. 等待 30-60 秒让 Task Governance webhook 准备就绪，然后重新安装证书管理器插件： ``` sleep 60 aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --region $REGION ```