mcpField
H
hyperpod-ssm

hyperpod-ssm

github.com/awslabs云与 DevOps932147 次安装3 周前更新
代码仓库

关于 hyperpod-ssm

hyperpod-ssm 是面向 AWS SageMaker HyperPod 运维人员的 Shell 脚本技能，可解析集群与节点标识，并通过 SSM 会话执行命令或上传文件。

主要功能

  1. 01按名称解析集群 ID
  2. 02分页列出并筛选节点
  3. 03通过 SSM 在节点执行命令
  4. 04向节点上传文件

适用场景

  1. 01检查或排查 HyperPod 节点
  2. 02在选定节点上运行命令
  3. 03向集群节点传输文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/awslabs/agent-plugins --skill hyperpod-ssm

安装后在 Claude Code 中输入/hyperpod-ssm确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
troubleshooting.md
scripts/
get-cluster-info.sh
list-nodes.sh
ssm-exec.sh

详细介绍

HyperPod SSM 访问

前置条件

  • aws CLI v2，已通过身份验证，可访问目标账户/区域。
  • session-manager-plugin — 与 AWS CLI 一同安装。
  • jq — 脚本使用它构建 JSON 负载。
  • unbuffer（来自 expect 包）— 为 aws ssm start-session 提供 PTY 包装，使 session-manager-plugin 刷新标准输出，而不是抢先关闭。没有它时，即使命令已运行，调用也可能间歇性地返回空输出并报错 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/ 下有三个脚本。先解析集群信息和节点，只需一次，然后对每个节点执行命令。

get-cluster-info.sh — 解析集群名称 → ID（调用一次）
scripts/get-cluster-info.sh CLUSTER_NAME [--region REGION]
# Output: {"cluster_id":"...","cluster_arn":"...","cluster_name":"...","region":"..."}
list-nodes.sh — 使用分页列出所有节点（调用一次）
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 ssm start-session 和 AWS-StartNonInteractiveCommand。每次调用都必须用 unbuffer 包装 — 没有它，标准输出可能间歇性为空（参见“前置条件”）。

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，而不是 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 agentsudo systemctl status amazon-cloudwatch-agent
进程占用排行ps aux --sort=-%mem | head -20

重要细节

  • SSM 默认的非交互式用户是 root。
  • SSM 速率限制：每个账户 3 TPS。
  • 对于交互式会话（较少使用），省略 --document-name 即可获得 shell。
  • AWS-StartNonInteractiveCommand 不支持交互式命令（vim、top）。
  • SSM 可能会截断较大的输出。
  • 常见错误的排查方法，请参见 references/troubleshooting.md。

评论

支持 Markdown