自 2026 年 4 月 20 日起，BigLake 现在称为 Lakehouse for Apache Iceberg。BigLake metastore 现已更名为 Lakehouse 运行时目录。Lakehouse API、客户端库、CLI 命令和 IAM 名称保持不变，仍引用 BigLake。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

为 Snowflake Horizon Catalog 设置跨云连接

本文档介绍了如何设置跨云连接，以便直接在Google Cloud中查询 Snowflake Horizon 目录中的数据。此功能可将外部数据源与现有 Google Cloud环境相集成，从而统一数据分析。

之后，您可以使用无边界 Lakehouse 来管理对联邦数据的访问权限。

准备工作

查看湖仓一体概览，了解湖仓一体如何管理数据访问权限。
请参阅有关访问跨云数据的文章，了解其运作方式。
查看支持的目录，验证支持的配置。
了解如何使用区域级 Secret Manager Secret。这是使用基于 Secret 的身份验证设置具有 Snowflake Horizon 目录的 Lakehouse 所必需的。
可选：如果您计划通过 Google Cloud VPC 与远程云提供商的 VPC（例如 AWS）之间的专用互连来路由查询，请确保您在远程提供商处拥有有效账号，预配专用跨云互连或合作伙伴跨云互连，与 Cloud Router 建立 BGP 会话，并验证您在两个云环境中都拥有所需的 IAM 权限。

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

Roles required to enable APIs

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)

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

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

支持的目录详情

本指南提供了有关在 Amazon Web Services (AWS) 或 Google Cloud上使用 Snowflake Horizon Catalog 设置 Lakehouse 的说明。如需详细了解外部位置要求和支持的配置，请参阅支持的目录。

限制和注意事项

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

支持跨云互连的云提供商：以下远程云提供商支持使用专用互联来连接无边界 Lakehouse：Amazon Web Services (AWS)。您可以使用专用 Cross-Cloud Interconnect 或合作伙伴 Cross-Cloud Interconnect。
支持的表：只有 Snowflake Iceberg 表会同步到湖仓一体。在元数据刷新期间，系统会忽略标准原生 Snowflake 表。
只读：Lakehouse 中的联合目录是远程目录的只读视图。不支持资源操作（例如创建、更新或删除资源），必须直接在远程目录中执行。
网络路由：如果未配置专用互连（例如专用 CCI 或合作伙伴 CCI），查询将通过公共互联网进行路由。这可能会导致远程云提供商收取更高的出站费用，并降低性能的可预测性。
数据新鲜度：联合目录的 --refresh-interval 标志用于确定元数据的同步频率。该值必须为 0s（已停用）或至少为 300s（5 分钟）。目录的后台元数据刷新时间可能会随着命名空间和表资源数量的增加而延长。如果上一次刷新超时，系统会跳过当前刷新，但会在下一个间隔安排下一次刷新。

常规工作流程

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

设置跨云互连（可选）：在 Google Cloud VPC 与远程云提供商之间配置专用连接。
设置联合：在 Lakehouse 中配置身份验证并创建联合目录。
- 基于 Secret 的身份验证 (PAT)：在 Secret Manager 中创建包含远程目录凭据的 Secret。然后，在 Lakehouse 中创建联合目录，并向目录服务账号授予对 Secret 的访问权限。
- 工作负载身份联合 (WIF)：在 Lakehouse 中创建一个联合目录，指定所需的 Snowflake 角色。然后，将目录的服务账号 ID 关联到 Snowflake 中的服务用户。Snowflake 服务用户应具有对远程 Snowflake Horizon Catalog 的使用权限。
验证连接：验证 Lakehouse 是否可以成功连接到您的远程目录。
查询数据：使用 BigQuery 或 Managed Service for Apache Spark 针对联合数据运行查询。如需了解详情，请参阅查询远程数据。
配置权限：使用 IAM 管理哪些人可以查看和查询联合数据。

设置跨云互连（可选）

默认情况下，对远程目录的查询通过公共互联网传输。为了帮助增强安全性、合规性，提供可预测的性能并降低数据传输费用，请使用专用互连。这样一来，您的 Google CloudVirtual Private Cloud (VPC) 与远程云提供商的网络（例如 AWS）之间便会建立专用网络连接。

您可以在 Google Cloud VPC 与远程云提供商的 VPC（例如 AWS）之间预配和配置以下任一专用互连选项：

