为 Snowflake Horizon Catalog 设置跨云连接

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

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

准备工作

  1. 查看 Lakehouse 概览，了解 Lakehouse 如何管理对数据的访问权限。
  2. 阅读访问跨云数据简介，了解其工作原理。
  3. 查看支持的目录，验证支持的配置。
  4. 了解如何使用区域级 Secret Manager Secret。如需使用基于密文的身份验证设置 Lakehouse 与 Snowflake Horizon Catalog，则必须执行此操作。
  5. 可选：如果您计划通过 Google Cloud虚拟私有云 (VPC) 网络与远程云网络（AWS VPC 或 Azure VNet）之间的专用互连来路由查询读取或后台元数据刷新，请验证您是否拥有远程提供商的有效账号，预配专用跨云互连或合作伙伴跨云互连（适用于 AWS），与 Cloud Router 路由器建立 BGP 会话，并验证您是否在两个云环境中都拥有所需的 Identity and Access Management (IAM) 权限。

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

  7. 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 角色：

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

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

限制和注意事项

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

  • VPC Service Controls：如果包含联合目录端点或底层 Cloud Storage 存储桶的项目位于 VPC Service Controls 服务边界内，则您必须配置出站流量或入站流量规则。如需了解详情，请参阅将 VPC Service Controls 与联合目录端点搭配使用。
  • Cross-跨云互连支持的云服务商：AWS 和 Azure 支持使用专用互连来路由查询传输和/或后台元数据刷新。您可以使用专用 Cross-Cloud Interconnect（适用于 AWS 或 Azure）或合作伙伴 Cross-Cloud Interconnect（适用于 AWS）。
  • 网络路由：如果您没有为查询传输或后台元数据刷新配置专用互连，则相应的流量会通过 TLS 经由公共互联网进行路由。通过公共互联网路由查询读取可能会导致远程云服务商收取更高的出站流量费用，并且性能的可预测性较低。
  • Snowflake Horizon Catalog 支持的表：只有 Snowflake Horizon Catalog 中的 Apache Iceberg 表会同步到 Lakehouse。在后台元数据刷新期间，系统会忽略非 Iceberg Snowflake 表。
  • 网络政策和出站流量 IP 地址：当后台元数据刷新通过公共互联网连接时，Lakehouse 会使用 Google 全球基础设施出站流量 IP 地址来访问您的 Snowflake 面向互联网的端点。如果您为公共互联网访问配置了 Snowflake 网络政策，请将 goog.json 中的 Google 出站 IP 地址范围添加到网络政策的允许 IP 列表中。当您通过跨云互连配置专用后台元数据刷新时，元数据请求会通过您的 VPC 网络以私密方式路由到您的 Snowflake PrivateLink 端点。
  • 只读：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 中创建联合目录。
    • 基于 Secret 的身份验证 (PAT)：在 Secret Manager 中使用远程目录凭证创建 Secret。然后，在 Lakehouse 中创建联合目录，并向目录服务账号授予对该 Secret 的访问权限。
    • 工作负载身份联合 (WIF)：在 Lakehouse 中创建一个联合目录，并指定所需的 Snowflake 角色。然后，将目录的服务账号 ID 关联到 Snowflake 中的服务用户。Snowflake 服务用户必须对远程 Snowflake Horizon Catalog 具有使用权限。
  • 验证连接：验证 Lakehouse 是否可以连接到远程目录。
  • 查询数据：使用 BigQuery 或 Managed Service for Apache Spark 对联合数据运行查询。您可以选择在联合目录上启用跨云缓存，以帮助降低跨云出站流量费用并加快后续查询。如需了解详情，请参阅查询远程数据。
  • 配置权限：使用 IAM 管理谁可以查看和查询联合数据。

