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 がすでに動作するシェルから実行してください。つまり、aws sts get-caller-identity が成功する環境です。スクリプトは同じ aws バイナリを呼び出し、そのシェルのプロファイル、リージョン、SSO セッション、プロキシ、認証情報チェーンを引き継ぎます。

Windows／WSL／Git Bash に関する注意事項。 Windows では、これらを Bash の中継環境（WSL、Git Bash、MSYS）経由で実行しないでください。こうした Bash 環境では、Windows の AWS 設定、認証情報、SSO セッション、環境変数、プロキシ設定が共有されないことが多く、PowerShell では aws sts get-caller-identity が動作していても、Bash 内では失敗します。（これこそ、以前の .sh ヘルパーが Windows で失敗し、Python に置き換えられた理由です。）PowerShell を使用している場合は、PowerShell で python ...\check_role.py を直接実行してください。それでもヘルパーから ID を確認できない場合は、aws sts get-caller-identity が ARN を返すシェルで、同じ検出処理をネイティブに実行してください（以下の「ネイティブ AWS CLI の同等手順」を参照）。

操作の順序

ステップ 1 — ユーザーからロールが指定されているか？

指定されたロールを個別に検証します。

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

成功すると ARN を標準出力に出力します（終了コード 0）。失敗すると、その理由を標準エラー出力に記録します。壊れたロールを黙って修正しようとせず、問題を明示してください。

ステップ 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>"

2 番目の引数で、S3 アクセスを特定のバケットに制限します。不明な場合は省略してください。スクリプトが警告し、ユーザーは後でポリシーを更新できます。

ユーザーが作成できない場合（SSO プリンシパルの場合 — hf-cloud-aws-context-discovery で検出されています）：

ここで停止し、状況を明確に伝えてください。成功する操作があることを期待して、別の IAM 操作を試し続けないでください。

既存の SageMaker 実行ロールが見つかりませんでした。また、SSO で認証されているため、ロールを直接作成できません。次のいずれかを行ってください。

• AWS 管理者に SageMaker 実行ロール ARN を問い合わせる
• AWS 管理者に 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 を実際のバケット名に置き換えてください。2 番目の引数としてバケットを指定すると、create_role.py が自動的に置き換えます。非同期出力やデータキャプチャなどのオプション機能には、別途、範囲を限定した権限を追加してください。

AWS CLI のネイティブな同等手順（代替手段）

Python ヘルパーを実行できない場合や、ヘルパーから ID を確認できない場合（まれなケースです。通常は PATH の問題、または AWS のコンテキストを持たない Bash シム上で実行している場合）、aws sts get-caller-identity が動作するシェルで同じ事前確認を手動で行ってください。処理は 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 が返した場合と同じように、そのまま使用してください。Bash／macOS／Linux でも同じコマンドを使用します。