凭证分发概览

借助 Lakehouse 运行时目录中的凭证分发模式,您可以将 Cloud Storage 访问权限委托给查询引擎,并在目录、命名空间和表级别为 Apache Iceberg 表强制执行精细的 Identity and Access Management (IAM) 政策。您无需授予直接存储桶权限,而是将 Apache Iceberg REST Catalog 端点配置为针对授权表路径提供短期、范围缩小的存储令牌。自动表管理也需要此模式。

何时使用凭据发放

以下是一些常见使用场景:

  • 强制执行表级访问权限,无需存储桶级角色:向分析师和工作负载授予对特定 Apache Iceberg 表的访问权限,同时阻止直接访问底层 Cloud Storage 存储桶或同级表目录。
  • 集中管理多个查询引擎的访问权限治理:使用短期、路径范围的令牌,在 BigQuery、Managed Service for Apache Spark、开源 Apache Spark 和 Trino 中应用一致的 IAM 政策。
  • 在服务边界内隔离仓库存储桶:将表数据存储在受 VPC Service Controls 保护的 Cloud Storage 存储桶中,同时通过单个目录端点服务账号授权存储读取和写入。

凭证分发的工作原理

使用凭据发放模式时,操作序列会在访问存储空间之前强制执行 IAM 政策。下图展示了查询引擎如何从湖仓一体运行时目录获取降级存储令牌,以便直接在 Cloud Storage 中安全地读取和写入数据:

查询引擎从 Lakehouse 运行时目录获取范围缩小的存储令牌,以便在 Cloud Storage 中读取和写入数据。
委托 Cloud Storage 访问权限的凭据分发工作流。

上图中显示的操作顺序如下:

  1. 请求:用户向支持的引擎(例如 Spark 或 BigQuery)提交 SQL 语句,例如查询、DML 或 DDL 操作。
  2. 元数据查找:引擎向 Lakehouse 运行时目录发送请求以解析表。
  3. 身份验证和政策:Lakehouse 运行时目录会对用户进行身份验证,并检查其对 Lakehouse 资源的 IAM 权限。
  4. 响应:由于凭证分发模式已启用,Lakehouse 运行时目录会将元数据和短期存储令牌(范围缩小的存储凭证)返回给引擎。令牌的作用域限定为与表关联的路径,并缩小到所需的最低权限(例如,对不需要写入文件的查询的只读访问权限)。
  5. 访问:引擎使用此令牌直接从 Cloud Storage 读取或写入特定授权文件。
  6. 计算:引擎处理数据或执行操作,并返回结果。

启用自动表管理 (gcp.biglake.table-management.enabled) 后,压缩、快照过期和垃圾回收等后台维护任务会使用目录的自动预配服务账号直接向 Cloud Storage 进行身份验证并更新底层数据文件。

支持的引擎

如需将凭据分发与查询引擎搭配使用,您必须在 Lakehouse 运行时目录中以凭据分发模式配置 Apache Iceberg REST 目录端点。Apache Hive 目录端点不支持凭证发放。

  • 开源引擎:Spark 和 Trino 等受支持的引擎使用 Lakehouse 运行时目录提供的短期存储令牌。您的客户端应用必须在 X-Iceberg-Access-Delegation 标头中指定对凭据发放的支持。
  • BigQuery:BigQuery 使用 Cloud Storage 访问权限的供应商凭据,而不是最终用户凭据。

所需的角色

如需确保自动预配的目录端点服务账号具有在凭证分发模式下读取和写入表数据所需的权限,请让您的管理员为自动预配的目录端点服务账号授予以下 IAM 角色:

  • 在 Cloud Storage 中读取和写入表数据:针对所有关联的 Cloud Storage 存储桶的 Storage Object User (roles/storage.objectUser) 角色

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您的管理员还可以通过自定义角色或其他预定义角色向自动预配的目录端点服务账号授予所需的权限。

为确保运行查询引擎作业的服务账号具有获取具有写入范围的已售凭据所需的权限,请让您的管理员为运行查询引擎作业的服务账号授予以下 IAM 角色:

  • 从查询引擎作业(例如 Managed Service for Apache Spark 或 Dataflow)获取具有写入范围的自动售卖凭据:目录、命名空间、表或项目的 BigLake Editor (roles/biglake.editor) 角色

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您的管理员也可以通过自定义角色或其他预定义角色为运行查询引擎作业的服务账号授予所需的权限。

如果您使用 Google Cloud 控制台,点击设置存储桶权限会验证关联存储桶的 Storage Object User 角色 (roles/storage.objectUser)。对于 Google Cloud CLI、Terraform 或 REST API,您必须手动向自动预配的目录端点服务账号授予此角色。

