Endpoint regional lakehouse

Dokumen ini menjelaskan cara menggunakan endpoint regional Private Service Connect untuk mengakses resource dalam katalog runtime Lakehouse. Endpoint regional memungkinkan Anda menjalankan workload dengan cara yang mematuhi persyaratan residensi data dan kedaulatan data, dengan traffic permintaan Anda dirutekan langsung ke region yang ditentukan di endpoint.

Ringkasan

Endpoint regional membatasi permintaan untuk dilanjutkan hanya jika resource katalog yang terpengaruh ada di lokasi yang ditentukan oleh endpoint. Misalnya, jika Anda menggunakan endpoint https://biglake.us-central1.rep.googleapis.com untuk mengakses katalog, namespace, atau tabel, permintaan hanya akan dilanjutkan jika katalog berada di us-central1.

Tidak seperti endpoint global, tempat permintaan dapat dirutekan melalui lokasi yang berbeda dari tempat resource berada, endpoint regional membatasi permintaan Anda ke lokasi yang ditentukan oleh endpoint tempat resource berada. Endpoint regional mengakhiri sesi Transport Layer Security (TLS) di lokasi yang ditentukan oleh endpoint untuk permintaan yang diterima dari internet, resource Google Cloud lain seperti virtual machine Compute Engine, layanan lokal yang menggunakan Cloud VPN atau Cloud Interconnect, dan Virtual Private Cloud (VPC).

Endpoint regional membantu memastikan residensi data dengan menjaga permintaan katalog dalam pengiriman Anda tetap berada dalam lokasi yang ditentukan oleh endpoint. Untuk mengetahui informasi selengkapnya tentang cara penanganan metadata layanan, lihat Catatan tentang data layanan.

Endpoint katalog berikut di katalog runtime Lakehouse tersedia untuk digunakan dengan endpoint regional:

Endpoint katalog URL endpoint regional Referensi
Endpoint katalog REST Apache Iceberg https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Endpoint katalog Apache Hive (Pratinjau) https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

Lokasi yang didukung

Anda dapat menggunakan endpoint regional dengan katalog runtime Lakehouse di lokasi berikut:

  • Asia-Pasifik

    • Delhi asia-south2
    • Mumbai asia-south1

  • Eropa

    • Belgia europe-west1
    • Frankfurt europe-west3
    • London europe-west2
    • Milan europe-west8
    • Belanda europe-west4
    • Paris europe-west9
    • Zürich europe-west6

  • Timur Tengah

    • Dammam me-central2

  • Amerika

    • Columbus, Ohio us-east5
    • Dallas us-south1
    • Iowa us-central1
    • Las Vegas us-west4
    • Los Angeles us-west2
    • Montréal northamerica-northeast1
    • Northern Virginia us-east4
    • Oregon us-west1
    • Salt Lake City us-west3
    • South Carolina us-east1
    • Toronto northamerica-northeast2

Operasi dan lokasi penyimpanan yang didukung

Endpoint regional hanya dapat digunakan untuk melakukan operasi yang mengakses atau mengubah resource katalog yang direplikasi di lokasi yang ditentukan oleh endpoint:

  • Isolasi katalog regional: Mencantumkan katalog melalui https://biglake.LOCATION.rep.googleapis.com hanya menampilkan katalog yang berada di LOCATION. Permintaan untuk mendapatkan, memperbarui, atau menghapus katalog, namespace, atau tabel yang berada di luar LOCATION akan menampilkan error 404 NOT_FOUND.
  • Lokasi penyimpanan default: Saat Anda membuat katalog menggunakan endpoint regional, bucket Cloud Storage yang ditentukan di default_location untuk katalog multi-bucket (CATALOG_TYPE_BIGLAKE) atau bucket yang terkait dengan katalog bucket tunggal (CATALOG_TYPE_GCS_BUCKET) harus berada di LOCATION.
  • Lokasi terbatas katalog multi-bucket: Untuk katalog multi-bucket, Anda dapat mengonfigurasi bucket Cloud Storage tambahan di restricted_locations selama bucket tersebut berada dalam yurisdiksi geografis yang sama (seperti AS atau Eropa) dengan LOCATION. Untuk mengetahui informasi selengkapnya, lihat Katalog multi-bucket.

Pembatasan dan batasan

Endpoint regional tidak dapat digunakan untuk melakukan operasi berikut:

  • Operasi yang membaca atau mengubah katalog, namespace, atau tabel yang berada di luar region yang ditentukan oleh endpoint.
  • Perutean endpoint multiregional (seperti US atau EU). Endpoint regional harus menentukan satu region.

Perhatikan batasan berikut saat menggunakan endpoint regional:

Mengonfigurasi alat dan mesin kueri

Anda dapat mengonfigurasi Google Cloud CLI, Apache Spark, Trino, dan permintaan REST API langsung untuk menggunakan endpoint regional.

gcloud CLI

Untuk mengonfigurasi gcloud CLI agar menggunakan endpoint regional dengan perintah gcloud biglake, tetapkan properti api_endpoint_overrides/biglake ke endpoint regional yang ingin Anda gunakan:

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

Atau, Anda dapat menetapkan variabel lingkungan CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE untuk setiap perintah:

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

Ganti kode berikut:

  • LOCATION: wilayah yang didukung untuk katalog Anda (misalnya, us-central1).
  • PROJECT_ID: Google Cloud Project ID Anda.

Apache Spark

Saat mengonfigurasi sesi Spark untuk terhubung ke endpoint katalog REST Apache Iceberg, tetapkan properti spark.sql.catalog.CATALOG_NAME.uri ke URL endpoint regional:

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()

Ganti kode berikut:

  • CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog).
  • APP_NAME: nama untuk sesi Spark Anda.
  • LOCATION: wilayah yang didukung tempat katalog berada (misalnya, us-central1).
  • PROJECT_ID: Google Cloud Project ID Anda.
  • CATALOG_ID: ID katalog multi-bucket Anda.

Untuk opsi konfigurasi lainnya, lihat Menyiapkan endpoint katalog REST Apache Iceberg.

Trino

Saat membuat cluster Managed Service untuk Apache Spark dengan komponen Trino, tetapkan trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri ke URL endpoint regional:

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"

Ganti kode berikut:

  • CLUSTER_NAME: nama untuk cluster Anda.
  • LOCATION: wilayah yang didukung untuk cluster dan katalog Anda.
  • DATAPROC_VERSION: versi image Managed Service untuk Apache Spark (misalnya, 2.2).
  • NETWORK_ID: ID jaringan cluster.
  • CATALOG_NAME: nama katalog Trino Anda.
  • PROJECT_ID: Google Cloud Project ID Anda.
  • CATALOG_ID: ID katalog multi-bucket Anda.

REST API

Daripada mengirim permintaan REST ke endpoint global (https://biglake.googleapis.com), kirim permintaan ke endpoint regional dalam format berikut: https://biglake.LOCATION.rep.googleapis.com.

Misalnya, untuk mencantumkan katalog di LOCATION menggunakan API ekstensi endpoint katalog REST Apache Iceberg:

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"

Membatasi penggunaan endpoint API global

Untuk membantu menerapkan penggunaan endpoint regional, gunakan batasan kebijakan organisasi constraints/gcp.restrictEndpointUsage untuk memblokir permintaan ke endpoint API global (biglake.googleapis.com). Untuk mengetahui informasi selengkapnya, lihat Membatasi penggunaan endpoint.

Contoh file YAML kebijakan organisasi berikut menolak permintaan ke endpoint biglake.googleapis.com global sekaligus mengizinkan permintaan ke endpoint regional:

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

Langkah berikutnya