排查跨云数据访问问题

使用 Lakehouse 访问跨云数据时，您可以诊断和解决后台元数据刷新、通过跨云互连进行专用互连路由以及 Service Directory 端点解析方面的问题。解决这些问题有助于保持联合表元数据处于最新状态，并恢复私有跨云查询执行。

数据和资源已过时或未更新

Lakehouse 联合目录会根据刷新间隔同步远程云中的元数据。如果联合目录包含许多资源（共享、架构、命名空间和表），则联合目录的后台元数据刷新可能需要更长时间。如果上一次刷新超时，则系统会跳过当前刷新，并在下一个预定时间间隔运行下一次刷新。

如果查询的数据显示为过时，则联合目录的后台元数据刷新可能正在超限运行或失败。如果您删除了远程云中的资源，则在下次完成后台元数据刷新时，该资源会从 Lakehouse 中移除。

在 Google Cloud 控制台的 Lakehouse 页面中，或使用 Google Cloud CLI 查看联合目录的后台元数据刷新状态：

前往 Lakehouse

gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID"

gcloud biglake delta-sharing catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID"

AWS Glue Data Catalog 问题排查

如果您在 Lakehouse 运行时目录中的 AWS Glue 联合目录上配置 --metadata-service-directory-name 后，后台元数据刷新失败，请检查以下内容：

  • 验证私有目录端点映射：确认用于后台元数据刷新的混合连接网络端点组 (NEG) 或 Service Directory 端点指向 TCP 端口 443 上的 AWS Glue 接口 VPC 端点 (com.amazonaws.AWS_REGION.glue) 的专用 IP 地址，而不是 Amazon S3 接口 VPC 端点。
  • 验证 IAM 角色信任政策和权限：确认您的 Amazon Web Services (AWS) IAM 角色信任政策允许联合目录的Google Cloud 服务账号 (biglake-service-account) 担任该角色 (sts:AssumeRoleWithWebIdentity)，并且该角色有权读取您的 AWS Glue 数据库和表元数据（glue:GetDatabase、glue:GetDatabases、glue:GetTable、glue:GetTables）。
  • 检查 VPC 端点安全组规则：确认附加到 AWS Glue 接口 VPC 端点的 AWS 安全组允许来自Google Cloud 虚拟私有云 (VPC) 子网和仅代理子网 CIDR 范围的 TCP 端口 443 上的入站 HTTPS 流量。

Databricks Unity Catalog 问题排查

在后台元数据刷新期间，表为空或未被发现

如果联合目录后台元数据刷新指示已完成（例如 Refresh successfully completed），但联合目录中的表未显示或列出表返回 0 项，请检查以下内容：

  • EXTERNAL USE SCHEMA 权限：验证 Databricks 服务主体是否已在 Databricks Unity Catalog 中获得对目标架构或目录的 EXTERNAL USE SCHEMA 权限。如果没有此权限，后台元数据刷新和查询凭据发放将会失败。
  • 外部数据访问设置：验证 Databricks Unity Catalog 元存储区上是否已启用外部数据访问。
  • 外部位置：验证您的 Databricks Unity Catalog 和表使用的是外部存储位置（例如 Amazon S3、Microsoft Azure Data Lake Storage Gen2 或 Cloud Storage），而不是默认存储。

通过跨云互连进行的后台元数据刷新失败

如果在 Lakehouse 运行时目录中为 Databricks Unity Catalog 配置了 --metadata-service-directory-name，但后台元数据刷新失败，请验证以下内容：

  • 工作区专用端点目标：确认您的元数据 Service Directory 端点或内部区域代理网络负载均衡器后端以 Databricks 工作区 AWS PrivateLink 接口端点或 Azure 专用端点的专用 IP 地址（TCP 端口 443）为目标，而不是以远程存储端点为目标，并且 --unity-instance-name 与您的工作区主机名匹配。
  • Workspace 专用访问权限设置：如果您的 Databricks 工作区强制执行专用访问权限设置或 IP 访问权限列表，请验证是否允许通过专用端点从 Google CloudVPC 网络传入的请求。

后台元数据刷新失败或返回 401 Unauthorized

如果后台元数据刷新状态报告错误（例如 401 Unauthorized）或无法发现架构，请验证以下内容：

  • 服务主体联合政策：在 Databricks 账号控制台（账号设置 > 安全 > 身份提供方设置 > 联合政策）中，验证服务主体联合政策是否配置如下：
    • 颁发者网址： https://accounts.google.com
    • 主题：联合目录的 biglake-service-account 服务账号的数字唯一 ID（而非其邮箱）。
    • 受众群体：https://accounts.cloud.databricks.com
  • Secret Manager 权限：如果使用基于 Secret 的身份验证，请验证 Secret 是否存在于指定的区域位置，以及 biglake-service-account 是否已被授予 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
  • 服务主体权限：确保 Databricks 服务主体对目标工作区和 Databricks Unity Catalog 具有读取权限。

交互式查询失败，并显示“401 未经授权”或令牌验证错误

