hyperpod-ssm

用途

HyperPod SSM 用于通过 AWS Systems Manager (SSM) 在 SageMaker HyperPod 集群节点上执行远程命令和传输文件。它是访问 HyperPod 集群节点的主要接口，适合需要批量操作、诊断或管理集群节点的场景。

主要能力

工具集包含三个脚本，位于 scripts/ 目录下：

get-cluster-info.sh：解析集群名称到集群 ID（调用一次）。用法：scripts/get-cluster-info.sh CLUSTER_NAME [--region REGION] 输出：{"cluster_id":"...","cluster_arn":"...","cluster_name":"...","region":"..."}
list-nodes.sh：分页列出所有节点（调用一次）。用法：scripts/list-nodes.sh CLUSTER_NAME [--region REGION] [--instance-group GROUP] [--instance-id ID] 输出：ClusterNodeSummaries 的 JSON 数组（包含 InstanceId、InstanceGroupName、InstanceStatus 等）。说明：list-cluster-nodes 每页最多 100 个节点，该脚本自动处理分页。
ssm-exec.sh：在节点上执行命令（每个节点调用一次）。用法示例：
- 执行命令（使用预构建目标）：scripts/ssm-exec.sh --target "sagemaker-cluster:CLUSTERID_GROUP-INSTANCEID" 'command' [--region REGION]
- 执行命令（使用各部分）：scripts/ssm-exec.sh --cluster-id ID --group GROUP --instance-id INSTANCE_ID 'command' [--region REGION]
- 上传文件：scripts/ssm-exec.sh --target TARGET --upload LOCAL_PATH REMOTE_PATH [--region REGION]
- 读取远程文件：scripts/ssm-exec.sh --target TARGET --read REMOTE_PATH [--region REGION]

使用方式

前置条件

aws CLI v2，已针对目标账户/区域完成认证。
session-manager-plugin — 随 AWS CLI 一起安装。
jq — 脚本用它构建 JSON 负载。
unbuffer（来自 expect 包）— 用 PTY 包装 aws ssm start-session，使 session-manager-plugin 刷新 stdout 而不是竞态关闭。没有它，调用会间歇性返回空输出并报 Cannot perform start session: EOF，即使命令已执行。安装方式：sudo yum install expect、sudo apt install expect 或 brew install expect。ssm-exec.sh 会自动检测并使用它；缺失时回退并给出警告。

SSM 目标格式

Target: 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）。

跨多节点运行命令

SSM start-session 速率限制：每账户 3 TPS。据此规划批处理大小和延迟。
aws ssm send-command 不支持 sagemaker-cluster: 目标 — 只有 start-session 可用。

手动 SSM 命令

当脚本不适用时，直接使用 aws ssm start-session 配合 AWS-StartNonInteractiveCommand。每次调用都用 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

始终使用 JSON 文件作为 --parameters — 内联参数在特殊字符下会出错。
文档的 command 参数是 argv，不是 shell 输入。将多语句脚本包装在 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

适用场景

在 SageMaker HyperPod 集群节点上批量执行诊断命令（如检查 GPU、内存、磁盘、网络状态）。
向节点上传文件或从节点读取文件。
排查节点生命周期、CloudWatch 代理等问题。
需要以非交互方式在多个节点上运行命令时。

限制

默认 SSM 非交互用户是 root。
SSM 速率限制：每账户 3 TPS。
交互式会话（罕见）可省略 --document-name 获得 shell。
交互式命令（vim、top）不支持通过 AWS-StartNonInteractiveCommand 执行。
大输出可能被 SSM 截断。
常见错误排查参见 references/troubleshooting.md。