hyperpod-ssm

HyperPod SSM アクセス

前提条件

• aws CLI v2。対象のアカウント／リージョンで認証済みであること。
• session-manager-plugin — AWS CLI とともにインストールします。
• jq — スクリプトで JSON ペイロードを構築する際に使用します。
• unbuffer（expect パッケージに含まれます）— aws ssm start-session を PTY でラップし、session-manager-plugin が stdout をフラッシュしてから終了するようにします。これがない場合、コマンドが実行された場合でも、呼び出しが断続的に空の出力を返し、Cannot perform start session: EOF が発生します。sudo yum install expect、sudo apt install expect、または brew install expect でインストールしてください。ssm-exec.sh は自動的に検出して使用し、見つからない場合は警告を出して代替手段に切り替えます。

SSM ターゲット形式

ターゲット：sagemaker-cluster:<CLUSTER_ID>_<GROUP_NAME>-<INSTANCE_ID>

• CLUSTER_ID：クラスター ARN の最後のセグメント（クラスター名ではありません）。get-cluster-info.sh で取得します。
• GROUP_NAME：インスタンスグループ名。list-nodes.sh で取得します。
• INSTANCE_ID：EC2 インスタンス ID（例：i-0123456789abcdef0）

スクリプト

scripts/ の下に 3 つのスクリプトがあります。クラスター情報とノードを一度だけ取得してから、ノードごとに実行してください。

get-cluster-info.sh — クラスター名から ID を取得（1 回実行）

scripts/get-cluster-info.sh CLUSTER_NAME [--region REGION]
# Output: {"cluster_id":"...","cluster_arn":"...","cluster_name":"...","region":"..."}

list-nodes.sh — ページネーションを使ってすべてのノードを一覧表示（1 回実行）

scripts/list-nodes.sh CLUSTER_NAME [--region REGION] [--instance-group GROUP] [--instance-id ID]
# Output: JSON array of ClusterNodeSummaries (InstanceId, InstanceGroupName, InstanceStatus, etc.)

list-cluster-nodes は 100 ノードごとにページネーションします。このスクリプトがページネーションを自動的に処理します。

ssm-exec.sh — ノード上でコマンドを実行（ノードごとに実行）

# Execute — with pre-built target
scripts/ssm-exec.sh --target "sagemaker-cluster:CLUSTERID_GROUP-INSTANCEID" 'command' [--region REGION]

# Execute — with parts
scripts/ssm-exec.sh --cluster-id ID --group GROUP --instance-id INSTANCE_ID 'command' [--region REGION]

# Upload
scripts/ssm-exec.sh --target TARGET --upload LOCAL_PATH REMOTE_PATH [--region REGION]

# Read remote file
scripts/ssm-exec.sh --target TARGET --read REMOTE_PATH [--region REGION]

多数のノードでコマンドを実行する

SSM start-session のレート制限は、アカウントあたり 3 TPS です。これに応じてバッチサイズと遅延を計画してください。

aws ssm send-command は sagemaker-cluster: ターゲットをサポートしておらず、start-session のみ使用できます。

SSM コマンドを手動で実行する

スクリプトが適さない場合は、AWS-StartNonInteractiveCommand を指定して aws ssm start-session を直接使用してください。呼び出しはすべて unbuffer でラップしてください。これがない場合、stdout が断続的に空になります（「前提条件」を参照）。

cat > /tmp/cmd.json << 'EOF'
{"command": ["bash -c 'echo hello && whoami'"]}
EOF

unbuffer aws ssm start-session \
  --target sagemaker-cluster:{CLUSTER_ID}_{GROUP_NAME}-{INSTANCE_ID} \
  --region REGION \
  --document-name AWS-StartNonInteractiveCommand \
  --parameters file:///tmp/cmd.json

• --parameters には必ず JSON ファイルを使用してください。インラインパラメーターは特殊文字があると正しく動作しません。
• ドキュメントの command パラメーターは argv であり、シェル入力ではありません。複数の文からなるスクリプトは bash -c '...' でラップし、パイプ、セミコロン、リダイレクトが評価されるようにしてください。

よく使う診断コマンド

タスク	コマンド
ライフサイクルログ	cat /var/log/provision/provisioning.log
メモリ	free -h
ディスク／マウント	df -h && lsblk
GPU の状態	nvidia-smi
GPU メモリ	nvidia-smi --query-gpu=memory.used,memory.total --format=csv
EFA／ネットワーク	fi_info -p efa
CloudWatch エージェント	sudo systemctl status amazon-cloudwatch-agent
上位プロセス	ps aux --sort=-%mem | head -20

重要事項

• SSM のデフォルトの非対話型ユーザーは root です。
• SSM のレート制限は、アカウントあたり 3 TPS です。
• 対話型セッション（まれなケース）では、シェルを起動するため --document-name を省略してください。
• 対話型コマンド（vim、top）は AWS-StartNonInteractiveCommand ではサポートされていません。
• 大きな出力は SSM によって切り詰められる場合があります。
• よくあるエラーのトラブルシューティングについては、references/troubleshooting.md を参照してください。