Back to Details

hf-cloud-sagemaker-iam-preflight

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SageMaker IAM Preflight

SageMaker IAM 预检查

Every SageMaker resource needs an execution role — the IAM role SageMaker assumes to read model artifacts from S3, pull serving containers from ECR, and write logs. Most deployments fail here because the script tried to create a new role without checking if a usable one already existed, then blew up because the caller is an SSO principal.
This skill encodes the right order: discover, validate, only create if necessary.
每个SageMaker资源都需要一个execution role——即SageMaker承担的IAM角色，用于从S3读取模型工件、从ECR拉取服务容器以及写入日志。大多数部署失败都源于脚本未检查是否已有可用角色就尝试创建新角色，随后因调用者是SSO主体而报错。
此技能规定了正确的操作顺序：发现、验证、仅在必要时创建。

Running the helpers (cross-platform)

运行辅助工具（跨平台）

The helpers are Python so they run identically on Windows, macOS, and Linux:
bash
python3 scripts/check_role.py        # macOS / Linux
python  scripts/check_role.py        # Windows (PowerShell / cmd)
Run them from the shell where the AWS CLI already works — i.e. wherever 
aws sts get-caller-identity
succeeds. The script shells out to that same 
aws
binary and inherits the shell's profile, region, SSO session, proxy, and credential chain.
Windows / WSL / Git Bash caveat. Do not invoke these through a Bash shim (WSL, Git Bash, MSYS) on Windows. Those Bash environments frequently do not share the Windows AWS config, credentials, SSO sessions, environment variables, or proxy settings — so 
aws sts get-caller-identity
fails inside Bash even when it works natively in PowerShell. (This is exactly why the old 
.sh
helpers failed on Windows and were replaced with Python.) If you're in PowerShell, run 
python ...\check_role.py
directly in PowerShell. If the helper still can't see your identity, run the same discovery natively (see "Native AWS CLI equivalent" below) in the shell where 
aws sts get-caller-identity
returns your ARN.
这些辅助工具基于Python开发，可在Windows、macOS和Linux上一致运行：
bash
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 Shim（WSL、Git Bash、MSYS）调用这些工具。这些Bash环境通常不会共享Windows的AWS配置、凭证、SSO会话、环境变量或代理设置——因此即使在PowerShell中
aws sts get-caller-identity
可正常运行，在Bash中也可能失败。（这正是旧版
.sh
辅助工具在Windows上失败并被Python版本替代的原因。）如果您使用PowerShell，请直接在PowerShell中运行
python ...\check_role.py
。如果辅助工具仍无法识别您的身份，请在
aws sts get-caller-identity
可返回您ARN的Shell中手动执行相同的检查操作（参见下文“原生AWS CLI等效操作”）。

Order of operations

操作顺序

Step 1 — Did the user provide a role?

步骤1 — 用户是否已提供角色？

Validate that one specifically:
bash
python3 scripts/check_role.py "<role-name-or-arn>"
On success it prints the ARN to stdout (exit 0). On failure it logs why on stderr. Don't try to silently fix a broken role — surface the problem.
验证指定的角色：
bash
python3 scripts/check_role.py "<role-name-or-arn>"
成功时会将ARN打印到标准输出（退出码0）。失败时会在标准错误输出中记录原因。请勿尝试静默修复损坏的角色——应明确告知问题。

Step 2 — Discover existing roles

步骤2 — 发现现有角色

bash
python3 scripts/check_role.py
Lists roles matching common SageMaker patterns (
AmazonSageMaker-ExecutionRole-*
, 
SageMakerExecutionRole*
, etc.), ranks by last-used date (most recent first), validates trust policy in that order, returns the first usable ARN. Most accounts that have used SageMaker before already have one.
Why rank by last-used: in accounts with multiple roles (auto-generated 2021 role + manual project role + etc.), the alphabetically-first one is rarely the actively-maintained one. The most-recently-used role is more likely to have current policies — including cross-account ECR pull. The script prints the ranking so you can see which got picked.
IAM frequently reports no 
RoleLastUsed
at all (tracking only covers recent activity). When every candidate ties at "never used", the script falls back to newest creation date — a newer role is more likely to have current policies than a 2021 leftover.
bash
python3 scripts/check_role.py
列出符合常见SageMaker命名模式的角色（
AmazonSageMaker-ExecutionRole-*
、
SageMakerExecutionRole*
等），按最后使用日期排序（最近使用的优先），按此顺序验证信任策略，返回第一个可用的ARN。大多数曾使用过SageMaker的账户都已存在此类角色。
为何按最后使用日期排序：在拥有多个角色的账户中（自动生成的2021年角色 + 手动项目角色 + 其他），按字母顺序排在首位的角色很少是当前维护的角色。最近使用的角色更可能具备最新的策略——包括跨账户ECR拉取权限。脚本会打印排序结果，以便您了解选中的角色。
IAM经常报告无
RoleLastUsed
记录（仅跟踪近期活动）。当所有候选角色均显示“从未使用”时，脚本会退而求其次，按创建日期最新排序——较新的角色相比2021年遗留的角色更可能具备最新策略。

