sagemaker.core.helper.iam_role_resolver

sagemaker.core.helper.iam_role_resolver#

IAM role resolution, validation, and (opt-in) creation for the SageMaker Python SDK.

The default path is read-only: resolve_and_validate_role() resolves the role to use (an explicitly provided role, or the caller’s own identity) and validates that it has the permissions and trust policy required for the operation. It never creates, mutates, attaches, or tags IAM roles or policies.

Creating a managed least-privilege execution role is an explicit, opt-in action exposed via the IamRoleResolver class at the bottom of this module — the only code path here that writes IAM. Auto-creation was removed from the default path because mutating a customer’s IAM account as a side effect of an ordinary SDK call is an elevation-of-privilege risk.

Functions

resolve_and_validate_role(provided_role, ...)

Resolve the role to use and validate it (read-only; does not mutate IAM).

verify_hyperpod_connect_permissions([...])

Verify the caller can drive the HyperPod CLI; warn (don't block) if not.

Classes

IamRoleResolver([sagemaker_session])

Create and manage SageMaker execution roles (explicit, opt-in).

Exceptions

RoleAutoCreationError

Raised when explicit role creation fails due to insufficient IAM permissions.

RoleValidationError

Raised when the resolved IAM role lacks the permissions/trust an operation needs.
class sagemaker.core.helper.iam_role_resolver.IamRoleResolver(sagemaker_session=None)[source]#

Bases: object

Create and manage SageMaker execution roles (explicit, opt-in).

Instantiate with an optional SageMaker session and call create_execution_role() to provision a managed least-privilege role for a workload type, or delete_execution_role() to remove one. This class is the only place in the SDK that writes IAM.

Example:

from sagemaker.core.helper import IamRoleResolver

resolver = IamRoleResolver()
role_arn = resolver.create_execution_role(
    role_type="training", s3_resource="my-bucket"
)
# ... pass role_arn into SFTTrainer(role=role_arn) / ModelBuilder(...) etc.
create_execution_role(role_type: str, *, role_name: str | None = None, s3_resource: str | List[str] = '*', kms_resource: str | List[str] = '*', update_if_exists: bool = True) → str[source]#

Create (or update) a managed least-privilege execution role.

Parameters:

  • role_type – One of ROLE_TYPES.

  • role_name – Role name to create. Defaults to the well-known SageMaker-AutoRole-<Type> name from the policy config.

  • s3_resource – S3 bucket name(s) to scope S3 policies. “*” (default) grants account-wide S3 access and emits a WARNING.

  • kms_resource – KMS key id(s) to scope KMS policies. “*” (default) grants account-wide KMS access and emits a WARNING.

  • update_if_exists – If the role already exists, attach/refresh its policies (idempotent). If False and the role exists, return its ARN without modifying policies.

Returns:

The created/existing role ARN.

Raises:

  • RoleAutoCreationError – The caller lacks the IAM permissions to create the role/policies.

  • ValueError – role_type is invalid.

delete_execution_role(role_type: str, *, role_name: str | None = None) → None[source]#

Delete a role created by create_execution_role() and its policies.

Idempotent and best-effort: detaches and deletes the SDK-managed policies, then deletes the role. Missing entities are ignored so re-running is safe. Useful for notebook/test cleanup.

get_required_actions(role_type: str) → List[str][source]#

Return the IAM actions a role of role_type needs (read-only preview).

exception sagemaker.core.helper.iam_role_resolver.RoleAutoCreationError[source]#

Bases: Exception

Raised when explicit role creation fails due to insufficient IAM permissions.

exception sagemaker.core.helper.iam_role_resolver.RoleValidationError[source]#

Bases: Exception

Raised when the resolved IAM role lacks the permissions/trust an operation needs.

The message lists the specific missing permissions (or required actions) and the two ways to fix it: grant them to the role, or create a dedicated least-privilege role via IamRoleResolver().create_execution_role(...).

sagemaker.core.helper.iam_role_resolver.resolve_and_validate_role(provided_role: str | None, role_type: str, sagemaker_session=None) → str[source]#

Resolve the role to use and validate it (read-only; does not mutate IAM).

Resolution:

  1. provided_role given → resolve it to an ARN (must exist).

  2. Otherwise → resolve the caller’s own identity role.

The resolved role is then VALIDATED (read-only, via iam:SimulatePrincipalPolicy + trust inspection):

  • permissions allowed AND trusted → return the ARN.

  • a required permission is definitively denied → raise RoleValidationError.

  • the trust policy definitively excludes the service → raise RoleValidationError.

  • permissions cannot be verified (caller lacks iam:SimulatePrincipalPolicy, the common Studio/notebook case) → return the ARN with a WARNING.

Parameters:

  • provided_role – User-supplied role name or ARN. If set, used directly.

  • role_type – One of ROLE_TYPES.

  • sagemaker_session – SageMaker session (used to get the boto session).

Returns:

IAM role ARN.

Raises:

  • RoleValidationError – The resolved role lacks required permissions/trust, or no role could be resolved.

  • ValueError – provided_role doesn’t exist, or role_type is invalid.

sagemaker.core.helper.iam_role_resolver.verify_hyperpod_connect_permissions(sagemaker_session=None, cluster_name: str | None = None) → bool | None[source]#

Verify the caller can drive the HyperPod CLI; warn (don’t block) if not.

The HyperPod CLI (connect-cluster + start-job) runs locally under the caller’s credentials, not under the job execution role. This function simulates the connect actions on the caller identity and surfaces actionable guidance when they are missing.

It logs a WARNING rather than raising so the SDK does not hard-fail in the common case where the caller cannot self-simulate (e.g. an execution role without iam:SimulatePrincipalPolicy); the CLI itself will still produce a precise error if a permission is truly absent. Callers that want to fail fast can inspect the return value.

Parameters:

  • sagemaker_session – SageMaker session (used to get the boto session).

  • cluster_name – Optional HyperPod cluster name, included in guidance.

Returns:

True — all connect actions are allowed for the caller. False — at least one connect action is denied. None — could not be determined (caller is not a role, or cannot simulate).

Contents