设置跨云互连（可选）

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

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

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

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

  • 查询传输 (--service-directory-name)：将查询读取从 BigQuery 或开源引擎路由到远程对象存储（Amazon S3 或 Azure Data Lake Storage Gen2 [ADLS Gen2]），以帮助降低跨云出站流量费用并保持查询延迟时间可预测。
  • 后台元数据刷新 (--metadata-service-directory-name)：将控制平面后台元数据刷新和身份验证请求从 Lakehouse 运行时目录路由到远程 Snowflake Horizon 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 地址。
  • 对于专用后台元数据刷新（远程目录）：在 Snowflake 中，运行 SELECT SYSTEM$GET_PRIVATELINK_CONFIG(); 以获取 PrivateLink 服务标识符和 .privatelink 账号标识符。在 AWS 上，按照 AWS PrivateLink 和 Snowflake 中的说明在 AWS VPC 中创建接口 VPC 端点，并记下 ENI 专用 IP 地址。在 Azure 上，按照 Azure Private Link 和 Snowflake 中的说明在 Azure VNet 中创建 Azure 专用端点，并记下 NIC 专用 IP 地址。
  • 入站安全规则：验证附加到专用端点的 AWS 安全组或 Azure 网络安全组 (NSG) 是否允许来自 Google Cloud VPC CIDR 范围的端口 443（如果您的 Snowflake 配置使用 OCSP，则为端口 80）上的入站 TCP 流量。添加 Google Cloud 代理专用子网的 CIDR 范围，以允许健康检查和转发的流量。

配置 Google Cloud 网络

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

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

  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. 在远程云网络中创建专用端点：

    记下每个端点的专用 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 网络名称。

设置联合

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

配置身份验证

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

基于 Secret (PAT)

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

  1. 生成对目标目录具有读取权限的程序化访问令牌 (PAT)。

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

    {
  "client_secret": "SNOWFLAKE_PAT_TOKEN",
  "scope": "session:role:SNOWFLAKE_ROLE"
}

    替换以下内容：

    • SNOWFLAKE_PAT_TOKEN：您的 Snowflake 程序化访问令牌 (PAT)。
    • SNOWFLAKE_ROLE：会话所需的特定 Snowflake 角色。例如 ICEBERG_VIEW。

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

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

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

    替换以下内容：

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

  4. 将载荷上传到 Secret Manager：

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

    替换以下内容：

    • SNOWFLAKE_SECRET_NAME：Snowflake 密钥的名称。
    • PROJECT_ID：您的 Google Cloud 项目 ID。

工作负载身份联合

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

创建联合目录

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

控制台

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

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

    前往 Lakehouse

  2. 点击 创建目录。

  3. 点击联合目录。

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

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

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

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

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

  7. 点击继续。

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

  8. 在远程目录详细信息部分的 Snowflake 账号标识符字段中，输入您的 Snowflake 账号标识符（例如 myorg-myaccount）。如果您通过 AWS PrivateLink 或 Azure Private Link 私下路由后台元数据刷新，请输入您的 .privatelink 账号标识符（例如 myorg-myaccount.privatelink）。

  9. 在 Snowflake 仓库字段中，输入您的 Snowflake 仓库名称。这也称为 Snowflake Horizon Catalog 中的数据库名称。

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

    • 对于Secret，输入基于 Secret (PAT) 的 Secret 名称。请使用以下格式：projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME。
    • 对于 OIDC，输入工作负载身份联合的 Snowflake 角色。例如：ICEBERG_VIEW。

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

    • 在服务目录名称字段中，输入传输 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。

  12. 点击创建。

gcloud

基于 Secret (PAT)

