为 Snowflake 设置无边界数据湖仓

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

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

配置 AWS 网络

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

1. 在 AWS VPC 控制台中，为 Amazon S3 创建接口端点。
2. 对于服务名称，请指定 com.amazonaws.AWS_REGION.s3。
3. 选择通过 Direct Connect 连接到 Google Cloud VPC 的 VPC 和子网。
4. 将安全组附加到端点以控制入站访问。
5. 此操作会在每个所选子网中预配弹性网络接口 (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）。

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

   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

   将 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 并为其他可用区添加端点。

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

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：服务的唯一标识符。

3. 在服务中为 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 地址，请按照以下步骤操作：

1. 在 AWS VPC 内为 Amazon S3 创建接口 VPC 端点。记下此端点的 IP 地址和端口。

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：服务的唯一标识符。

4. 在包含 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 网络名称。

基于 Secret (PAT)

对于基于 Secret 的身份验证 (PAT)，您必须使用个人访问令牌 (PAT)（由 Snowflake 生成的长期令牌），以及会话所需的特定 Snowflake 角色。

在区域级 Secret Manager 中创建一个 Secret 来存储凭据：

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

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

   替换以下内容：

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

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

   默认情况下，Secret Manager 使用全球端点。不过，无边界 Lakehouse 要求您的 Secret 存储在与 Lakehouse 目录相同的区域中。如需使用 gcloud CLI 与区域级 Secret 进行交互，您必须替换当前会话或配置文件的默认 API 端点。为避免连接问题，您的 Secret 和目录必须在同一区域中创建。

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

   替换以下内容：

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

3. 将载荷上传到 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 服务用户，避免使用长期有效的密钥。在创建目录之前，无需在 Secret Manager 中进行任何预配置。继续创建联合目录。

控制台

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

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

   前往 Lakehouse

2. 点击 add_box 创建目录。

3. 点击联合目录。

   系统会显示目录配置详细信息。

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

5. 对于数据位置，选择要在其中创建联邦目录的 Lakehouse 区域。例如 us-east4。 为了尽可能缩短延迟时间（即使是通过公共互联网），请在选择区域时执行以下操作：

   • 如果您的 Snowflake 目录位于 AWS 上，请选择Google Cloud 距离您的 AWS 区域最近的区域。

6. 点击继续。

   系统会显示连接详细信息。

7. 在远程目录详细信息部分中，在 Snowflake 账号标识符字段中输入您的 Snowflake 账号标识符。例如：my_org-my_account。

8. 在 Snowflake 仓库字段中，输入您的 Snowflake 仓库名称。

9. 根据您选择的方法配置身份验证详细信息：

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

10. 可选：在服务目录名称字段中，输入 Service Directory 端点或服务的路径。仅当您配置专用互连 (跨云互连) 时，才需要执行此操作。

11. 点击创建。

gcloud CLI

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"

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/endpoints/ENDPOINT_NAME"

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"

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/endpoints/ENDPOINT_NAME"

REST API

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: PROJECT_ID" \
  -d '{
    "catalog-type": "CATALOG_TYPE_FEDERATED",
    "federated-catalog-options": {
      "snowflake-catalog-info": {
        "account-identifier": "SNOWFLAKE_ACCOUNT_IDENTIFIER",
        "warehouse": "SNOWFLAKE_WAREHOUSE",
        "snowflake-role": "SNOWFLAKE_ROLE"
      },
      "refresh-options": {
        "refresh-schedule": {
          "refresh-interval": "REFRESH_INTERVAL"
        }
      }
    }
}' \
  "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg_catalog_id=FEDERATED_CATALOG_NAME&primary_location=REGION"

基于 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" \
      --location="REGION" \
      --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 alpha 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 角色（必须与创建目录时指定的角色一致）。

gcloud CLI

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

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

2. 确认远程数据库架构显示为已同步的命名空间：

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

REST API

1. 验证目录联合同步状态：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME"

2. 列出已同步的命名空间：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces"

3. 列出同步命名空间中的表：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces/NAMESPACE_NAME/tables"