为 Databricks Unity Catalog 设置跨云连接

通过与 Amazon Web Services (AWS)、Microsoft Azure 或 Google Cloud 上的 Databricks Unity Catalog 建立跨云连接，您可以直接在 Google Cloud中查询该目录中的数据。此功能通过将外部数据源与现有Google Cloud 环境集成，统一了数据分析。

设置连接后，您可以在无边界 Lakehouse 中管理对联合数据的访问权限。

准备工作

1. 查看 Lakehouse 概览，了解 Lakehouse 如何管理对数据的访问权限。
2. 阅读访问跨云数据，了解其工作原理。
3. 查看支持的目录，验证支持的配置。
4. 了解如何使用区域级 Secret Manager Secret。如需使用基于密文的身份验证设置具有 Databricks Unity Catalog 的 Lakehouse，则必须执行此操作。
5. 可选：如果您计划通过 Google Cloud虚拟私有云 (VPC) 网络与远程云网络（AWS VPC 或 Azure VNet）之间的专用互连来路由查询读取或后台元数据刷新，请验证您是否拥有远程提供商的有效账号，预配专用跨云互连或合作伙伴跨云互连（适用于 AWS），与 Cloud Router 路由器建立 BGP 会话，并验证您是否在两个云环境中都拥有所需的 Identity and Access Management (IAM) 权限。
6. 可选：如果您计划使用用户身份联合在查询中传播最终用户身份，请确保：
   • 您的身份提供方 (IdP) 已配置为在身份验证令牌中将用户的 email 声明作为 sub 主题声明发出。
   • 您的 Databricks 账号已配置为通过最终用户的电子邮件地址识别最终用户，以便 Databricks 识别用户。您可以在 Databricks 中配置用户，方法是使用 SCIM 从身份提供方同步用户（推荐），或在 Databricks 账号控制台中手动添加用户。

7. Verify that billing is enabled for your Google Cloud project.

8. Enable the BigLake, Secret Manager APIs, if any are not already enabled.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

所需的角色

如需获得设置跨云访问权限所需的权限，请让管理员向您授予项目的以下 IAM 角色：

• 管理 Lakehouse 目录：BigLake Admin (roles/biglake.admin)
• 管理 Secret（如果使用基于 Secret 的身份验证）：Secret Manager Admin (roles/secretmanager.admin)
• 通过专用互连路由流量（用户）：Compute Network Admin (roles/compute.networkAdmin)
• 通过专用互连路由流量（目录服务账号）：
  • Service Directory Viewer (roles/servicedirectory.viewer)
  • Service Directory PSC Authorized Service (roles/servicedirectory.pscAuthorizedService)

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注意： 如果使用基于 Secret 的身份验证，为遵循最小权限原则并避免授予对项目中所有 Secret 的访问权限，请让 Secret Manager 管理员为您创建 Secret，并授予您仅修改 Lakehouse 的该特定 Secret 的权限。

限制和注意事项

本部分列出了访问跨云数据的限制和注意事项。

• VPC Service Controls：如果包含联合目录端点或底层 Cloud Storage 存储桶的项目位于 VPC Service Controls 服务边界内，则您必须配置出站流量或入站流量规则。如需了解详情，请参阅将 VPC Service Controls 与联合目录端点搭配使用。
• Cross-跨云互连支持的云服务商：AWS 和 Azure 支持使用专用互连来路由查询传输和/或后台元数据刷新。您可以使用专用 Cross-Cloud Interconnect（适用于 AWS 或 Azure）或合作伙伴 Cross-Cloud Interconnect（适用于 AWS）。
• 网络路由：如果您没有为查询传输或后台元数据刷新配置专用互连，则相应的流量会通过 TLS 经由公共互联网进行路由。通过公共互联网路由查询读取可能会导致远程云服务商收取更高的出站流量费用，并且性能的可预测性较低。
• Databricks Unity Catalog 配置：
  • 仅支持使用 AWS 上的外部位置、Azure 上的外部位置或 Google Cloud上的外部位置的 Databricks Unity Catalog。不支持使用 AWS 上的默认存储、Azure 上的默认存储或 Google Cloud上的默认存储的 Unity Catalog。
  • 您必须在 Unity Catalog 使用的 metastore 上启用外部数据访问权限，该功能默认处于停用状态。
  • 您必须向 Databricks 服务主账号授予对目标架构或目录的 EXTERNAL USE SCHEMA 权限，才能为外部数据访问启用凭据发放。如果没有此权限，后台元数据刷新和查询凭据发放将会失败。
