翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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 ENI アクセス許可の問題](sagemaker-hyperpod-model-deployment-ts-permissions.md)
+ [IAM 信頼関係の問題](sagemaker-hyperpod-model-deployment-ts-trust.md)
+ [NVIDIA GPU プラグインの欠落エラー](sagemaker-hyperpod-model-deployment-ts-gpu.md)
+ [推論演算子の起動に失敗する](sagemaker-hyperpod-model-deployment-ts-startup.md)
# SageMaker AI コンソールを使用した推論オペレーターのインストールの失敗
**概要:** クイックインストールまたはカスタムインストールを使用して SageMaker AI コンソールから推論演算子をインストールすると、基盤となる CloudFormation スタックがさまざまな問題により失敗することがあります。このセクションでは、一般的な障害シナリオとその解決方法について説明します。
## クイックインストールまたはカスタムインストールによる推論演算子アドオンのインストール失敗
**問題:** HyperPod クラスターの作成は正常に完了しましたが、推論演算子のアドオンのインストールは失敗します。
**一般的な原因:**
+ クラスターノードのポッド容量制限を超えました。推論演算子のインストールには、少なくとも 13 個のポッドが必要です。最小推奨インスタンスタイプは です`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. ポッド制限の問題を確認します。
```
# 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 コンソール (推奨) または AWS CLI を使用して推論演算子を再インストールします。
**ステップ 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: 根本的な問題を修正する**
失敗の原因に基づいて適切な解決策を選択します。
問題がポッドの制限を超えた場合:
```
# 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 ウェブフックの準備が整っていないため、Cert-manager のインストールに失敗しました
**問題:** Task Governance (Kueue) ウェブフックサービスに使用可能なエンドポイントがないため、cert-manager アドオンのインストールがウェブフックエラーで失敗します。これは、Task Governance ウェブフックポッドが完全に実行される前に、cert-manager がリソースを作成しようとするときに発生する競合状態です。これは、クラスターの作成中にタスクガバナンスアドオンが推論演算子とともにインストールされている場合に発生する可能性があります。
### 症状と診断
**エラーメッセージ:**
```
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 アドオンは、すべてのデプロイ作成を傍受する変更ウェブフックをインストールして登録します
+ Cert-manager アドオンは、タスクガバナンスウェブフックポッドの準備が整う前にデプロイリソースを作成しようとします
+ Kubernetes アドミッションコントロールは Task Governance ウェブフックを呼び出しますが、エンドポイントはありません (ポッドはまだ実行されていません)
**診断ステップ:**
1. 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
```
### 解決策
**解決策: cert-manager を削除して再インストールする**
タスクガバナンスウェブフックは 60 秒以内に準備完了になります。cert-manager アドオンを削除して再インストールするだけです。
1. 失敗した cert-manager アドオンを削除します。
```
aws eks delete-addon \
--cluster-name $EKS_CLUSTER_NAME \
--addon-name cert-manager \
--region $REGION
```
1. Task Governance ウェブフックの準備ができるまで 30～60 秒待ってから、cert-manager アドオンを再インストールします。
```
sleep 60
aws eks create-addon \
--cluster-name $EKS_CLUSTER_NAME \
--addon-name cert-manager \
--region $REGION
```
# AWS CLI による推論演算子のインストールの失敗
**概要:** CLI AWS を使用して推論演算子をインストールする場合、依存関係がないためにアドオンのインストールが失敗することがあります。このセクションでは、一般的な CLI のインストール失敗シナリオとその解決策について説明します。
## CSI ドライバーがないため、推論アドオンのインストールに失敗しました
**問題:** 必要な CSI ドライバーの依存関係が EKS クラスターにインストールされていないため、推論演算子のアドオンの作成が失敗します。
**症状と診断:**
**エラーメッセージ:**
アドオン作成ログまたは推論演算子ログには、次のエラーが表示されます。
```
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.finalizer を空の配列に設定します。
```
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. すべてのリソースがクリーンアップされたことを確認したら、推論アドオンを削除します。
## 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"
```
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: 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
```
1. 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
```
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 Controller がないため、推論アドオンのインストールに失敗しました
**問題:** 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 Controller がインストールされているかどうかを確認します。
```
# 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 Controller をインストールさせる (推奨)**
+ アドオン設定で 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 Controller のインストールを使用する**
+ 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 Controller が動作していることを確認します。
```
# 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"
```
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
```
# 証明書のダウンロードタイムアウト
SageMaker AI エンドポイントをデプロイすると、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 クラスターでモデルデプロイを開始できないことを示します。
**影響を受けるコンポーネント:**
通常のデプロイ中、推論演算子は次のことを行う必要があります。
+ モデルポッドをデプロイする
+ ロードバランサーの作成
+ 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
```
**検索対象:**
+ オペレータログのエラーメッセージ
+ オペレータポッドのステータス
+ デプロイ関連の警告または障害
**注記**
正常なデプロイは、妥当な時間内に「保留中」状態を超えて進行する必要があります。問題が解決しない場合は、推論演算子ログで特定のエラーメッセージを確認し、根本原因を特定します。
## モデルデプロイの失敗状態のトラブルシューティング
モデルデプロイが「失敗」状態になると、次の 3 つのコンポーネントのいずれかで失敗が発生する可能性があります。
+ モデルポッドのデプロイ
+ ロードバランサーの作成
+ 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
```
**検索対象:**
オペレータログには、失敗したコンポーネントが表示されます。
+ モデルポッドのデプロイの失敗
+ ロードバランサーの作成に関する問題
+ 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 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. 失敗したエンドポイントを削除する (存在する場合)
1. エンドポイントの作成を再試行する
1. デプロイのステータスをモニタリングして正常に完了する
**注記**
このアクセス許可は、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 実行ロールの信頼関係を次の設定で更新します。
次のプレースホルダーを置き換えます。
+ ``: 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. オペレーターログをモニタリングして正常に起動する
# 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
```
1. GPU リソースが表示されるようになりました。
```
kubectl get nodes -o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\\.com/gpu
```
1. モデルのデプロイを再試行する
**注記**
NVIDIA ドライバーが GPU ノードにインストールされていることを確認します。プラグインのインストールは、クラスターごとに 1 回限りのセットアップです。インストールにはクラスター管理者権限が必要になる場合があります。
# 推論演算子の起動に失敗する
推論演算子ポッドの起動に失敗し、次のエラーメッセージが発生しています。このエラーは、オペレーター実行ロールのアクセス許可ポリシーが の実行を許可されていないためです`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 推論オペレーターポッドを終了します。
1. ポッドは例外をスローせずに再起動されます。