Endpoint regionali Lakehouse

Questo documento descrive come utilizzare gli endpoint regionali di Private Service Connect per accedere alle risorse nel catalogo di runtime di Lakehouse. Gli endpoint regionali ti consentono di eseguire i workload in modo conforme ai requisiti di residenza dei dati e sovranità dei dati, in cui il traffico delle richieste viene instradato direttamente alla regione specificata nell'endpoint.

Panoramica

Gli endpoint regionali limitano le richieste in modo che procedano solo se la risorsa del catalogo interessata esiste nella località specificata dall'endpoint. Ad esempio, se utilizzi l'endpoint https://biglake.us-central1.rep.googleapis.com per accedere a un catalogo, uno spazio dei nomi o una tabella, la richiesta procede solo se il catalogo si trova in us-central1.

A differenza degli endpoint globali, in cui le richieste possono essere instradate attraverso una località diversa da quella in cui si trova la risorsa, gli endpoint regionali limitano le richieste alla località specificata dall'endpoint in cui si trova la risorsa. Gli endpoint regionali terminano le sessioni Transport Layer Security (TLS) nella località specificata dall'endpoint per le richieste ricevute da internet, da altre risorse Google Cloud come le macchine virtuali di Compute Engine, dai servizi on-premise che utilizzano Cloud VPN o Cloud Interconnect e dai Virtual Private Cloud (VPC).

Gli endpoint regionali contribuiscono a garantire la residenza dei dati mantenendo le richieste di catalogo in transito all'interno della località specificata dall'endpoint. Per ulteriori informazioni su come vengono gestiti i metadati del servizio, consulta Nota sui dati dei clienti e sui dati di servizio.

I seguenti endpoint del catalogo di runtime Lakehouse sono disponibili per l'utilizzo con gli endpoint regionali:

Endpoint del catalogo URL endpoint regionale Riferimento
Endpoint del catalogo REST Apache Iceberg https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Endpoint del catalogo Apache Hive https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

Località supportate

Puoi utilizzare gli endpoint regionali con il catalogo di runtime Lakehouse nelle seguenti località:

  • Asia Pacifico

    • Delhi asia-south2
    • Mumbai asia-south1
  • Europa

    • Belgio europe-west1
    • Berlino europe-west10
    • Francoforte europe-west3
    • Londra europe-west2
    • Milano europe-west8
    • Paesi Bassi europe-west4
    • Parigi europe-west9
    • Zurigo europe-west6
  • Medio Oriente

    • Dammam me-central2
  • Americhe

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

Operazioni e località di archiviazione supportate

Gli endpoint regionali possono essere utilizzati solo per eseguire operazioni che accedono o modificano le risorse del catalogo replicate nella località specificata dall'endpoint:

  • Isolamento del catalogo regionale: l'elenco dei cataloghi tramite https://biglake.LOCATION.rep.googleapis.com restituisce solo i cataloghi che si trovano in LOCATION. Le richieste di recupero, aggiornamento o eliminazione di un catalogo, uno spazio dei nomi o una tabella situati al di fuori di LOCATION restituiscono un errore 404 NOT_FOUND.
  • Posizione di archiviazione predefinita: quando crei un catalogo utilizzando un endpoint regionale, il bucket Cloud Storage specificato in default_location per un catalogo con più bucket (CATALOG_TYPE_BIGLAKE) o il bucket associato a un catalogo con un singolo bucket (CATALOG_TYPE_GCS_BUCKET) deve trovarsi in LOCATION.
  • Località limitate per i cataloghi con più bucket: per i cataloghi con più bucket, puoi configurare bucket Cloud Storage aggiuntivi in restricted_locations, a condizione che questi bucket si trovino nella stessa giurisdizione geografica (ad esempio Stati Uniti o Europa) di LOCATION. Per saperne di più, consulta Catalogo con più bucket.

Limitazioni e restrizioni

Gli endpoint regionali non possono essere utilizzati per eseguire le seguenti operazioni:

  • Operazioni che leggono o modificano cataloghi, spazi dei nomi o tabelle che si trovano al di fuori della regione specificata dall'endpoint.
  • Routing degli endpoint multiregionali (ad esempio US o EU). Gli endpoint regionali devono specificare una singola regione.

Tieni presente le seguenti limitazioni quando utilizzi gli endpoint regionali:

Configura strumenti e motori di query

Puoi configurare Google Cloud CLI, Apache Spark, Trino e le richieste API REST dirette in modo che utilizzino gli endpoint regionali.

gcloud CLI

Per configurare gcloud CLI in modo da utilizzare gli endpoint regionali con i comandi gcloud biglake, imposta la proprietà api_endpoint_overrides/biglake sull'endpoint regionale che vuoi utilizzare:

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

In alternativa, puoi impostare la variabile di ambiente CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE per i singoli comandi:

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

Sostituisci quanto segue:

  • LOCATION: la regione supportata per il tuo catalogo (ad esempio us-central1).
  • PROJECT_ID: il tuo ID progetto Google Cloud .

Apache Spark

Quando configuri una sessione Spark per connetterti all'endpoint del catalogo REST Apache Iceberg, imposta la proprietà spark.sql.catalog.CATALOG_NAME.uri sull'URL dell'endpoint regionale:

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

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog).
  • APP_NAME: un nome per la sessione Spark.
  • LOCATION: la regione supportata in cui si trova il catalogo (ad esempio us-central1).
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • CATALOG_ID: l'ID del catalogo con più bucket.

Per altre opzioni di configurazione, consulta Configura l'endpoint del catalogo REST di Apache Iceberg.

Trino

Quando crei un cluster Managed Service for Apache Spark con il componente Trino, imposta trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri sull'URL dell'endpoint regionale:

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"

Sostituisci quanto segue:

  • CLUSTER_NAME: un nome per il cluster.
  • LOCATION: la regione supportata per il cluster e il catalogo.
  • DATAPROC_VERSION: la versione immagine di Managed Service for Apache Spark (ad esempio 2.2).
  • NETWORK_ID: l'ID della rete del cluster.
  • CATALOG_NAME: il nome del catalogo Trino.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • CATALOG_ID: l'ID del catalogo con più bucket.

API REST

Anziché inviare una richiesta REST all'endpoint globale (https://biglake.googleapis.com), invia la richiesta all'endpoint regionale nel seguente formato: https://biglake.LOCATION.rep.googleapis.com.

Ad esempio, per elencare i cataloghi in LOCATION utilizzando l'API delle estensioni degli endpoint del catalogo REST di 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"

Limita l'utilizzo degli endpoint API globali

Per contribuire a imporre l'utilizzo di endpoint regionali, utilizza il vincolo delle policy dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale (biglake.googleapis.com). Per saperne di più, consulta Limita l'utilizzo degli endpoint.

Il seguente file YAML di esempio della policy dell'organizzazione nega le richieste all'endpoint biglake.googleapis.com globale, consentendo al contempo le richieste agli endpoint regionali:

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

Passaggi successivi