Lakehouse 区域级端点

本文档介绍了如何使用 Private Service Connect 区域端点来访问 Lakehouse 运行时目录中的资源。借助区域端点，您可以根据符合数据驻留和数据主权要求的方式运行工作负载，此时请求流量会直接路由到端点中指定的区域。

概览

区域端点会限制请求，只有当受影响的目录资源存在于端点指定的位置时，请求才能继续处理。例如，如果您使用端点 https://biglake.us-central1.rep.googleapis.com 访问目录、命名空间或表，则仅当目录位于 us-central1 中时，请求才会继续。

全球端点可将请求路由到资源所在位置之外的其他位置；与此不同，区域端点可将请求限制在资源所在的、由端点指定的位置。对于从互联网、其他 Google Cloud 资源（例如 Compute Engine 虚拟机）、使用 Cloud VPN 或 Cloud Interconnect 的本地服务以及虚拟私有云 (VPC) 收到的请求，区域端点会在端点指定的位置终止传输层安全协议 (TLS) 会话。

区域端点有助于确保数据驻留，因为它们会将传输中的目录请求保留在端点指定的位置。如需详细了解服务元数据的处理方式，请参阅有关服务数据的说明。

Lakehouse 运行时目录中的以下目录端点可与区域端点搭配使用：

目录端点 区域端点网址 参考文档
Apache Iceberg REST 目录端点 https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Apache Hive 目录端点（预览版） https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

支持的位置

您可以在以下位置将区域端点与 Lakehouse 运行时目录搭配使用：

  • 亚太地区

    • 德里 asia-south2
    • 孟买 asia-south1

  • 欧洲

    • 比利时 europe-west1
    • 法兰克福 europe-west3
    • 伦敦 europe-west2
    • 米兰 europe-west8
    • 荷兰 europe-west4
    • 巴黎 europe-west9
    • 苏黎世 europe-west6

  • 中东

    • 达曼 me-central2

  • 美洲

    • 俄亥俄州，哥伦布 us-east5
    • 达拉斯 us-south1
    • 艾奥瓦 us-central1
    • 拉斯维加斯 us-west4
    • 洛杉矶 us-west2
    • 蒙特利尔 northamerica-northeast1
    • 北弗吉尼亚 us-east4
    • 俄勒冈 us-west1
    • 盐湖城 us-west3
    • 南卡罗来纳 us-east1
    • 多伦多 northamerica-northeast2

支持的操作和存储位置

区域端点只能用于执行访问或更改端点所指定位置内复制的目录资源的操作：

  • 区域目录隔离：通过 https://biglake.LOCATION.rep.googleapis.com 列出目录时，只会返回位于 LOCATION 中的目录。如果请求获取、更新或删除位于 LOCATION 之外的目录、命名空间或表，则会返回 404 NOT_FOUND 错误。
  • 默认存储位置：使用区域端点创建目录时，default_location 中为多存储桶目录 (CATALOG_TYPE_BIGLAKE) 指定的 Cloud Storage 存储桶或与单存储桶目录 (CATALOG_TYPE_GCS_BUCKET) 关联的存储桶必须位于 LOCATION 中。
  • 多存储桶目录受限位置：对于多存储桶目录，您可以在 restricted_locations 中配置其他 Cloud Storage 存储桶，前提是这些存储桶与 LOCATION 位于同一地理管辖区（例如美国或欧洲）。如需了解详情，请参阅多存储桶目录。

局限和限制

区域端点不能用于执行以下操作：

  • 读取或修改端点所指定区域以外的目录、命名空间或表的操作。
  • 多区域端点路由（例如 US 或 EU）。区域级端点必须指定单个区域。

使用区域端点时，请注意以下限制：

配置工具和查询引擎

您可以配置 Google Cloud CLI、Apache Spark、Trino 和直接 REST API 请求，以使用区域端点。

gcloud CLI

如需将 gcloud CLI 配置为通过 gcloud biglake 命令使用区域端点，请将 api_endpoint_overrides/biglake 属性设置为您要使用的区域端点：

gcloud config set api_endpoint_overrides/biglake https://biglake.LOCATION.rep.googleapis.com/

或者，您也可以为各个命令设置 CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE 环境变量：

CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE=https://biglake.LOCATION.rep.googleapis.com/ \
    gcloud biglake iceberg catalogs list --project=PROJECT_ID

替换以下内容：

Apache Spark

在配置 Spark 会话以连接到 Apache Iceberg REST Catalog 端点时，请将 spark.sql.catalog.CATALOG_NAME.uri 属性设置为区域端点网址：

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
    .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
    .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
    .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/CATALOG_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
    .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
    .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .getOrCreate()

替换以下内容：

  • CATALOG_NAME：本地 Spark 目录的名称（例如 my_catalog）。
  • APP_NAME：Spark 会话的名称。
  • LOCATION：目录所在的受支持的国家/地区（例如 us-central1）。
  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • CATALOG_ID：多存储桶目录的 ID。

如需了解更多配置选项，请参阅设置 Apache Iceberg REST Catalog 端点。

Trino

创建包含 Trino 组件的 Managed Service for Apache Spark 集群时，请将 trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri 设置为区域端点网址：

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=LOCATION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=bl://projects/PROJECT_ID/catalogs/CATALOG_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

替换以下内容：

  • CLUSTER_NAME：集群的名称。
  • LOCATION：集群和目录的受支持区域。
  • DATAPROC_VERSION：Managed Service for Apache Spark 映像版本（例如 2.2）。
  • NETWORK_ID：集群网络 ID。
  • CATALOG_NAME：Trino 目录的名称。
  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • CATALOG_ID：多存储桶目录的 ID。

REST API

请向区域端点（而非全球端点 [https://biglake.googleapis.com]）发送 REST 请求，格式如下：https://biglake.LOCATION.rep.googleapis.com。

例如，如需使用 Apache Iceberg REST 目录端点扩展 API 列出 LOCATION 中的目录，请执行以下操作：

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

限制全球 API 端点用量

为了帮助强制使用区域端点，请使用 constraints/gcp.restrictEndpointUsage 组织政策限制条件来阻止对全球 API 端点 (biglake.googleapis.com) 的请求。如需了解详情，请参阅限制端点用量。

以下组织政策 YAML 文件会拒绝向全局 biglake.googleapis.com 端点发出的请求，同时允许向区域端点发出的请求：

name: projects/PROJECT_ID/policies/gcp.restrictEndpointUsage
spec:
  rules:
  - values:
      deniedValues:
      - under:services/biglake.googleapis.com

后续步骤