• 只读：Lakehouse 中的联合目录是远程目录的只读视图。不支持资源操作（例如创建、更新或删除资源），必须直接在远程目录中执行。
• 数据新鲜度：联合目录的 --refresh-interval 标志决定了元数据的同步频率。该值必须为 0s（停用）或至少为 300s（5 分钟）。目录的后台元数据刷新可能需要更长时间，具体取决于命名空间和表资源的数量。如果上一次刷新超时，则系统会跳过当前刷新，并安排在下一个间隔时间进行下一次刷新。 查询使用最近同步的目录元数据，因此在远程目录中所做的更改（例如新表、架构更新或新提交的数据）在 Lakehouse 中不可见，直到下一次后台元数据刷新完成。
• Lakehouse 缓存：默认情况下，跨云缓存处于停用状态 (--cross-cloud-cache=disabled)。您可以在联合目录或连接级别启用或停用缓存。缓存不支持客户管理的加密密钥 (CMEK)；缓存的文件使用 Google-owned and Google-managed encryption keys进行加密。如果对查询中的表强制执行 constraints/gcp.restrictNonCmekServices 组织政策限制条件，则系统会自动为该查询停用缓存。如需了解详情，请参阅智能缓存。
• 数据驻留和合规性：在联合目录或连接上启用跨云缓存后，Lakehouse 会将缓存的静态文件临时存储在 Google Cloud 查询运行的区域。如果您的远程云文件位于其他管辖区，请在启用跨区域缓存之前，验证该功能是否符合贵组织的数据驻留和合规性要求。

常规工作流程

如需访问跨云数据，请按照以下常规步骤操作：

• 设置跨云互连（可选）：在 Google Cloud VPC 网络与远程云服务提供商之间配置专用连接。
• 设置联合：配置身份验证并在 Lakehouse 中创建联合目录。
  • 基本身份验证（必需）：配置 OpenID Connect (OIDC)（推荐）或基于 Secret 的身份验证，以允许 Lakehouse 使用目录的服务账号执行后台元数据刷新。
  • 用户身份联合（可选）：启用用户身份联合 (--federated-catalog-identity-mode="user-identity-federation")，以允许使用经过身份验证的最终用户身份执行查询。这样，Databricks Unity Catalog 就可以将查询归因于最终用户、强制执行权限并生成审核日志。
• 验证连接：验证 Lakehouse 是否可以连接到远程目录。
• 查询数据：使用 BigQuery 或 Managed Service for Apache Spark 对联合数据运行查询。您可以选择在联合目录上启用跨云缓存，以帮助降低跨云出站流量费用并加快后续查询。如需了解详情，请参阅查询远程数据。
• 配置权限：使用 IAM 管理谁可以查看和查询联合数据。

设置跨云互连（可选）

默认情况下，查询数据读取和后台元数据刷新都会通过公共互联网使用 TLS 进行传输。为了帮助增强网络隔离、提供可预测的延迟时间并降低数据传输费用，您可以在 Google CloudVPC 网络与远程云网络（AWS VPC 或 Azure 虚拟网络 [VNet]）之间配置专用互连。

您可以预配以下任一专用互连选项：

• 专用 Cross-Cloud Interconnect：与 AWS 或 Azure 的专用物理连接。
• 合作伙伴 Cross-Cloud Interconnect：通过受支持的服务提供商连接到 AWS。

在 Google Cloud中的 Cloud Router 路由器与远程云网络之间建立 BGP 会话，以实现路由交换。

您可以根据安全和费用要求，为以下任一或两个流量路径配置通过跨云互连的专用路由：

• 查询传输 (--service-directory-name)：将查询读取从 BigQuery 或开源引擎路由到远程对象存储（Amazon S3 或 Azure Data Lake Storage Gen2 [ADLS Gen2]），以帮助降低跨云出站流量费用并保持查询延迟时间可预测。
• 后台元数据刷新 (--metadata-service-directory-name)：将控制平面后台元数据刷新和身份验证请求从 Lakehouse 运行时目录路由到远程 Databricks Unity Catalog 专用端点，例如，当远程目录限制公共互联网访问时。

如果您通过跨云互连路由查询传输和后台元数据刷新，请针对远程存储端点和远程目录端点分别完成一次专用端点、路由和 Service Directory 目录服务步骤。两个 Service Directory 服务必须与联合目录位于同一 Google Cloud 区域，并且可以共享同一仅代理子网和 Service Directory 命名空间。

您可以使用以下两种架构流程之一，将流量从 Service Directory 路由到远程专用端点：

• 内部区域级代理网络负载均衡器路由：使用 Google Cloud内部区域级代理网络负载均衡器，在指向远程私有端点 IP 地址（AWS 弹性网络接口 [ENI] 或 Azure 私有端点网络接口 [NIC]）的混合连接网络端点组 (NEG) 之间分配请求。此流程是合作伙伴跨云互连的必需流程，也是专用跨云互连的推荐流程，可实现负载均衡、可伸缩性和高可用性。
• 直接端点路由：将 Service Directory 直接连接到单个远程专用端点 IP 地址。此流程仅适用于专用跨云互连，合作伙伴跨云互连不支持此流程。

