运行角色（Runtime Role）是 EMR Serverless Spark 作业运行时访问云资源所使用的 IAM 身份。启用后，您无需在 SparkJar、PySpark 或 Spark Connect 等作业配置中明文提供 AK/SK。系统会根据您在作业中指定的运行角色，自动获取临时凭证并将其注入作业的运行环境。

核心优势 #

• 提升安全性：避免在代码、配置或日志中明文存储 AK/SK，显著降低凭证泄露的风险。
• 简化权限管理：将数据访问权限统一收敛至 IAM 角色的策略中，便于管理员按资源（如 TOS Bucket、LAS Catalog）实现精细化的最小权限控制。

工作机制与优先级 #

EMR Serverless 支持运行角色和显式配置 AK/SK两种认证方式。运行角色和显式配置 AK/SK 同时存在时，作业优先使用 AK/SK；如果 AK/SK 验证失败或无权限，作业会直接失败，不会降级使用运行角色。因此，迁移到运行角色时，请删除作业运行参数中不再需要的长期 AK/SK。用于 API 请求签名的 SDK/API 客户端认证配置（提交身份）仍需保留。

适用场景 #

在任何不希望明文配置长期 AK/SK 的场景下，都推荐使用运行角色，运行角色尤其适用于以下环境：

在创建运行角色前，请确保满足以下条件：

• 管理权限：确保当前账号拥有创建 IAM 角色、创建或选择权限策略，以及编辑信任关系所需的权限。

• 提交身份：明确将由哪个用户或角色提交作业，并准备好其完整的 TRN。如果无法获取完整 TRN，请准备其所属主账号 ID 和准确的 IAM 用户名。同时，提交身份还需具备在目标 EMR Serverless 资源上执行作业操作的权限。

• 资源范围：明确作业运行所需的全部资源路径，包括代码与依赖、输入数据、结果输出和 checkpoint 等，以及对各路径所需的具体操作权限（如读取、写入、列举或删除）。

• 资源访问权限策略：如果已有适用的系统策略或自定义策略，可以直接记录其名称，然后创建角色。如果需要自定义策略，请先完成创建，以便后续在角色创建向导中进行选择。关于新建自定义策略的具体步骤，请参见新建自定义策略。注意权限选择与配置应遵循最小权限原则：即仅授予作业运行所必需的最小权限集。
  下表列出了常见授权资源与授权重点：

  资源类型	授权重点	校验方式
  TOS	Bucket、Prefix、GetObject、PutObject、ListObject、DeleteObject RenameObject、AbortMultipartUpload、ListMultipartUploadParts 等。	提交一个读写 TOS 的 Spark 作业，验证授权路径可正常访问，而未授权路径访问失败。
  LAS Catalog	对 Catalog、Database、Table 的读写权限，以及对底层数据存储的访问权限。	依次执行建表、读表、写表、分区等操作，分别验证只读和读写策略是否生效。
  EMR Serverless	根据需要，在访问控制中授予 EMRServerlessFullAccess 或 EMRServerlessReadOnly 权限。	授权后，作业应能正常指定运行角色；若未授权，提交作业时会报告权限错误。
  LAS	如果作业需要访问 LAS Catalog 元数据，需要在访问控制中授予 LASFullAccess 或 LASReadOnly 权限。	授权后，作业应能正常访问 LAS Catalog 元数据；若未授权，相关操作会报告权限错误。

创建运行角色 #

1. 进入 IAM 角色管理页面，点击 新建角色。
   

2. 在 新建角色 弹窗中， 选择 账号 和 当前账号，然后点击 下一步。
   

3. 在 配置角色信息 页面，填写 角色名，例如 EMRServerlessExecuteRole。根据需要填写 显示名称、 描述 和 标签，点击 下一步。

4. 在 添加权限 页面，搜索并勾选已准备好的权限策略，不确定权限时可先选择 跳过。然后完成角色创建。

配置信任关系 #

1. 打开刚创建角色的详情页面，切换到 信任关系 页签。

2. 点击 编辑信任策略，​在 Principal 字段中补充 IAM 列表，并填入实际提交作业的身份 TRN，然后点击 保存。

   注意

   信任策略必须同时包含 Service 和 IAM 身份。如果忽略对提交者 IAM 身份的校验，任何拥有权限的账号或角色都可能指定该运行角色，从而引发越权访问风险。

   示例：

   {
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["sts:AssumeRole"],
         "Principal": {
           "Service": ["emr_serverless"],
           "IAM": [
             "trn:iam::<account-id>:root",
             "trn:iam::<account-id>:user/<sub-user-name>",
             "trn:iam::<account-id>:role/<submit-role-name>"
           ]
         }
       }
     ]
   }
   

3. 在角色详情的 基本信息 中，核对 最大会话时间。建议将其设置为 12 小时。请注意，此时间是临时凭证有效期的上限，而非作业本身的最长运行时长。对于长时作业，请确保运行环境支持凭证自动刷新。如需修改，可使用该字段旁的编辑功能。

4. 复制完整的 角色 TRN（例如 trn:iam::<ROLE_ACCOUNT_ID>:role/EMRServerlessExecuteRole），后续提交作业时将会用到。

指定运行角色 #

创建并配置角色后，即可在提交作业时指定该角色。指定角色支持以下两种途径：

• 控制台：界面可视化操作，适用于人工提交和调试；
• API：程序化调用，适用于调度系统、CI/CD、平台集成和批量提交。

通过控制台 #

1. 进入 EMR Serverless 的 作业中心。
2. 在创建或编辑作业的页面，找到 运行角色 配置项。
3. 从下拉列表中选择您已准备好的运行角色。

详细的作业提交步骤，请参见 SparkJar 作业 和 PySpark 作业。

通过 API #

调用 API 提交作业时，您需要在请求体（Request Body）中包含运行角色的完整 TRN。具体的参数字段名和位置取决于您调用的 API 版本和作业类型。
示例：在 conf 参数中指定运行角色
以下示例展示了如何在提交 Spark 作业时，通过 conf 配置块内的 serverless.spark.runtime.role 参数来指定运行角色。

{
    "name": "test_use_role",
    "jar": "tos:///jobs/demo.py",
    "mainArgs": [
        "arg0",
        "arg1"
    ],
    "conf": {
        "serverless.spark.runtime.role": "trn:iam::${accountId}:role/EMRServerlessExecuteRole",
        "tqs.spark.jar.resource": "tos:///jobs/demo.py",
        "tqs.spark.jar.class": "",
        "tqs.spark.jar.class.args": "[\"arg0\",\"arg1\"]",
        "tqs.query.engine.type": "SparkJar"
    },
    "queue": {},
    "sync": false
}

详细的作业提交步骤，请参见 SparkJar 作业 和 PySpark 作业。

作业提示服务或用户未被信任 #

先区分失败发生在提交阶段还是运行阶段。提交阶段的 NoPermission 多数来自服务身份或提交身份不在运行角色信任策略中；运行阶段访问 TOS、LAS 时失败，则优先检查运行角色的资源权限。

能提交作业，但无法读取 TOS 或 LAS 表 #

先按日志确认失败资源和实际鉴权身份。典型错误包括未授权 Bucket、Prefix 范围过窄、跨租户 Bucket Policy 未放行、Executor 侧仍使用旧 AK/SK 配置。

配置了运行角色，但仍然使用旧密钥 #

检查作业运行参数中是否仍显式填写 AK/SK。两者同时存在时旧密钥优先。为保障存量用户兼容性，服务端保留原 AK/SK 提交链路；存量作业迁移时应先灰度验证权限策略、错误信息和审计链路。