SageMaker IAM Preflight
Chaque ressource SageMaker a besoin d'un rôle d'exécution — le rôle IAM que SageMaker assume pour lire les artefacts de modèle depuis S3, extraire les conteneurs de serving depuis ECR, et écrire les logs. La plupart des déploiements échouent ici parce que le script a tenté de créer un nouveau rôle sans vérifier si un rôle utilisable existait déjà, puis s'est écrasé parce que l'appelant est un principal SSO.
Ce skill encode le bon ordre : découvrir, valider, créer seulement si nécessaire.
Lancer les helpers (multiplateforme)
Les helpers sont en Python donc ils s'exécutent de manière identique sur Windows, macOS et Linux :
python3 scripts/check_role.py # macOS / Linux
python scripts/check_role.py # Windows (PowerShell / cmd)Lancez-les depuis le shell où l'AWS CLI fonctionne déjà — c'est-à-dire partout où aws sts get-caller-identity réussit. Le script invoque ce même binaire aws et hérite du profil, de la région, de la session SSO, du proxy et de la chaîne de credentials du shell.
Caveat Windows / WSL / Git Bash. Ne pas invoquer ces helpers via un shim Bash (WSL, Git Bash, MSYS) sur Windows. Ces environnements Bash ne partagent fréquemment pas la config AWS Windows, les credentials, les sessions SSO, les variables d'environnement ou les paramètres proxy — donc
aws sts get-caller-identityéchoue à l'intérieur de Bash même quand ça marche nativement dans PowerShell. (C'est exactement pourquoi les anciens helpers.shont échoué sur Windows et ont été remplacés par Python.) Si vous êtes dans PowerShell, exécutezpython ...\check_role.pydirectement dans PowerShell. Si le helper ne voit toujours pas votre identité, lancez la même découverte nativement (voir « Équivalent AWS CLI natif » ci-dessous) dans le shell oùaws sts get-caller-identityretourne votre ARN.
Ordre des opérations
Étape 1 — L'utilisateur a-t-il fourni un rôle ?
Validez-en un en particulier :
python3 scripts/check_role.py "<role-name-or-arn>"En cas de succès, il affiche l'ARN sur stdout (exit 0). En cas d'échec, il enregistre la raison sur stderr. N'essayez pas de corriger silencieusement un rôle cassé — surfacez le problème.
Étape 2 — Découvrir les rôles existants
python3 scripts/check_role.pyListe les rôles correspondant à des motifs SageMaker courants (AmazonSageMaker-ExecutionRole-*, SageMakerExecutionRole*, etc.), les classe par date d'utilisation (les plus récents en premier), valide la politique de confiance dans cet ordre, retourne le premier ARN utilisable. La plupart des comptes ayant utilisé SageMaker avant en ont déjà un.
Pourquoi classer par date d'utilisation : dans les comptes avec plusieurs rôles (rôle auto-généré 2021 + rôle projet manuel + etc.), celui qui est alphabétiquement en premier est rarement celui activement maintenu. Le rôle le plus récemment utilisé a plus de chances d'avoir des politiques courantes — y compris l'ECR pull cross-account. Le script affiche le classement pour que vous puissiez voir lequel a été sélectionné.
IAM rapporte fréquemment aucun RoleLastUsed du tout (le suivi couvre seulement l'activité récente). Quand tous les candidats sont au même niveau « jamais utilisé », le script bascule vers la date de création la plus récente — un rôle plus récent a plus de chances d'avoir des politiques courantes qu'un reste de 2021.
Étape 3 — Créer, seulement si la découverte n'a rien trouvé
Si l'utilisateur peut créer (a les permissions IAM) :
python3 scripts/create_role.py "<role-name>" "<model-bucket>"Le deuxième argument limite l'accès S3 à un bucket spécifique. Omettez-le si inconnu ; le script prévient et l'utilisateur peut mettre à jour la politique plus tard.
Si l'utilisateur ne peut pas créer (principal SSO — hf-cloud-aws-context-discovery aura marqué ceci) :
Arrêtez et surfacez cela clairement. Ne réessayez pas d'autres opérations IAM en espérant qu'une fonctionne :
Je ne trouve pas de rôle d'exécution SageMaker existant, et vous êtes authentifié via SSO donc vous ne pouvez pas en créer un directement. Veuillez soit :
- Demander à votre administrateur AWS un ARN de rôle d'exécution SageMaker, soit
- Lui demander d'accorder à votre permission set SSO
iam:CreateRole,iam:AttachRolePolicy,iam:PutRolePolicy
Les instructions spécifiques se débloquent rapidement ; les messages vagues « permission denied » non.
Ce que « validé » signifie
Un rôle est utilisable quand (1) il existe, (2) sa politique de confiance permet à sagemaker.amazonaws.com de faire sts:AssumeRole — voir references/trust-policy.json pour la forme canonique.
check_role.py vérifie ces deux points. Il ne fait pas une vérification approfondie des permissions car l'analyse complète est coûteuse (iam:SimulatePrincipalPolicy par action) et la plupart des rôles SageMaker existants sont sur-permissionnés via AmazonSageMakerFullAccess. Si vous soupçonnez un problème de permissions au moment du déploiement, l'erreur de déploiement vous dira quelle action a été refusée — corrigez-la alors, pas de façon préemptive.
Permissions minimales
references/minimum-permissions.json couvre ce que SageMaker a réellement besoin :
s3:GetObject+s3:ListBucketsur le bucket des artefacts de modèle- Permissions d'ECR pull
- Logs et métriques CloudWatch
En couche au-dessus de AmazonSageMakerFullAccess (attaché par create_role.py). Remplacez REPLACE_WITH_MODEL_BUCKET dans le template par le nom du bucket réel — create_role.py le fait automatiquement quand reçoit un bucket comme deuxième argument.
Équivalent AWS CLI natif (secours)
Si le helper Python ne peut pas s'exécuter ou ne peut pas voir votre identité (rare — généralement un PATH cassé ou exécution sous un shim Bash qui manque de contexte AWS), faites le même preflight à la main dans le shell où aws sts get-caller-identity fonctionne. La logique est juste des appels AWS CLI ; le helper existe seulement pour les regrouper et les classer.
PowerShell :
# 1. Lister les rôles SageMaker candidats
aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json
# 2. Pour chaque candidat, confirmer que la politique de confiance permet sagemaker.amazonaws.com
aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json
# 3. Préférer le rôle le plus récemment utilisé avec le nommage d'exécution SageMaker
# (LastUsedDate est souvent None pour chaque rôle — alors préférer le CreateDate le plus récent)
aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output textSélectionnez le rôle le plus récemment utilisé dont la politique de confiance contient sagemaker.amazonaws.com. Utilisez l'ARN résultant exactement comme si check_role.py l'avait retourné. Bash/macOS/Linux utilisent les mêmes commandes.