选择符合您架构要求的配置流程：

内部区域级代理网络负载均衡器

如需配置在远程专用端点 IP 地址之间分配请求的内部区域级代理网络负载均衡器，请按照以下步骤操作：

配置远程云专用端点

在通过跨云互连连接到 Google Cloud VPC 网络的远程网络和子网中创建专用端点，并记下分配给每个端点的专用 IP 地址：

• 对于专用查询传输（远程对象存储区）：在 AWS 上，在 AWS VPC 中创建 Amazon S3 的接口 VPC 端点 (com.amazonaws.AWS_REGION.s3)，并记下 ENI 专用 IP 地址。在 Azure 上，针对 Azure VNet 中的 ADLS Gen2 存储账号（dfs 或 blob）创建适用于 Azure Storage 的 Azure 专用端点，并记下 NIC 专用 IP 地址。
• 对于专用后台元数据刷新（远程目录）：在 AWS 上，在 AWS VPC 中为 Databricks 工作区配置 AWS PrivateLink 接口端点，并记下 ENI 专用 IP 地址。在 Azure 上，在 Azure VNet 中创建以 Azure Databricks 工作区为目标的 Azure 专用端点，并记下 NIC 专用 IP 地址。
• 入站安全规则：验证附加到专用端点的 AWS 安全组或 Azure 网络安全组 (NSG) 是否允许来自 Google Cloud VPC CIDR 范围的端口 443 上的入站 TCP 流量。添加 Google Cloud 代理专用子网的 CIDR 范围，以允许健康检查和转发的流量。

配置 Google Cloud 网络

重要提示： 您必须在跨云互连 VLAN 连接所在的同一区域中部署本部分中的所有 Google Cloud 资源（健康检查、混合 NEG、后端服务和负载均衡器）。如果它们位于不同的区域，则流量无法路由到远程端点。

运行以下命令，以配置内部负载均衡器。如果您要通过跨云互连路由查询传输和后台元数据刷新，请为存储端点和目录端点配置单独的后端服务、目标 TCP 代理和转发规则。如需了解高级配置，请参阅为混合端点设置内部区域级代理网络负载均衡器。

注意： 在开始之前，请确保您已在相应区域的 VPC 网络中配置了代理专用子网。如果您没有，请创建一个：

gcloud compute networks subnets create PROXY_SUBNET_NAME \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=REGION \
    --network=VPC_NETWORK \
    --range=PROXY_SUBNET_RANGE

替换以下内容：

• PROXY_SUBNET_NAME：代理专用子网的名称。
• PROXY_SUBNET_RANGE：VPC 网络中未使用的 CIDR 范围（例如 10.129.0.0/23）。

重要提示： Cloud Router 不会自动使用 BGP 通告代理专用子网。您必须手动配置 Cloud Router，以使用自定义路由通告向远程网络通告 PROXY_SUBNET_RANGE，以便来自远程端点的响应流量可以路由回负载均衡器。

1. 创建区域级 TCP 健康检查：

   gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
       --region=REGION \
       --port=443

   替换以下内容：

   • HEALTH_CHECK_NAME：健康检查的名称。
   • REGION： Google Cloud 区域（例如 us-east4）。

2. 创建混合连接网络端点组 (NEG) 并添加端点：

   为每个可用区创建一个混合 NEG (NON_GCP_PRIVATE_IP_PORT)：

   gcloud compute network-endpoint-groups create NEG_NAME \
       --network-endpoint-type=NON_GCP_PRIVATE_IP_PORT \
       --zone=ZONE \
       --network=VPC_NETWORK

   将远程端点 ENI 或 NIC 的专用 IP 地址添加到混合 NEG：

   gcloud compute network-endpoint-groups update NEG_NAME \
       --zone=ZONE \
       --add-endpoint="ip=REMOTE_ENDPOINT_IP,port=443"

   替换以下内容：

   • NEG_NAME：混合 NEG 的名称。
   • ZONE： Google Cloud 可用区（例如 us-east4-a）。此可用区必须位于跨云互连 VLAN 连接的区域内。
   • VPC_NETWORK：您的 VPC 网络的名称。
   • REMOTE_ENDPOINT_IP：该可用区中远程存储或远程目录专用端点的专用 IP 地址。

   如果您的远程端点有多个专用 IP 地址分布在不同可用区，请重复这些命令，为每个可用区创建混合 NEG 并添加端点。

