Endpoint regionali Lakehouse

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

Panoramica

Gli endpoint regionali limitano le richieste a procedere solo se la risorsa 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 tramite 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 posizione specificata dall'endpoint per le richieste ricevute da internet, da altre risorse Google Cloud come le macchine virtuali 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 saperne di più su come vengono gestiti i metadati del servizio, consulta Nota sui dati del servizio.

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

Endpoint catalogo URL dell'endpoint regionale Riferimento
Endpoint del catalogo REST Apache Iceberg https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Endpoint del catalogo Apache Hive (anteprima) 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
    • 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 posizioni 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 dei cataloghi regionali: l'elenco dei cataloghi tramite https://biglake.LOCATION.rep.googleapis.com restituisce solo i cataloghi che si trovano in LOCATION. Le richieste per ottenere, aggiornare o eliminare un catalogo, uno spazio dei nomi o una tabella che si trova 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 solo bucket (CATALOG_TYPE_GCS_BUCKET) deve trovarsi in LOCATION.
  • Località con limitazioni per cataloghi con più bucket: per i cataloghi con più bucket, puoi configurare bucket Cloud Storage aggiuntivi in restricted_locations, a condizione che si trovino nella stessa giurisdizione geografica (ad esempio Stati Uniti o Europa) di LOCATION. Per saperne di più, consulta Catalogo multibucket.

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 per utilizzare endpoint regionali.

gcloud CLI

Per configurare gcloud CLI in modo da utilizzare 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 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 multibucket.

Per altre opzioni di configurazione, consulta Configura l'endpoint del catalogo REST 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 dell'immagine di Managed Service for Apache Spark (ad esempio 2.2).
  • NETWORK_ID: l'ID rete del cluster.
  • CATALOG_NAME: il nome del catalogo Trino.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • CATALOG_ID: l'ID del catalogo multibucket.

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 dell'endpoint del catalogo 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"

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 Limitazione dell'utilizzo degli endpoint.

Il seguente file YAML 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