本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # HyperPod 推理疑难解答本疑难解答指南解决了 Amazon SageMaker HyperPod 推理部署和操作期间可能出现的常见问题。这些问题通常涉及 VPC 网络配置、IAM 权限、Kubernetes 资源管理和操作员连接问题，这些问题可能会阻碍成功部署模型或导致部署失败或保持待处理状态。本故障排除指南使用以下术语：**故障排除步骤**是识别和调查问题的诊断程序，**解决方案**提供修复已发现问题的具体操作，**验证**确认解决方案是否正常运行。 **Topics** + [通过 SageMaker AI 控制台进行推理操作员安装失败](sagemaker-hyperpod-model-deployment-ts-console-cfn-failures.md) + [通过 AWS CLI 安装推理运算符失败](sagemaker-hyperpod-model-deployment-ts-cli.md) + [证书下载超时](sagemaker-hyperpod-model-deployment-ts-certificate.md) + [模型部署问题](sagemaker-hyperpod-model-deployment-ts-deployment-issues.md) + [VPC 弹性网卡权限问题](sagemaker-hyperpod-model-deployment-ts-permissions.md) + [IAM 信任关系问题](sagemaker-hyperpod-model-deployment-ts-trust.md) + [缺少英伟达 GPU 插件错误](sagemaker-hyperpod-model-deployment-ts-gpu.md) + [推理运算符无法启动](sagemaker-hyperpod-model-deployment-ts-startup.md) # 通过 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 ``` # 通过 AWS CLI 安装推理运算符失败 **概述：**通过 AWS CLI 安装推理运算符时，插件安装可能会因为缺少依赖项而失败。本节介绍常见的 CLI 安装失败场景及其解决方案。 ## 由于缺少 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 ``` 1. 检查 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" ``` 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 步：安装缺失的 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" ``` 1. 安装 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 ``` 1. 验证 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" ``` 1. 安装 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 ``` **步骤 3：验证所有依赖关系** 安装缺少的依赖项后，在重试推理运算符安装之前，请先验证它们是否正常运行： ``` # 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 ``` 1. 检查是否有卡住的自定义资源。 ``` # Check for JumpStartModel resources kubectl get jumpstartmodels -A # Check for InferenceEndpointConfig resources kubectl get inferenceendpointconfigs -A ``` 1. 检查资源卡住的终结器。 ``` # Example for a specific JumpStartModel kubectl get jumpstartmodels -n -o jsonpath='{.metadata.finalizers}' # Example for a specific InferenceEndpointConfig kubectl get inferenceendpointconfigs -n -o jsonpath='{.metadata.finalizers}' ``` **解决方法：** 从所有模型部署中手动移除在移除推理插件时未删除的终结器。为每个卡住的自定义资源完成以下步骤。 **从资源中移除终结器 JumpStartModel ** 1. 列出所有命名空间中的所有 JumpStartModel 资源。 ``` kubectl get jumpstartmodels -A ``` 1. 对于每个 JumpStartModel 资源，通过修补资源来移除终结器，将 metadata.finalizers 设置为空数组。 ``` kubectl patch jumpstartmodels -n -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 以下示例说明如何修补名为 kv-l1-only 的资源。 ``` kubectl patch jumpstartmodels kv-l1-only -n default -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 1. 验证模型实例是否已删除。 ``` 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) ``` 1. 验证 JumpStartModel CRD 是否已被移除。 ``` kubectl get crd | grep jumpstartmodels.inference.sagemaker.aws.amazon.com ``` 如果成功删除 CRD，则此命令不返回任何输出。 **从资源中移除终结器 InferenceEndpointConfig ** 1. 列出所有命名空间中的所有 InferenceEndpointConfig 资源。 ``` kubectl get inferenceendpointconfigs -A ``` 1. 对于每种 InferenceEndpointConfig 资源，移除终结器。 ``` kubectl patch inferenceendpointconfigs -n -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 以下示例说明如何修补名为的资源 my-inference-config。 ``` kubectl patch inferenceendpointconfigs my-inference-config -n default -p '{"metadata":{"finalizers":[]}}' --type=merge ``` 1. 确认配置实例已删除。 ``` 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) ``` 1. 验证 InferenceEndpointConfig CRD 是否已被移除。 ``` kubectl get crd | grep inferenceendpointconfigs.inference.sagemaker.aws.amazon.com ``` 如果成功删除 CRD，则此命令不返回任何输出。 **重新安装推理插件** 清理所有卡住的资源并确认 CRDs 它们已被移除后，重新安装推理插件。有关更多信息，请参阅 [使用 EKS 附加组件安装推理运算符](sagemaker-hyperpod-model-deployment-setup.md#sagemaker-hyperpod-model-deployment-setup-install-inference-operator-addon)。 **验证：** 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 ``` 状态应为 “活跃”，“健康” 应为 “健康”。 1. 验证 CRDs 是否已正确安装。 ``` kubectl get crd | grep inference.sagemaker.aws.amazon.com ``` 您应该会在输出中看到与推理相关的 CRDs 内容。 1. 测试创建新模型部署以确认问题已得到解决。 ``` # Create a test deployment using your preferred method kubectl apply -f ``` **预防措施**：为防止出现此问题，请在卸载推理插件之前完成以下步骤。 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 ``` 1. 确认所有自定义资源都已删除。 1. 确认所有资源都已清理完毕后，删除推理插件。 ## 由于缺少证书管理器，推理插件安装失败 **问题：**由于未安装证书管理器 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. 检查证书管理器是否已安装： ``` # 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" ``` 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：安装证书管理器插件** 1. 安装证书管理器 EKS 附加组件： ``` aws eks create-addon \ --cluster-name $EKS_CLUSTER_NAME \ --addon-name cert-manager \ --addon-version v1.18.2-eksbuild.2 \ --region $REGION ``` 1. 验证证书管理器的安装： ``` # 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. 安装证书管理器后，请重试推理运算符的安装： ``` # 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 ``` 1. 监控安装： ``` # 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 控制器，推理插件安装失败 **问题：**推理运算符插件创建失败，因为未安装 Loa AWS d Balancer Controller 或者没有为推理插件正确配置。 **症状和诊断：** **错误消息：** 插件创建日志或推理操作员日志中出现以下错误： ``` 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" ``` 1. 检查推理运算符插件配置： ``` 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 ``` **解决方法：** 根据您的设置选择以下选项之一： **选项 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 Controller，请将插件配置为使用现有安装： ``` # 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 ``` 1. 验证 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 事件驱动的自动扩缩器）运算符或配置不正确。 **症状和诊断：** **错误消息：** 插件创建日志或推理操作员日志中出现以下错误： ``` 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" ``` 1. 检查推理运算符插件配置： ``` 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 ``` **解决方法：** 根据您的设置选择以下选项之一： **选项 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 ``` 1. 验证 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 ``` # 证书下载超时部署 A SageMaker I 终端节点时，由于无法在 VPC 环境中下载证书颁发机构 (CA) 证书，创建过程失败。有关详细的配置步骤，请参阅[管理员指南](https://github.com/aws-samples/sagemaker-genai-hosting-examples/blob/main/SageMakerHyperpod/hyperpod-inference/Hyperpod_Inference_Admin_Notebook.ipynb)。 **错误消息：** SageMaker AI 终端节点 CloudWatch 日志中出现以下错误： ``` Error downloading CA certificate: Connect timeout on endpoint URL: "https://****.s3..amazonaws.com/****/***.pem" ``` **根本原因：** + 当推理操作员无法访问您的 VPC 中的 Amazon S3 中的自签名证书时，就会出现此问题 + 正确配置 Amazon S3 VPC 终端节点对于访问证书至关重要 **解决方法：** 1. 如果您没有 Amazon S3 VPC 终端节点： + 按照[管理员指南](https://github.com/aws-samples/sagemaker-genai-hosting-examples/blob/main/SageMakerHyperpod/hyperpod-inference/Hyperpod_Inference_Admin_Notebook.ipynb)第 5.3 节中的配置创建 Amazon S3 VPC 终端节点。 1. 如果您已经有一个 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 ``` 1. 查看推理运算符日志并检查操作员日志中是否有错误消息： ``` kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system ``` **要找什么：** + 操作员日志中的错误消息 + 操作员窗格的状态 + 任何与部署相关的警告或故障 **注意** 健康的部署应在合理的时间内超过 “待处理” 状态。如果问题仍然存在，请查看推理运算符日志以了解特定的错误消息以确定根本原因。 ## 模型部署失败状态疑难解答当模型部署进入 “失败” 状态时，以下三个组件之一可能会出现故障： + 模型 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 ``` 1. 查看操作员日志： ``` kubectl logs hyperpod-inference-operator-controller-manager-5b5cdd7757-txq8f -n hyperpod-inference-operator-system ``` **要找什么：** 操作员日志将显示哪个组件出现故障： + 模型 pod 部署失败 + 负载均衡器创建问题 + SageMaker AI 端点错误 ## 检查模型部署进度要监控模型部署进度并识别潜在问题，您可以使用 kubectl 命令检查各种组件的状态。这有助于确定部署是正常进行，还是在模型容器创建、负载均衡器设置或 SageMaker AI 端点配置阶段遇到问题。 **方法 1：检查 JumpStart 模型状态** ``` kubectl describe jumpstartmodel.inference.sagemaker.aws.amazon.com/ -n ``` **要监控的关键状态指标：** 1. 部署状态 + 寻找`Status.State`：应该显示 `DeploymentComplete` + 查看 `Status.Deployment Status.Available Replicas` + 监控`Status.Conditions`部署进度 1. SageMaker AI 端点状态 + 勾选`Status.Endpoints.Sagemaker.State`：应该显示 `CreationCompleted` + 验证 `Status.Endpoints.Sagemaker.Endpoint Arn` 1. TLS 证书状态 + 查看`Status.Tls Certificate`详情 + 在中查看证书到期时间 `Last Cert Expiry Time` **方法 2：检查推理端点配置** ``` kubectl describe inferenceendpointconfig.inference.sagemaker.aws.amazon.com/ -n ``` **常见状态状态：** + `DeploymentInProgress`: 初始部署阶段 + `DeploymentComplete`: 成功部署 + `Failed`: 部署失败 **注意** 监视 “事件” 部分是否存在任何警告或错误。检查副本数量是否与预期配置相符。验证显示的所有条件`Status: True`以实现正常部署。 # VPC 弹性网卡权限问题 SageMaker 由于在 VPC 中创建网络接口的权限不足，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. 删除失败的端点（如果存在） 1. 重试创建终端节点 1. 监控部署状态以成功完成 **注意** 此权限对于在 VPC 模式下运行的 SageMaker AI 终端节点至关重要。确保执行角色还具有所有其他必要的 VPC 相关权限。 # IAM 信任关系问题 HyperPod 推理运算符启动失败， AssumeRoleWithWebIdentity出现 STS 错误，这表明 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 执行角色的信任关系。替换以下占位符： + ``: 您的 AWS 账户 ID + ``: 你所在 AWS 的地区 + ``: 您的 Amazon EKS 集群的 OIDC 提供商 ID ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringLike": { "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount::", "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com" } } }, { "Effect": "Allow", "Principal": { "Service": [ "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` **验证：** 更新信任关系后： 1. 在 IAM 控制台中验证角色配置 1. 如有必要，请重新启动推理运算符 1. 监控操作员日志以成功启动 # 缺少英伟达 GPU 插件错误尽管有可用的 GPU 节点，但模型部署失败并出现 GPU 不足错误。当 HyperPod集群中未安装 NVIDIA 设备插件时，就会发生这种情况。 **错误消息：** ``` 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. ``` **根本原因：** + 如果没有 NVIDIA 设备插件，Kubernetes 就无法检测 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 ``` 1. 验证 GPU 资源现在是否可见： ``` kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\\.com/gpu ``` 1. 重试模型部署 **注意** 确保在 GPU 节点上安装了 NVIDIA 驱动程序。插件安装是每个集群的一次性设置。可能需要集群管理员权限才能安装。 # 推理运算符无法启动推理运算符 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. 更改策略。 1. 终止 HyperPod 推理运算符 pod。 1. Pod 将在不引发任何异常的情况下重新启动。