3. 创建和配置后端服务：

   创建具有内部代管式负载均衡功能的区域后端服务：

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --protocol=TCP \
       --region=REGION \
       --health-checks=HEALTH_CHECK_NAME \
       --health-checks-region=REGION

   将混合 NEG 添加到后端服务：

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
       --region=REGION \
       --network-endpoint-group=NEG_NAME \
       --network-endpoint-group-zone=ZONE \
       --balancing-mode=CONNECTION \
       --max-connections=MAX_CONNECTIONS

   替换以下内容：

   • BACKEND_SERVICE_NAME：后端服务的名称。
   • NEG_NAME：您在上一步中创建的混合 NEG 的名称。
   • ZONE： Google Cloud 可用区（例如 us-east4-a）。
   • MAX_CONNECTIONS：后端的并发连接数上限（例如 100）。

   对您创建的每个混合 NEG 重复执行 add-backend 命令。

4. 配置负载均衡器前端：

   创建目标 TCP 代理：

   gcloud compute target-tcp-proxies create TARGET_PROXY_NAME \
       --backend-service=BACKEND_SERVICE_NAME \
       --region=REGION

   创建转发规则以将流量路由到目标代理：

   gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --network=VPC_NETWORK \
       --subnet=VPC_SUBNET \
       --ports=443 \
       --region=REGION \
       --target-tcp-proxy=TARGET_PROXY_NAME \
       --target-tcp-proxy-region=REGION \
       --allow-global-access

   替换以下内容：

   • TARGET_PROXY_NAME：目标代理的名称。
   • FORWARDING_RULE_NAME：转发规则的名称。
   • VPC_SUBNET：您的 VPC 子网的名称。

为负载均衡器创建转发规则后，请记下分配给它的内部 IP 地址。这是您的ILB_IP_ADDRESS。

配置 Service Directory

在 Service Directory 中注册内部负载均衡器的 IP 地址，以便 Lakehouse 能够以不公开方式发现并路由到该地址。如果您为查询传输和后台元数据刷新配置了单独的负载均衡器转发规则，请为每个转发规则 IP 地址创建单独的 Service Directory 服务和端点。

1. 为远程专用端点创建命名空间：

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   替换以下内容：

   • NAMESPACE：命名空间的唯一标识符。
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • REGION： Google Cloud 区域（例如 us-east4）。此区域必须与联合目录所在的区域相同。

2. 在 Service Directory 命名空间中创建服务：

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   替换以下内容：

   • SERVICE_NAME：服务的唯一标识符（在注册后台元数据刷新端点时，请创建一个单独的服务名称，例如 METADATA_SERVICE_NAME）。

3. 在服务中为负载均衡器转发规则创建端点：

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --project=PROJECT_ID \
       --namespace=NAMESPACE \
       --service=SERVICE_NAME \
       --location=REGION \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK \
       --address=ILB_IP_ADDRESS \
       --port=443

   替换以下内容：

   • ENDPOINT_NAME：端点的唯一标识符。
   • PROJECT_NUMBER：您的 Google Cloud项目编号。在 --network 标志中使用您的项目编号。
   • ILB_IP_ADDRESS：负载均衡器转发规则的内部 IP 地址。

直接端点

如需将 Service Directory 配置为通过专用跨云互连将流量直接路由到单个远程专用端点 IP 地址，请按照以下步骤操作：

1. 在远程云网络中创建专用端点：

   • 对于私密查询传输：在 AWS VPC 中创建 Amazon S3 的接口 VPC 端点，或在 Azure VNet 中创建 Azure Storage 的 Azure 专用端点（dfs 或 blob）。
   • 对于私密后台元数据刷新：在 AWS VPC 中为 Databricks 工作区创建 AWS PrivateLink 接口端点，或在 Azure VNet 中为 Azure Databricks 工作区创建 Azure 专用端点。

   记下每个端点的专用 IP 地址和端口 (443)，并验证您的 AWS 安全群组或 Azure NSG 是否允许来自 Google Cloud VPC 网络的端口 443 上的入站 TCP 流量。

2. 为远程专用端点创建命名空间：

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   替换以下内容：

   • NAMESPACE：命名空间的唯一标识符。
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • REGION： Google Cloud 区域（例如 us-east4）。此区域必须与联合目录所在的区域相同。

3. 在 Service Directory 命名空间中创建服务（如果您要通过私密方式路由查询传输和后台元数据刷新，请为每个端点创建一个单独的服务）：

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   替换以下内容：

   • SERVICE_NAME：服务的唯一标识符（在注册后台元数据刷新端点时，请创建一个单独的服务名称，例如 METADATA_SERVICE_NAME）。

4. 使用远程专用端点的专用 IP 地址和端口在服务中创建端点：

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --service=SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION \
       --address=REMOTE_ENDPOINT_IP \
       --port=REMOTE_ENDPOINT_PORT \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK

   替换以下内容：

   • ENDPOINT_NAME：端点的唯一标识符。
   • REMOTE_ENDPOINT_IP：远程存储或远程目录专用端点的专用 IP 地址（例如 10.0.1.45）。
   • REMOTE_ENDPOINT_PORT：远程专用端点的端口号（例如 443）。
   • PROJECT_NUMBER：您的 Google Cloud项目编号。在 --network 标志中使用您的项目编号。
   • VPC_NETWORK：与您的专用互连关联的 Google CloudVPC 网络名称。