专用 Cross-Cloud Interconnect：专用物理连接。
合作伙伴 Cross-Cloud Interconnect：通过受支持的服务提供商建立的连接。

在 Google Cloud 中的 Cloud Router 路由器与远程云提供商的 VPC 之间建立 BGP 会话，以确保路由交换。

如需启用私密查询，您必须通过专用互联配置从 Lakehouse 到远程存储桶（例如 AWS Amazon S3 存储桶）的路径。您可以通过以下两种架构流程来配置此路由：

内部区域级代理网络负载平衡器路由：此流程使用Google Cloud 内部区域级代理网络负载平衡器在指向多个 AWS 弹性网络接口 (ENI) 的混合连接网络端点群组 (NEG) 之间分配请求。此流程对于负载均衡、可伸缩性和高可用性至关重要。对于合作伙伴 CCI，这是必需的；对于专用 CCI，建议使用，以实现负载均衡、可伸缩性和高可用性。
直接端点路由：此流程将 Service Directory 直接连接到单个 AWS 接口 VPC 端点 IP 地址。此流程仅适用于专用 CCI，不支持合作伙伴 CCI。

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

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

如需配置内部区域代理网络负载平衡器，以在多个 AWS ENI 之间分配请求，从而实现高可用性和负载均衡，请按以下步骤操作：

配置 AWS 网络

首先，创建 Amazon S3 VPC 接口端点 (AWS PrivateLink)：

在 AWS VPC 控制台中，为 Amazon S3 创建接口端点。
对于服务名称，请指定 com.amazonaws.AWS_REGION.s3。
选择通过 Direct Connect 连接到 Google Cloud VPC 的 VPC 和子网。
将安全组附加到端点以控制入站访问。
此操作会在每个所选子网中预配弹性网络接口 (ENI)。记下这些 ENI 的私有 IP 地址。

接下来，配置安全组：

确保附加到 Amazon S3 端点 ENI 的安全组允许来自 Google Cloud VPC 的端口 443 上的入站 TCP 流量。这必须包含Google Cloud 代理专用子网的 CIDR 范围，以允许健康检查和转发的流量。

配置 Google Cloud 网络

为简化设置，请运行以下命令来配置内部负载均衡器。如需了解高级配置或更多详情，请参阅为混合端点设置内部区域级代理网络负载平衡器。

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）。

