hf-cloud-sagemaker-iam-preflight

SageMaker IAM 预检

每个 SageMaker 资源都需要一个执行角色——即 SageMaker 用于从 S3 读取模型文件、从 ECR 拉取服务容器并写入日志的 IAM 角色。大多数部署都会在这里失败，因为脚本没有先检查是否已存在可用角色，就尝试创建新角色，随后又因调用方是 SSO 主体而出错。

此技能规定了正确的顺序：发现、验证，只有必要时才创建。

运行辅助脚本（跨平台）

这些辅助脚本使用 Python 编写，因此在 Windows、macOS 和 Linux 上的运行方式相同：

python3 scripts/check_role.py        # macOS / Linux
python  scripts/check_role.py        # Windows (PowerShell / cmd)

请在 AWS CLI 已可正常使用的 Shell 中运行这些脚本——也就是运行 aws sts get-caller-identity 能成功的环境。脚本会调用同一个 aws 可执行文件，并继承 Shell 的配置文件、区域、SSO 会话、代理和凭证链。

Windows / WSL / Git Bash 注意事项。 在 Windows 上，不要通过 Bash 兼容层（WSL、Git Bash、MSYS）调用这些脚本。这些 Bash 环境通常无法共享 Windows 的 AWS 配置、凭证、SSO 会话、环境变量或代理设置——因此，即使在原生 PowerShell 中运行正常，在 Bash 中运行 aws sts get-caller-identity 也会失败。（这正是旧版 .sh 辅助脚本在 Windows 上失效并被 Python 版替代的原因。）如果你使用 PowerShell，请直接在 PowerShell 中运行 python ...\check_role.py。如果辅助脚本仍无法获取你的身份，请在 aws sts get-caller-identity 能返回你的 ARN 的 Shell 中，使用原生命令执行相同的发现操作（参见下文“原生 AWS CLI 等效命令”）。

操作顺序

第 1 步——用户是否提供了角色？

专门验证该角色：

python3 scripts/check_role.py "<role-name-or-arn>"

成功时会将 ARN 输出到 stdout（退出码为 0）。失败时会将原因记录到 stderr。不要尝试悄悄修复有问题的角色——应明确说明问题。

第 2 步——发现现有角色

python3 scripts/check_role.py

列出符合常见 SageMaker 模式的角色（AmazonSageMaker-ExecutionRole-*、SageMakerExecutionRole* 等），按最近使用日期排序（最近使用的排在前面），并按此顺序验证信任策略，返回第一个可用的 ARN。大多数以前使用过 SageMaker 的账户已经有这样的角色。

按最近使用日期排序的原因：在拥有多个角色的账户中（自动生成的 2021 年角色、手动创建的项目角色等），按字母顺序排在最前面的角色往往不是当前维护中的角色。最近使用的角色更可能具有最新策略，包括跨账户 ECR 拉取策略。脚本会打印排序结果，便于查看最终选择了哪个角色。

IAM 经常完全不提供 RoleLastUsed（该跟踪功能只涵盖近期活动）。当所有候选角色的状态都是“从未使用”时，脚本会改为按创建日期从新到旧排序——较新的角色比 2021 年遗留角色更可能具有最新策略。

第 3 步——仅在未发现任何角色时才创建

如果用户可以创建（拥有 IAM 权限）：

python3 scripts/create_role.py "<role-name>" "<model-bucket>"

第二个参数用于将 S3 访问权限限定到特定存储桶。若存储桶未知，请省略此参数；脚本会发出警告，用户之后可以更新策略。

如果用户无法创建（SSO 主体——hf-cloud-aws-context-discovery 会标记这种情况）：

停止操作并明确说明原因。不要尝试其他 IAM 操作，寄希望于其中某项能够成功：

我找不到现有的 SageMaker 执行角色，而且你通过 SSO 进行身份验证，因此无法直接创建角色。请任选以下方式：

• 请 AWS 管理员提供 SageMaker 执行角色 ARN，或
• 请管理员向你的 SSO 权限集授予 iam:CreateRole、iam:PutRolePolicy 权限

明确具体的指引能让问题迅速得到解决；含糊的“权限被拒绝”消息则不能。

“已验证”的含义

角色可用需满足以下条件：（1）角色存在；（2）其信任策略允许 sagemaker.amazonaws.com 执行 sts:AssumeRole；（3）其权限仅授予此部署所需的操作和资源。规范信任策略见 references/trust-policy.json。

check_role.py 会验证角色是否存在及其信任策略，因为权限评估取决于部署所用的确切 S3、ECR、日志记录和可选输出资源。部署前，请检查所选角色的策略，并与 references/minimum-permissions.json 比对；仅添加缺少的操作，并将其范围限定为所需资源。不要附加 AmazonSageMakerFullAccess，也不要等到出现 AccessDenied 错误后再检查权限。

最低权限

references/minimum-permissions.json 是用于端点执行的独立内联策略：

• 模型构件存储桶上的 s3:GetObject + s3:ListBucket
• ECR 拉取权限
• CloudWatch 日志和指标

create_role.py 会安装此内联策略，而不会附加托管式 FullAccess 策略。将模板中的 REPLACE_WITH_MODEL_BUCKET 替换为实际存储桶名称——如果将存储桶作为第二个参数传给 create_role.py，它会自动完成替换。对于异步输出或数据捕获等可选功能，请单独添加范围严格限定的权限。

原生 AWS CLI 等效操作（备用方案）

如果 Python 辅助脚本无法运行或无法识别你的身份（这种情况很少见，通常是 PATH 配置错误，或在缺少 AWS 上下文的 Bash shim 下运行），请在 aws sts get-caller-identity 可正常运行的 shell 中手动执行相同的预检。其逻辑仅涉及 AWS CLI 调用；辅助脚本只是将这些调用打包并排序。

PowerShell：

# 1. List candidate SageMaker roles
aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json

# 2. For each candidate, confirm the trust policy allows sagemaker.amazonaws.com
aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json

# 3. Prefer the most-recently-used role with SageMaker-execution naming
#    (LastUsedDate is often None for every role — then prefer newest CreateDate)
aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text

选择信任策略中包含 sagemaker.amazonaws.com 的最近使用角色。使用得到的 ARN，就像 check_role.py 返回了该 ARN 一样。Bash/macOS/Linux 使用相同的命令。