设置联合

如需查询数据，您必须设置一个连接到远程 Databricks Unity Catalog 的 Lakehouse 联合目录。

配置身份验证

联合身份验证需要以 Databricks 服务主体的身份向目标目录进行身份验证。选择以下任一身份验证选项：

OIDC

借助 OpenID Connect (OIDC)，您可以通过 Databricks OAuth 令牌联合配置无密钥身份验证。

1. 在 Databricks 账号中创建一个服务主体，通过向其授予 EXTERNAL USE SCHEMA 权限，使其对目标 Databricks Unity Catalog 及其资源具有读取权限。
2. 保存服务主账号的应用 ID (UUID)。您在后续步骤中会用到此文件。

基于 Secret 的

此选项使用 OAuth 客户端 ID 和客户端密钥，这些信息会安全地存储在区域级 Secret Manager 密钥中。

1. 在 Databricks 账号中创建一个服务主体，通过向其授予 EXTERNAL USE SCHEMA 权限，使其对目标 Databricks Unity Catalog 及其资源具有读取权限。

2. 为服务主账号生成 OAuth secret。

3. 创建一个名为 credentials.json 且包含载荷的 JSON 文件：

   {
       "client_id": "CLIENT_ID",
       "client_secret": "CLIENT_SECRET"
   }

   替换以下内容：

   • CLIENT_ID：Databricks 服务主体的 OAuth 客户端 ID。
   • CLIENT_SECRET：Databricks 服务主体的 OAuth 客户端密钥。

4. 为 Secret Manager 配置区域端点：

   默认情况下，Secret Manager 使用全球端点。不过，Lakehouse 要求将 Secret 存储在 Lakehouse 目录所在的区域。如需使用 Google Cloud CLI 与区域级 Secret 进行交互，您必须替换当前会话或配置文件的默认 API 端点。例如 secretmanager.us-east4.rep.googleapis.com。

   gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/

   替换以下内容：

   • REGION：存储 Secret Manager 密钥的 Google Cloud 区域。例如 us-east4。为避免连接性问题，您的 Secret 和目录必须在同一区域中创建。

5. 将载荷上传到 Secret Manager：

   gcloud secrets create DATABRICKS_SECRET_NAME \
     --location="REGION" \
     --project="PROJECT_ID" \
     --data-file=credentials.json

   替换以下内容：

   • DATABRICKS_SECRET_NAME：Databricks 密钥的名称。
   • PROJECT_ID：您的 Google Cloud 项目 ID。

创建联合目录

使用 Google Cloud 控制台或 gcloud CLI 创建联合目录。

注意事项：

• 仅支持使用 AWS 上的外部位置、Azure 上的外部位置或 Google Cloud上的外部位置的 Databricks Unity Catalog。不支持使用 AWS 上的默认存储、Azure 上的默认存储或 Google Cloud上的默认存储的 Databricks Unity Catalog。

• 您必须在 Unity Catalog 使用的元存储上启用外部数据访问，该功能默认处于停用状态。

• 您必须向 Databricks 服务主账号授予对目标目录及其资源的 EXTERNAL USE SCHEMA 权限，才能为外部数据访问启用凭据发放。如果没有此权限，后台元数据刷新和查询凭证发放将会失败。

控制台

如需创建联合目录，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Lakehouse。

   前往 Lakehouse

2. 点击 创建目录。

3. 点击联合目录。

   系统会显示目录配置部分。

4. 对于联合目录来源，选择 Databricks (Unity)。

5. 对于数据位置，选择要在其中创建联合目录的 Lakehouse 区域。例如 us-east4。 为了最大限度地减少延迟时间（即使通过公共互联网），请在选择区域时执行以下操作：

   • 如果您的 Unity Catalog 位于 AWS 上，请选择最靠近 AWS 区域的Google Cloud 区域。
   • 如果您的 Unity Catalog 位于 Azure 上，请选择Google Cloud 距离您的 Azure 区域最近的区域。
   • 如果您的 Unity Catalog 位于 Google Cloud，请选择完全相同的区域。

6. 可选：在跨云缓存下，选择启用跨云缓存，以在目录的 Google Cloud区域中缓存远程文件并提升查询性能。您也可以稍后通过修改目录详情来更新此设置。如需详细了解缓存的工作原理、保留和价格，请参阅智能缓存。

7. 点击继续。

   系统会显示连接详情部分。

8. 在远程目录详细信息部分的 Unity 实例名称字段中，输入目标 Databricks 工作区主机名（例如，AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net）。

9. 在 Unity Catalog 名称字段中，输入要联合到的目标目录的名称。

10. 为身份验证方法选择一个选项：

    • 对于 OIDC，输入服务主体的应用 ID。
    • 在Secret部分，输入 Secret 的名称。请使用以下格式：projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME。