自动预配的目录端点服务账号的创建最终会保持一致。服务账号需要一些时间才能在整个系统中传播。如果您在创建服务账号后立即尝试向其授予角色,请求可能会失败。如需详细了解访问权限更改传播的平均时间,请参阅访问权限更改传播。

针对受 FGAC 保护的表的凭证分发护栏

当行级安全或列级数据政策(精细访问权限控制,即 FGAC)保护使用凭证发放模式的目录中的 Apache Iceberg 表时,直接 Cloud Storage 文件访问会绕过 BigQuery 中的查询时政策评估。

为防止未经授权的数据泄露,Apache Iceberg REST 目录端点会针对受 FGAC 保护的表上的凭据发放请求返回 403 Forbidden HTTP 状态代码,除非调用主账号对该表具有完全访问权限:

  • 对所有受保护列的未遮盖(原始)数据访问权限:表中的每个受保护列还必须附加 RAW_DATA_ACCESS_POLICY。使用调用主账号的 IAM v2 主账号标识符(例如 principal://iam.googleapis.com/projects/-/serviceAccounts/SA_EMAIL),向其授予对该 RAW_DATA_ACCESS_POLICY 数据政策的 FINE_GRAINED_READ 权限。
  • 未过滤的行访问权限(所有行):如果表附加了行级访问权限政策,请向调用主账号授予具有 FILTER USING (TRUE) 子句的行级访问权限政策。

如需配置服务账号,以便从开源引擎(例如 Spark、Trino 或 Apache Flink)读取或写入受 FGAC 保护的表,请参阅为受 FGAC 保护的表配置开源引擎凭据。

将 VPC Service Controls 与凭证发放搭配使用

在 VPC Service Controls 服务边界内,将 Apache Iceberg REST Catalog 端点与 Cloud Storage 存储桶搭配使用时,您可以支持以下用例:

  • 在受保护的存储桶中创建和修改 Apache Iceberg 表:当仓库存储桶位于服务边界内时,从 BigQuery、Managed Service for Apache Spark、Spark 或 Trino 运行 CREATE TABLE 或 DML 语句。
  • 在存储边界内委托精细的表读取:使用短期、范围缩小的存储令牌强制执行表级 IAM 政策,而无需向最终用户或查询运行时授予对边界保护的存储桶的直接 IAM 角色。

在凭证分发模式下,查询引擎和 Lakehouse 会使用为目录端点的自动预配服务账号 (blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.) 颁发的凭证向 Cloud Storage 进行身份验证。由于此服务代理属于服务边界之外的 Google 管理的项目,因此每当存储桶项目的边界限制 storage.googleapis.com 时,Cloud Storage 都会将使用其凭证进行身份验证的请求评估为边界入站流量。即使目录端点、查询作业和存储桶位于同一项目和服务边界内,此评估也适用。

如需允许访问,请在 Access Context Manager 中,在保护存储桶项目的边界上配置入站流量规则,并进行以下设置:

  • 来源身份: serviceAccount:blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.
  • 目标项目:存储桶项目 (projects/BUCKET_PROJECT_NUMBER)
  • 服务:storage.googleapis.com(包含所有方法 ['*'])或特定支持的服务方法

以下 ingress.yaml 示例允许目录端点的服务账号访问存储桶项目中的 storage.googleapis.com:

- ingressFrom:
    identities:
    - serviceAccount:CATALOG_ENDPOINT_SERVICE_ACCOUNT
    sources:
    - accessLevel: '*'
  ingressTo:
    operations:
    - serviceName: storage.googleapis.com
      methodSelectors:
      - method: '*'
    resources:
    - projects/BUCKET_PROJECT_NUMBER

替换以下内容:

  • CATALOG_ENDPOINT_SERVICE_ACCOUNT:目录端点的自动预配服务账号邮箱 (blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.)。如需检索此邮箱,请描述目录端点:

    gcloud biglake iceberg catalogs describe CATALOG_ID \
        --project=PROJECT_ID \
        --format='value(biglake-service-account)'
    

    在此命令中,CATALOG_ID 是目录端点的 ID,PROJECT_ID 是包含目录端点的项目的 ID。

  • BUCKET_PROJECT_NUMBER:包含 Cloud Storage 存储桶的项目的数字项目编号。

如果表创建或查询请求被 VPC Service Controls 屏蔽,则出错提示会包含 vpcServiceControlsUniqueIdentifier 值。通过将 protoPayload.metadata.vpcServiceControlsUniqueId 与该标识符进行匹配,在 Cloud Audit Logs 中搜索政策拒绝审计日志,并检查 blirc-... 主体 的 ingressViolations。如需了解详情,请参阅从审计日志中检索 VPC Service Controls 错误。

后续步骤