如果您使用基于 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="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" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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="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" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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 相同。如需最大限度地缩短延迟时间，请执行以下操作：
    • 如果您的 Snowflake Horizon Catalog 位于 AWS 上，请选择Google Cloud 距离您的 AWS 区域最近的区域。
    • 如果您的 Snowflake Horizon 目录位于 Azure 上，请选择Google Cloud 最靠近您的 Azure 区域的区域。
    • 如果您的 Snowflake Horizon Catalog 位于 Google Cloud，请选择完全相同的区域。
  • SNOWFLAKE_SECRET_NAME：Snowflake 密钥的名称。
  • SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 账号标识符（例如 myorg-myaccount）。如果您指定 --metadata-service-directory-name 通过 PrivateLink 或 Private Link 同步元数据，请使用您的 .privatelink 账号标识符（例如 myorg-myaccount.privatelink）。
  • SNOWFLAKE_WAREHOUSE：您要与之联合的 Snowflake 仓库。这也称为 Snowflake Horizon Catalog 中的数据库名称。
  • REFRESH_INTERVAL：可选：指定后台元数据刷新的运行频率。将此值设置为时长，例如 330s 或 5m30s。
  • NAMESPACE_FILTERS：可选：要联合的命名空间的逗号分隔列表。例如 ns1,ns2。如果省略，Lakehouse 会包含所有命名空间。
  • CROSS_CLOUD_CACHE_MODE：可选：是否在联合目录上启用跨云缓存（enabled 或 disabled）。默认值为 disabled。如果设置为 enabled，Lakehouse 会将远程文件缓存在目录的Google Cloud 区域中。如需了解详情，请参阅智能缓存。
  • 如果您使用的是专用互连 (跨云互连)，请指定以下一个或两个 Service Directory 引用（如果您不通过跨云互连路由该流量层，请省略任一标志）：
    • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您为远程对象存储区创建的 Service Directory 命名空间和服务名称，用于专用查询传输。
    • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_SERVICE_NAME：您为专用后台元数据刷新创建的 Service Directory 命名空间和服务名称。

工作负载身份联合

如果您使用工作负载身份联合，则必须指定 --snowflake-role。

公共互联网（无 CCI）

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

gcloud 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" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --cross-cloud-cache="CROSS_CLOUD_CACHE_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 相同。如需最大限度地缩短延迟时间，请执行以下操作：
    • 如果您的 Snowflake Horizon Catalog 位于 AWS 上，请选择Google Cloud 距离您的 AWS 区域最近的区域。
    • 如果您的 Snowflake Horizon 目录位于 Azure 上，请选择Google Cloud 最靠近您的 Azure 区域的区域。
    • 如果您的 Snowflake Horizon Catalog 位于 Google Cloud，请选择完全相同的区域。
  • SNOWFLAKE_ACCOUNT_IDENTIFIER：您的 Snowflake 账号标识符（例如 myorg-myaccount）。如果您指定 --metadata-service-directory-name 通过 PrivateLink 或 Private Link 同步元数据，请使用您的 .privatelink 账号标识符（例如 myorg-myaccount.privatelink）。
  • SNOWFLAKE_WAREHOUSE：您要与之联合的 Snowflake 仓库。这也称为 Snowflake Horizon Catalog 中的数据库名称。
  • SNOWFLAKE_ROLE：会话所需的特定 Snowflake 角色。例如 ICEBERG_VIEW。
  • REFRESH_INTERVAL：指定后台元数据刷新的运行频率。将此值设置为时长，例如 330s 或 5m30s。
  • NAMESPACE_FILTERS：可选：要联合的命名空间的逗号分隔列表。例如 ns1,ns2。如果省略，Lakehouse 会包含所有命名空间。
  • CROSS_CLOUD_CACHE_MODE：可选：是否在联合目录上启用跨云缓存（enabled 或 disabled）。默认值为 disabled。如果设置为 enabled，Lakehouse 会将远程文件缓存在目录的Google Cloud 区域中。如需了解详情，请参阅智能缓存。
  • 如果您使用的是专用互连 (跨云互连)，请指定以下一个或两个 Service Directory 引用（如果您不通过跨云互连路由该流量层，请省略任一标志）：
    • SERVICE_DIRECTORY_NAMESPACE 和 SERVICE_NAME：您为远程对象存储区创建的 Service Directory 命名空间和服务名称，用于专用查询传输。
    • METADATA_SERVICE_DIRECTORY_NAMESPACE 和 METADATA_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 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 中的服务用户。

  1. 从目录详情中提取 Lakehouse 服务账号 ID（主体）。

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

    或者，您也可以对目录运行 describe 命令来获取该值：

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

    在输出中查找 biglake-service-account-id。

  2. 登录您的 Snowflake 管理实例，并执行以下脚本，以与 Lakehouse 服务身份建立信任关系：

    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 角色（必须与创建目录时指定的角色一致）。

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

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

控制台

  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"

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

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

后续步骤