11. 可选：在身份模式部分，选择一个选项：

    • 服务身份（默认）：查询以 Lakehouse 服务账号身份执行。
    • 用户身份：查询会使用经过身份验证的最终用户的身份执行，并传播到目标目录。必须在目标目录中配置身份联合。

12. 在传输层下，选择公共互联网或专用私有互连。如果您选择专用私有互连，请配置以下字段：

    • 在服务目录名称字段中，输入传输 Service Directory 服务的路径，格式为 projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME。
    • 可选：如需通过跨云互连以私密方式同步目录元数据，请在元数据 Service Directory 名称字段中，输入元数据 Service Directory 服务的路径，格式为 projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME。

13. 点击创建。

gcloud

OIDC

如果您使用 OIDC，则必须指定 --unity-service-principal-application-id。

公共互联网（无 CCI）

如果您未配置跨云互连，则连接会使用 TLS 通过公共互联网传输。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

客户拥有 (CCI)

如果您配置了专用互连（专用或合作伙伴跨云互连），请提供用于专用查询传输 (--service-directory-name)、专用后台元数据刷新 (--metadata-service-directory-name) 或两者的 Service Directory 服务引用。您还可以通过运行 gcloud biglake iceberg catalogs update 在现有目录中添加或更新任一标志。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --unity-service-principal-application-id="UNITY_SERVICE_PRINCIPAL_APPLICATION_ID" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME" \
    --metadata-service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME"

替换以下内容：

• FEDERATED_CATALOG_NAME：联合目录的名称。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• REGION：创建联合目录的 Lakehouse 区域。此区域必须与 Service Directory 命名空间和区域级 Secret 相同。为了最大限度地缩短延迟时间，请执行以下操作：
  • 如果您的 Unity Catalog 位于 AWS 上，请选择最靠近 AWS 区域的Google Cloud 区域。
  • 如果您的 Unity Catalog 位于 Azure 上，请选择Google Cloud 距离您的 Azure 区域最近的区域。
  • 如果您的 Unity Catalog 位于 Google Cloud，请选择完全相同的区域。
• UNITY_SERVICE_PRINCIPAL_APPLICATION_ID：Databricks 服务主体的应用 ID (UUID)。
• UNITY_INSTANCE_NAME：目标 Databricks 工作区主机名（例如，AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net）。
• UNITY_CATALOG_NAME：要联合到的目标目录的名称。
• REFRESH_INTERVAL：指定后台元数据刷新的运行频率。将此值设置为时长，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：可选：要联合的命名空间的逗号分隔列表。例如 ns1,ns2。如果省略，Lakehouse 会包含所有命名空间。
• CROSS_CLOUD_CACHE_MODE：可选：是否在联合目录上启用跨云缓存（enabled 或 disabled）。默认值为 disabled。如果设置为 enabled，Lakehouse 会将远程文件缓存在目录的Google Cloud 区域中。如需了解详情，请参阅智能缓存。
• IDENTITY_MODE（可选）：指定目录的身份模式。设置为 user-identity-federation 可在查询中传播最终用户身份，或设置为 service-identity 可作为目录的服务账号执行查询。如果省略，则默认为 service-identity。
• 如果您使用的是专用互连 (跨云互连)，请指定以下一个或两个 Service Directory 引用（如果您不通过跨云互连路由该流量层，请省略任一标志）：
  • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您为远程对象存储区创建的 Service Directory 命名空间和服务名称，用于专用查询传输。
  • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您为专用后台元数据刷新创建的 Service Directory 命名空间和服务名称。

基于 Secret 的

如果您使用基于 Secret 的身份验证，则必须指定 --secret-name。

公共互联网（无 CCI）

如果您未配置跨云互连，则连接会使用 TLS 通过公共互联网传输。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE"

客户拥有 (CCI)

如果您配置了专用互连（专用或合作伙伴跨云互连），请提供用于专用查询传输 (--service-directory-name)、专用后台元数据刷新 (--metadata-service-directory-name) 或两者的 Service Directory 服务引用。您还可以通过运行 gcloud biglake iceberg catalogs update 在现有目录中添加或更新任一标志。

gcloud biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="unity" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/DATABRICKS_SECRET_NAME" \
    --unity-instance-name="UNITY_INSTANCE_NAME" \
    --unity-catalog-name="UNITY_CATALOG_NAME" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_MODE" \
    --federated-catalog-identity-mode="IDENTITY_MODE" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/SERVICE_DIRECTORY_NAMESPACE/services/SERVICE_NAME" \
    --metadata-service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/METADATA_SERVICE_DIRECTORY_NAMESPACE/services/METADATA_SERVICE_NAME"

替换以下内容：