创建区域级健康检查：
```
gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
    --region=REGION \
    --port=443
```
替换以下内容：
- HEALTH_CHECK_NAME：健康检查的名称。
- REGION： Google Cloud 区域（例如 us-east4）。
创建混合连接网络端点组 (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
```
将 AWS ENI 的专用 IP 地址添加到相应的混合 NEG：
```
gcloud compute network-endpoint-groups update NEG_NAME \
    --zone=ZONE \
    --add-endpoint="ip=AWS_S3_IP,port=443"
```
替换以下内容：
- NEG_NAME：混合 NEG 的名称。
- ZONE： Google Cloud 可用区（例如 us-east4-a）。此可用区必须位于跨云互连 VLAN 连接的区域内。
- VPC_NETWORK：您的 VPC 网络的名称。
- AWS_S3_IP：相应可用区中 AWS Amazon S3 VPC 端点 (ENI) 的私有 IP 地址。
如果您的 AWS ENI 分布在多个可用区中，请重复执行这些命令，以创建 NEG 并为其他可用区添加端点。

创建和配置后端服务：

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

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 命令。

配置负载均衡器前端：

创建目标 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 中注册 ILB 的 IP 地址，以便 Lakehouse 可以发现它。

为远程云创建命名空间：
```
gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION
```
替换以下内容：
- NAMESPACE：命名空间的唯一标识符。
- PROJECT_ID：您的 Google Cloud 项目 ID。
- REGION： Google Cloud 区域。例如 us-east4。此值必须与联合目录所在的区域相同。

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

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

替换以下内容：

SERVICE_NAME：服务的唯一标识符。

在服务中为 ILB 创建端点：

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：ILB 转发规则的内部 IP 地址。

直接端点

如需配置 Service Directory 以将流量直接路由到单个 AWS 接口 VPC 端点 IP 地址，请按照以下步骤操作：

在 AWS VPC 内为 Amazon S3 创建接口 VPC 端点。记下此端点的 IP 地址和端口。
为远程云创建命名空间：
```
gcloud service-directory namespaces create NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION
```
替换以下内容：
- NAMESPACE：命名空间的唯一标识符。
- PROJECT_ID：您的 Google Cloud 项目 ID。
- REGION： Google Cloud 区域。例如 us-east4。此值必须与联合目录所在的区域相同。

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

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

替换以下内容：

SERVICE_NAME：服务的唯一标识符。

在包含 Amazon S3 接口 VPC 端点路由信息的服务中创建端点：
```
gcloud service-directory endpoints create ENDPOINT_NAME \
    --service=SERVICE_NAME \
    --namespace=NAMESPACE \
    --project=PROJECT_ID \
    --location=REGION \
    --address=S3_VPCE_IP_ADDRESS \
    --port=S3_VPCE_PORT \
    --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK
```
替换以下内容：
- ENDPOINT_NAME：端点的唯一标识符。
- S3_VPCE_IP_ADDRESS：Amazon S3 接口 VPC 端点的 IP 地址。例如 10.0.1.45。
- S3_VPCE_PORT：Amazon S3 接口 VPC 端点的端口号。例如 443。
- PROJECT_NUMBER：您的 Google Cloud项目编号。在 --network 标志中使用您的项目编号。
- VPC_NETWORK：与专用互连关联的 Google Cloud VPC 网络名称。

设置联合

如需查询数据，您必须设置一个 Lakehouse 联合目录，该目录可连接到您的远程 Snowflake Horizon 目录。

配置身份验证

联合需要凭据或角色配置才能访问远程 Snowflake Horizon Catalog。选择以下方法之一。

基于 Secret (PAT)

此选项使用通过区域性 Secret Manager 密文安全存储的程序化访问令牌 (PAT)。

生成对目标目录具有读取权限的程序化访问令牌 (PAT)。
创建一个名为 credentials.json 且包含您的载荷的 JSON 文件：
```
{
  "client_secret": "SNOWFLAKE_PAT_TOKEN",
  "scope": "session:role:SNOWFLAKE_ROLE"
}
```
替换以下内容：
- SNOWFLAKE_PAT_TOKEN：您的 Snowflake 程序化访问令牌 (PAT)。
- SNOWFLAKE_ROLE：会话所需的特定 Snowflake 角色。例如 ICEBERG_VIEW。
注意：对于 Snowflake Horizon 设置，不需要 client_id 参数，因为身份验证完全由 PAT 令牌和范围处理。
为 Secret Manager 配置区域端点：

默认情况下，Secret Manager 使用全球端点。不过，Lakehouse 要求您的 Secret 存储在与 Lakehouse 目录相同的区域中。如需使用 gcloud CLI 与区域级密文进行交互，您必须替换当前会话或配置文件的默认 API 端点。为避免连接问题，您的 Secret 和目录必须在同一区域中创建。
```
gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
```
替换以下内容：
- REGION：存储 Secret Manager Secret 的 Google Cloud 区域。例如 us-east4。为避免连接问题，您的密钥和目录必须在同一区域中创建。
将载荷上传到 Secret Manager：
```
gcloud secrets create SNOWFLAKE_SECRET_NAME \
  --location="REGION" \
  --project="PROJECT_ID" \
  --data-file=credentials.json
```
替换以下内容：
- SNOWFLAKE_SECRET_NAME：Snowflake Secret 的名称。
- PROJECT_ID：您的 Google Cloud 项目 ID。

工作负载身份联合

工作负载身份联合 (WIF) 通过将 Lakehouse 目录服务账号直接关联到 Snowflake 服务用户，避免使用长期有效的密钥。无需进行任何前提设置。继续创建联合目录。

创建联合目录

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

控制台

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

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

前往 Lakehouse
点击 创建目录。
点击联合目录。

系统会显示目录配置详细信息。
对于联合目录源，请选择 Snowflake (Horizon)。
对于数据位置，选择要在其中创建联邦目录的 Lakehouse 区域。例如 us-east4。为了尽可能缩短延迟时间（即使是通过公共互联网），请在选择区域时执行以下操作：
- 如果您的 Snowflake Horizon Catalog 位于 AWS 上，请选择Google Cloud 距离您的 AWS 区域最近的区域。
- 如果您的 Snowflake Horizon Catalog 位于 Google Cloud，请选择完全相同的区域。
点击继续。

系统会显示连接详细信息。
在远程目录详细信息部分中，在 Snowflake 账号标识符字段中输入您的 Snowflake 账号标识符。例如：my_org-my_account。
在 Snowflake 仓库字段中，输入 Snowflake 仓库名称。这在 Snowflake Horizon Catalog 中也称为数据库名称。
选择身份验证方法：
- 对于 Secret，请输入 Secret-based (PAT) 的 Secret 名称。请使用以下格式：projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME。
- 对于 OIDC，请输入您的 Snowflake 角色以用于工作负载身份联合。例如：ICEBERG_VIEW。
可选：在服务目录名称字段中，输入您的 Service Directory 服务的路径。例如：projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME。仅当您配置专用互连 (跨云互连) 时，才需要执行此操作。
点击创建。

gcloud CLI

基于 Secret 的令牌 (PAT)

公共互联网（无 CCI）

如果您不配置 CCI，连接将通过公共互联网安全传输。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
REGION：创建联邦目录的 Lakehouse 区域。例如 us-east4。为尽可能缩短延迟时间，请选择距离您的 Snowflake 区域最近的 Google Cloud 区域。
SNOWFLAKE_SECRET_NAME：Snowflake Secret 的名称。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 账号标识符（例如 my_org-my_account）。
SNOWFLAKE_WAREHOUSE：您要联合的 Snowflake 数据仓库。这在 Snowflake Horizon Catalog 中也称为数据库名称。
REFRESH_INTERVAL（可选）：指定更新目录信息的频率。将此值设置为时长，例如 330s 或 5m30s。该值必须为 0s（已停用）或至少为 300s (5m)。如果时长短于 300s，则会导致错误。间隔时间越短，数据更新频率越高，但 API 调用费用也可能越高。间隔时间越长，费用越低，但查询的数据可能无法反映最新的数据集。 如果省略此参数或将值设置为 0s，则不会启动后台元数据刷新。在刷新间隔更新为有效的正值之前，该功能将保持停用状态。
NAMESPACE_FILTERS：可选：要联合的命名空间逗号分隔列表。例如 ns1,ns2。如果省略，则将包含所有命名空间。

客户拥有的 (CCI)

如果您配置了专用互连（例如专用 CCI 或合作伙伴 CCI），请提供 Service Directory 服务引用，以便 Lakehouse 以私密方式路由流量。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
REGION：创建联邦目录的 Lakehouse 区域。注意：此区域必须与 Service Directory 命名空间和区域密钥相同。
SNOWFLAKE_SECRET_NAME：Snowflake Secret 的名称。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 账号标识符。
SNOWFLAKE_WAREHOUSE：您要联合的 Snowflake 数据仓库。这在 Snowflake Horizon Catalog 中也称为数据库名称。
REFRESH_INTERVAL（可选）：指定更新目录信息的频率。将此值设置为时长，例如 330s 或 5m30s。该值必须为 0s（已停用）或至少为 300s (5m)。如果时长短于 300s，则会导致错误。间隔时间越短，数据更新频率越高，但 API 调用费用也可能越高。间隔时间越长，费用越低，但查询的数据可能无法反映最新的数据集。 如果省略此参数或将值设置为 0s，则不会启动后台元数据刷新。在刷新间隔更新为有效的正值之前，该功能将保持停用状态。
NAMESPACE_FILTERS：可选：要联合的命名空间逗号分隔列表。例如 ns1,ns2。如果省略，则将包含所有命名空间。
NAMESPACE：您在设置专用互连时创建的 Service Directory 命名空间。
SERVICE_NAME：您在设置专用互连时创建的 Service Directory 服务名称。

工作负载身份联合

公共互联网（无 CCI）

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

客户拥有的 (CCI)

如果您配置了专用互连（例如专用 CCI 或合作伙伴 CCI），请提供 Service Directory 服务引用，以便 Lakehouse 私密地路由流量。

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME"

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 账号标识符。
SNOWFLAKE_WAREHOUSE：您要联合的 Snowflake 数据仓库。这在 Snowflake Horizon Catalog 中也称为数据库名称。
SNOWFLAKE_ROLE：会话所需的特定 Snowflake 角色。例如 ICEBERG_VIEW。
FEDERATED_CATALOG_NAME：Lakehouse 联合目录的名称。
REGION：创建联邦目录的 Lakehouse 区域。
REFRESH_INTERVAL（可选）：指定更新目录信息的频率。将此值设置为时长，例如 330s 或 5m30s。该值必须为 0s（已停用）或至少为 300s (5m)。如果时长短于 300s，则会导致错误。间隔时间越短，数据更新频率越高，但 API 调用费用也可能越高。间隔时间越长，费用越低，但查询的数据可能无法反映最新的数据集。 如果省略此参数或将值设置为 0s，则不会启动后台元数据刷新。在刷新间隔更新为有效的正值之前，该功能将保持停用状态。
NAMESPACE_FILTERS：可选：要联合的命名空间逗号分隔列表。例如 ns1,ns2。如果省略，则将包含所有命名空间。
NAMESPACE：Service Directory 服务的命名空间。
SERVICE_NAME：Service Directory 服务的名称。

完成身份验证设置

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

基于 Secret (PAT)

创建目录时，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 SNOWFLAKE_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud alpha 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 SNOWFLAKE_SECRET_NAME \
    --project="PROJECT_ID" \
    --location="REGION"

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

工作负载身份联合

创建目录后，您必须将其服务账号身份与 Snowflake 中的服务用户相关联。

从目录详细信息中提取 Lakehouse 服务账号 ID（正文）。

您可以从创建命令的 JSON 响应（字段 biglake-service-account-id）中获取此信息。

或者，您也可以对目录运行 describe 命令来获取该值：
```
gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
  --project="PROJECT_ID"
```
在输出中查找 biglake-service-account-id。

USE ROLE ACCOUNTADMIN;

CREATE USER SNOWFLAKE_SERVICE_USER
  TYPE = SERVICE
  WORKLOAD_IDENTITY = (
    TYPE = GCP
    SUBJECT = 'LAKEHOUSE_SERVICE_ACCOUNT_ID'
  )
  DEFAULT_ROLE = SNOWFLAKE_ROLE
  COMMENT = 'Service user for Lakehouse federation over WIF';

-- Also explicitly GRANT permissions to the role
GRANT ROLE SNOWFLAKE_ROLE TO USER SNOWFLAKE_SERVICE_USER;

替换以下内容：

SNOWFLAKE_SERVICE_USER：Snowflake 中新服务用户的名称。
LAKEHOUSE_SERVICE_ACCOUNT_ID：在上一步中提取的服务账号 ID。
SNOWFLAKE_ROLE：Snowflake 角色（必须与创建目录时指定的角色一致）。

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

如果您要通过专用互连（专用或合作伙伴 CCI）路由流量，则必须授予 Lakehouse 目录服务账号通过 Service Directory 发现和授权连接的权限。

控制台

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

进入 IAM
点击授予访问权限（或添加）。
在新主账号字段中，输入 Lakehouse 目录服务账号电子邮件地址。您可以通过描述目录（请参阅 gcloud 标签页）来检索此电子邮件。
在角色下拉菜单中，选择 Service Directory Viewer (roles/servicedirectory.viewer)。
点击添加其他角色，然后选择 Service Directory PSC Authorized Service (roles/servicedirectory.pscAuthorizedService)。
点击保存。

gcloud CLI

向目录的服务账号授予所需角色：

# Grant Service Directory Viewer
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(gcloud alpha 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 alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --format='value(biglake-service-account)')" \
--role="roles/servicedirectory.pscAuthorizedService"

验证连接

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

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

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

确认命名空间已同步：

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

确认命名空间中的表已同步：

gcloud alpha biglake iceberg tables list \
  --project="PROJECT_ID" \
  --catalog="FEDERATED_CATALOG_NAME" \
  --namespace="NAMESPACE_ID"

为 Snowflake Horizon Catalog 设置跨云连接 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

支持的目录详情

限制和注意事项

常规工作流程

设置跨云互连（可选）

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

直接端点

设置联合

配置身份验证

基于 Secret (PAT)

工作负载身份联合

创建联合目录

控制台

gcloud CLI

基于 Secret 的令牌 (PAT)

公共互联网（无 CCI）

客户拥有的 (CCI)

工作负载身份联合

公共互联网（无 CCI）

客户拥有的 (CCI)

完成身份验证设置

基于 Secret (PAT)

工作负载身份联合

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

控制台

gcloud CLI

验证连接

后续步骤

为 Snowflake Horizon Catalog 设置跨云连接