Step 3 — Create, only if discovery found nothing

步骤3 — 仅在未发现现有角色时创建

If the user can create (has IAM permissions):
bash
python3 scripts/create_role.py "<role-name>" "<model-bucket>"
Second arg scopes S3 access to a specific bucket. Omit if unknown; script warns and the user can update the policy later.
If the user cannot create (SSO principal — 
hf-cloud-aws-context-discovery
will have flagged this):
Stop and surface this clearly. Don't retry alternative IAM operations hoping one works:
I can't find an existing SageMaker execution role, and you're authenticated via SSO so you can't create one directly. Please either:
  • Ask your AWS admin for a SageMaker execution role ARN, or
  • Have them grant your SSO permission set 
    iam:CreateRole
    , 
    iam:AttachRolePolicy
    , 
    iam:PutRolePolicy
Specific instructions get unblocked fast; vague "permission denied" messages don't.
如果用户具备创建权限（拥有IAM权限）：
bash
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:AttachRolePolicy
    、
    iam:PutRolePolicy
    权限
明确的说明能快速解决问题；模糊的“权限被拒绝”消息则无法做到这一点。

What "validated" means

“验证通过”的定义

A role is usable when (1) it exists, (2) its trust policy allows 
sagemaker.amazonaws.com
to 
sts:AssumeRole
— see 
references/trust-policy.json
for the canonical form.
check_role.py
verifies these two. It does not deep-check permissions because comprehensive analysis is expensive (
iam:SimulatePrincipalPolicy
per action) and most existing SageMaker roles are over-permissioned via 
AmazonSageMakerFullAccess
. If you suspect a permissions issue at deploy time, the deployment error will tell you which action was denied — fix it then, not preemptively.
一个角色可用需满足两个条件：(1) 角色存在；(2) 其信任策略允许
sagemaker.amazonaws.com
执行
sts:AssumeRole
——标准格式请参见
references/trust-policy.json
。
check_role.py
会验证这两个条件。它不会深度检查权限，因为全面分析成本高昂（每个操作都需调用
iam:SimulatePrincipalPolicy
），且大多数现有SageMaker角色通过
AmazonSageMakerFullAccess
被过度授权。如果您在部署时怀疑存在权限问题，部署错误会告知您被拒绝的具体操作——届时再修复即可，无需提前处理。

Minimum permissions

最低权限

references/minimum-permissions.json
covers what SageMaker actually needs:
  • s3:GetObject
    + 
    s3:ListBucket
    on the model artifact bucket
  • ECR pull permissions
  • CloudWatch logs and metrics
Layered on top of 
AmazonSageMakerFullAccess
(attached by 
create_role.py
). Replace 
REPLACE_WITH_MODEL_BUCKET
in the template with the actual bucket name — 
create_role.py
does this automatically when given a bucket as its second argument.
references/minimum-permissions.json
涵盖了SageMaker实际所需的权限：
  • 模型工件存储桶的
    s3:GetObject
    + 
    s3:ListBucket
    权限
  • ECR拉取权限
  • CloudWatch日志和指标权限
这些权限基于
AmazonSageMakerFullAccess
（由
create_role.py
附加）构建。请将模板中的
REPLACE_WITH_MODEL_BUCKET
替换为实际存储桶名称——当
create_role.py
收到第二个参数（存储桶名称）时会自动完成此替换。

Native AWS CLI equivalent (fallback)

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

If the Python helper can't run or can't see your identity (rare — usually a broken PATH or running under a Bash shim that lacks AWS context), do the same preflight by hand in the shell where 
aws sts get-caller-identity
works. The logic is just AWS CLI calls; the helper exists only to bundle and rank them.
PowerShell:
powershell
undefined
如果Python辅助工具无法运行或无法识别您的身份（这种情况很少见——通常是PATH损坏或在缺乏AWS上下文的Bash Shim下运行），请在
aws sts get-caller-identity
可正常运行的Shell中手动执行相同的预检查操作。逻辑完全是AWS CLI调用；辅助工具仅用于整合和排序这些操作。
PowerShell：
powershell
undefined

1. List candidate SageMaker roles

1. 列出候选SageMaker角色

aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json
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

2. 针对每个候选角色，确认信任策略允许sagemaker.amazonaws.com

aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json
aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json

3. Prefer the most-recently-used role with SageMaker-execution naming

3. 优先选择最近使用过的、符合SageMaker执行角色命名规则的角色

(LastUsedDate is often None for every role — then prefer newest CreateDate)

（LastUsedDate通常对所有角色都为None——此时优先选择创建日期最新的角色）

aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text

Pick the most-recently-used role whose trust policy contains `sagemaker.amazonaws.com`. Use the resulting ARN exactly as if `check_role.py` had returned it. Bash/macOS/Linux use the same commands.
aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text

选择信任策略包含`sagemaker.amazonaws.com`且最近使用过的角色。将得到的ARN直接使用，就像`check_role.py`返回的结果一样。Bash/macOS/Linux使用相同的命令。