• FEDERATED_CATALOG_NAME：联合目录的名称。
• PROJECT_ID：您的 Google Cloud 项目 ID。
• REGION：创建联合目录的 Lakehouse 区域。此区域必须与 Service Directory 命名空间和区域级 Secret 相同。为了最大限度地缩短延迟时间，请执行以下操作：
  • 如果您的 Unity Catalog 位于 AWS 上，请选择最靠近 AWS 区域的Google Cloud 区域。
  • 如果您的 Unity Catalog 位于 Azure 上，请选择Google Cloud 距离您的 Azure 区域最近的区域。
  • 如果您的 Unity Catalog 位于 Google Cloud，请选择完全相同的区域。
• DATABRICKS_SECRET_NAME：Databricks 密钥的名称。
• UNITY_INSTANCE_NAME：目标 Databricks 工作区主机名（例如，AWS 上的 abcd.cloud.databricks.com 或 Azure 上的 adb-1234567890123456.7.azuredatabricks.net）。
• UNITY_CATALOG_NAME：要联合到的目标目录的名称。
• REFRESH_INTERVAL：指定后台元数据刷新的运行频率。将此值设置为时长，例如 330s 或 5m30s。
• NAMESPACE_FILTERS：可选：要联合的命名空间的逗号分隔列表。例如 ns1,ns2。如果省略，Lakehouse 会包含所有命名空间。
• CROSS_CLOUD_CACHE_MODE：可选：是否在联合目录上启用跨云缓存（enabled 或 disabled）。默认值为 disabled。如果设置为 enabled，Lakehouse 会将远程文件缓存在目录的Google Cloud 区域中。如需了解详情，请参阅智能缓存。
• IDENTITY_MODE（可选）：指定目录的身份模式。设置为 user-identity-federation 可在查询中传播最终用户身份，或设置为 service-identity 可作为目录的服务账号执行查询。如果省略，则默认为 service-identity。
• 如果您使用的是专用互连 (跨云互连)，请指定以下一个或两个 Service Directory 引用（如果您不通过跨云互连路由该流量层，请省略任一标志）：
  • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您为远程对象存储区创建的 Service Directory 命名空间和服务名称，用于专用查询传输。
  • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您为专用后台元数据刷新创建的 Service Directory 命名空间和服务名称。

完成身份验证设置

使用您选择的身份验证类型完成身份验证流程。

OIDC

创建目录后，Lakehouse 会为其预配一个唯一服务账号。您必须检索服务账号的数字唯一 ID，并使用该 ID 为 Databricks 服务主体配置联合政策。

1. 检索 Lakehouse 目录服务账号的数字唯一 ID：

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

2. 在 Databricks 账号中，为您之前创建的服务主体配置联合政策。请使用以下值：

   • 颁发者网址：https://accounts.google.com
   • Subject：在上一步中检索到的 Lakehouse Catalog 服务账号的数字唯一 ID。
   • 受众群体：https://accounts.cloud.databricks.com

   通过向 Databricks 服务主体授予 EXTERNAL USE SCHEMA 权限，确保其对目标目录及其资源具有读取权限。

基于 Secret 的

创建目录后，Lakehouse 会为其预配一个唯一服务账号（在资源说明中返回为 biglake-service-account）。

您必须向此服务账号授予访问您之前创建的 Secret 的权限。请注意，传播 IAM 政策可能需要几分钟时间。

向目录的服务账号授予访问 Secret 的权限：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding DATABRICKS_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --format='value(biglake-service-account)')" \
  --role="roles/secretmanager.secretAccessor"

如需验证联合目录服务账号是否有权访问该 Secret，请运行以下命令：

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets get-iam-policy DATABRICKS_SECRET_NAME \
     --project="PROJECT_ID" \
     --location="REGION"

在输出中，验证 biglake-service-account 服务账号是否已分配 roles/secretmanager.secretAccessor 角色。

通过向 Databricks 服务主体授予 EXTERNAL USE SCHEMA 权限，确保其对目标目录及其资源具有读取权限。

完成专用互连设置（仅限跨云互连）

如果您通过专用互连（专用或合作伙伴跨云互连）路由查询传输和/或后台元数据刷新，则必须向 Lakehouse 目录服务账号授予权限，以便通过 Service Directory 发现和授权连接。如果您的传输 Service Directory 服务和元数据 Service Directory 服务托管在不同的 Google Cloud 项目中，请在托管 Service Directory 服务的每个项目中授予这些角色。

注意： 目录服务账号是内部 Google Cloud 服务代理。它可能不会显示在Google Cloud 控制台的项目服务账号列表中，但您可以手动为其分配角色。

控制台

1. 在 Google Cloud 控制台中，前往 IAM 页面。

   进入 IAM

2. 点击授予访问权限（或添加）。

3. 在新的主账号字段中，输入 Lakehouse 目录服务账号电子邮件地址。您可以通过描述目录来检索此电子邮件地址（请参阅 gcloud 标签页）。

