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
- Delhi
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
- Belgio
Medio Oriente
- Dammam
me-central2
- Dammam
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
- Columbus, Ohio
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.comrestituisce solo i cataloghi che si trovano inLOCATION. Le richieste di recupero, aggiornamento o eliminazione di un catalogo, uno spazio dei nomi o una tabella situati al di fuori diLOCATIONrestituiscono un errore404 NOT_FOUND. - Posizione di archiviazione predefinita: quando crei un catalogo utilizzando un endpoint regionale, il bucket Cloud Storage specificato in
default_locationper 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 inLOCATION. - 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) diLOCATION. 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
USoEU). Gli endpoint regionali devono specificare una singola regione.
Tieni presente le seguenti limitazioni quando utilizzi gli endpoint regionali:
- Gli endpoint regionali non supportano mutual Transport Layer Security (mTLS).
- L'utilizzo di un endpoint regionale non impedisce agli utenti di creare risorse in altre regioni o di chiamare l'endpoint globale (
biglake.googleapis.com). Per applicare le limitazioni regionali, configura il vincolo delle località delle risorse del servizio policy dell'organizzazione e limita l'utilizzo degli endpoint API globali.
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 esempious-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 esempiomy_catalog).APP_NAME: un nome per la sessione Spark.LOCATION: la regione supportata in cui si trova il catalogo (ad esempious-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 esempio2.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
- Scopri di più sull'endpoint del catalogo REST Apache Iceberg.
- Configura l'endpoint del catalogo REST Apache Iceberg.
- Scopri di più su Identity and Access Management e sul controllo degli accessi.