启用用户身份联合后，交互式查询会动态生成最终用户身份令牌，并根据 Databricks 中的账号级联合政策对其进行验证。如果查询失败并显示 401 Unauthorized 或令牌验证错误，而后台元数据刷新正常，请检查以下内容：

  • 已配置账号级联合政策：确保在 Databricks 账号控制台中的账号设置 > 安全 > 身份提供方设置 > 联合政策下创建了账号级联合政策（不同于服务主体政策）。
  • 区分大小写的受众群体匹配：Databricks 会严格区分大小写地验证 aud（受众群体）声明。验证 Databricks 账号级联合政策中的受众群体字段是否与从联合目录中检索到的元存储区级 audience 声明 (databricks-METASTORE_ID) 的大小写完全一致。任何大小写差异（例如，在 databricks- 前缀或 Metastore UUID 中）都会导致 Databricks 令牌验证拒绝查询并显示 401 Unauthorized。
  • 颁发者网址：验证颁发者网址是否与联合目录中的确切 issuer-url 声明匹配：https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID。
  • Metastore 受众群体可用性：只有在第一个后台元数据刷新周期完成后（通常在 5 分钟内），系统才会填充 metastore 范围的 audience 声明。如果您使用占位值配置政策，或者在第一个刷新周期完成之前配置政策，查询将会失败。在配置政策之前，请运行 gcloud biglake iceberg catalogs describe，验证联合目录上的 audience 声明是否已填充。

Snowflake Horizon Catalog 问题排查

后台元数据刷新失败，并显示代码 16（未经身份验证）

如果 Snowflake Horizon Catalog 的后台元数据刷新失败，并显示状态 Code 16 (UNAUTHENTICATED)，请验证以下内容：

  • Secret 载荷格式设置：确保 Secret Manager 中的 Secret 令牌包含所需的 JSON 结构 ({"client_secret": "SNOWFLAKE_PAT_TOKEN", "scope": "session:role:SNOWFLAKE_ROLE"})，而不是原始程序化访问令牌 (PAT) 字符串。
  • 令牌过期和权限：验证 Snowflake PAT 是否有效，以及关联的用户和角色是否有权读取目标目录和数据库。
  • PrivateLink 或 Private Link 账号标识符：如果您将 --metadata-service-directory-name 配置为使用 AWS PrivateLink 或 Azure Private Link 通过跨云互连同步元数据，请验证 --snowflake-account-identifier 指定的是您的 Snowflake .privatelink 账号标识符（例如 myorg-myaccount.privatelink），而不是您的公共账号标识符。
  • 网络政策：如果后台元数据刷新通过公共互联网连接，并且 Snowflake 网络政策处于有效状态，请验证 Google 的出站流量 IP 地址范围（来自 goog.json）是否包含在网络政策的允许 IP 列表中。

通过跨云互连进行的后台元数据刷新失败

如果在 Lakehouse 运行时目录中为 Snowflake Horizon Catalog 配置了 --metadata-service-directory-name，但后台元数据刷新失败，请验证以下内容：

  • Snowflake 专用端点目标：确认您的元数据 Service Directory 端点或内部区域级代理网络负载均衡器后端指向 Snowflake AWS PrivateLink 接口端点或 Azure 专用端点在 TCP 端口 443 上的专用 IP 地址，而不是远程对象存储区端点。
  • 私有账号标识符：确认 --snowflake-account-identifier 使用您的 .privatelink 账号标识符（例如 myorg-myaccount.privatelink）。

连接性或路由问题

如果您在通过跨云互连路由流量时遇到查询传输或后台元数据刷新失败，请验证以下内容：

  • 验证路由传播：检查Google Cloud 中的 Cloud Router 路由器，验证它是否已获知您的 AWS VPC 或 Azure 虚拟网络 (VNet) 前缀。检查您的 AWS 或 Azure 路由表，验证它们是否具有返回 Google CloudVPC 网络的路由。如果您使用内部区域级代理网络负载均衡器，请验证 Cloud Router 是否通过自定义 BGP 路由通告来通告代理专用子网 CIDR 范围。
  • 检查内部负载均衡器的健康状况：在 Google Cloud 控制台中，前往网络服务 > 负载均衡，验证传输和元数据后端服务的混合连接网络端点组 (NEG) 后端是否运行正常。如果后端运行状况不佳，请检查专用互连连接和远程安全规则。
  • 测试连接性 Google Cloud：在与内部负载均衡器或 Service Directory 端点相同的 Google Cloud VPC 网络和子网中创建测试虚拟机实例，并测试与 TCP 端口 443 上的 AWS 弹性网络接口 (ENI) 或 Azure 专用端点网络接口 (NIC) IP 地址的连接（例如，使用 curl 或 nc）。
  • 验证 Service Directory 配置和权限：确认在 --service-directory-name（用于查询传输）和 --metadata-service-directory-name（用于后台元数据刷新）中配置的 Service Directory 服务与联合目录位于同一 Google Cloud 区域。如果联合目录的后台元数据刷新失败并显示 Permission 'servicedirectory.services.resolve' denied 错误，请验证联合目录的唯一服务账号 ID（biglake-service-account 字段）在托管 Service Directory 服务的每个项目上是否具有 roles/servicedirectory.viewer 和 roles/servicedirectory.pscAuthorizedService 角色。
  • 检查安全群组和防火墙规则：验证Google Cloud 防火墙规则、AWS 安全群组和 Azure 网络安全群组 (NSG) 是否允许在 Google Cloud VPC CIDR 范围（包括任何代理专用子网 CIDR 范围）与远程专用端点之间通过端口 443 传输 TCP 流量。