4. 在角色菜单中，选择 Service Directory Viewer (roles/servicedirectory.viewer)。

5. 点击添加其他角色，然后选择 Service Directory PSC Authorized Service (roles/servicedirectory.pscAuthorizedService)。

6. 点击保存。

gcloud

在托管 Service Directory 服务的项目中，向目录的服务账号授予所需角色：

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.viewer"

# Grant Service Directory PSC Authorized Service
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.pscAuthorizedService"

验证连接

验证目录后台元数据刷新周期是否已成功完成，以及命名空间是否已同步。

1. 验证刷新状态是否显示成功：

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

2. 确认命名空间已同步：

   gcloud biglake iceberg namespaces list \
     --project="PROJECT_ID" \
     --catalog="FEDERATED_CATALOG_NAME"

配置用户身份联合（可选）

如果您为联合目录配置了用户身份联合，则必须在 Databricks 中配置账号级联合政策。

虽然后台元数据刷新会以配置了基本身份验证（OIDC 或基于 Secret）的目录服务账号身份执行，但用户身份联合需要此账号级政策，以便 Databricks 可以在交互式查询期间验证 Google Cloud 生成的最终用户身份令牌。这样，Databricks 就可以将查询归因于最终用户、强制执行权限并生成审核日志。

1. （可选）更新现有目录：

   如果您已有使用默认服务身份模式配置的联合目录，则可以将其更新为用户身份联合，而无需重新创建目录：

   控制台

   1. 在 Google Cloud 控制台中，前往 Lakehouse。

      前往 Lakehouse

   2. 在目录列表中，点击联合目录的名称。

      系统随即会显示目录详情页面。

   3. 点击 修改目录。

   4. 在身份模式部分，选择用户身份。

   5. 点击保存。

   gcloud

   运行 gcloud biglake iceberg catalogs update 命令：

   gcloud biglake iceberg catalogs update FEDERATED_CATALOG_NAME \
       --project="PROJECT_ID" \
       --federated-catalog-identity-mode="user-identity-federation"

2. 从目录中检索 OIDC 声明：

   运行以下命令，检索 Databricks 所需的令牌声明：

   gcloud biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
       --project="PROJECT_ID" \
       --format='yaml(federated-catalog-options.user-identity-federation-oidc)'

   输出类似于以下内容：

   federated-catalog-options:
     user-identity-federation-oidc:
       audience: databricks-12345678-abcd-1234-efgh-1234567890ab
       issuer-url: https://www.gstatic.com/biglake/federation/organizations/123456789012

   关于版权主张的可用性，请注意以下事项：

   • issuer-url：派生自您的 Google Cloud 组织 (https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID)，在创建目录后立即可用。
   • audience：范围限定为目标 Databricks Metastore (databricks-METASTORE_ID)，并派生自 Unity Catalog Metastore。由于此值由后台元数据刷新填充，因此必须完成基本身份验证，并且后台元数据刷新必须处于活动状态（未设置为 0）。请参阅验证连接，检查后台元数据刷新是否已正确设置。

3. 配置 Databricks 账号级联合政策：

   1. 在 Databricks 账号控制台中，依次前往账号设置 > 安全 > 身份提供方设置。
   2. 在联合政策部分中，点击创建政策。
   3. 在政策配置对话框中，设置以下字段：
      • Issuer URL（颁发者网址）：输入在上一步中检索到的 issuer-url 值（例如 https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID）。
      • 受众群体：输入在上一步中检索到的 metastore 范围的 audience 值（例如 databricks-METASTORE_ID）。
      • Subject claim（主题声明）：留空（Databricks 默认使用包含用户邮箱的 sub 声明）。Databricks 会使用此邮箱与 Databricks 账号中配置的用户进行匹配。
   4. 点击保存。

4. 验证用户身份联合和审核日志记录：

   如需验证用户归因查询执行和审核日志记录，请执行以下操作：

   1. 按照查询远程数据中的说明，在 BigQuery 中针对联合表运行查询。

   2. 在 Databricks 中，验证查询访问事件是否记录在 Databricks 审核日志中。在 Databricks SQL 编辑器中查询 system.access.audit 系统表（请参阅 Databricks 审核日志参考文档）。请注意，可审核事件可能需要 15 分钟或更长时间才能显示在 Databricks 审核日志中：

      SELECT
        *
      FROM
        system.access.audit
      WHERE
        service_name = 'accounts'
        AND action_name IN ('oidcTokenAuthorization')
        AND event_time >= NOW() - INTERVAL 30 MINUTE
        AND user_identity.email = 'USER_EMAIL'
      ORDER BY
        event_time DESC
      LIMIT 10;

后续步骤

• 查询远程数据。
• 将 VPC Service Controls 与联合目录端点搭配使用。
• 排查 Databricks Unity Catalog 的跨云数据访问问题。