Points de terminaison régionaux Lakehouse

Ce document explique comment utiliser les points de terminaison régionaux Private Service Connect pour accéder aux ressources du catalogue Lakehouse Runtime. Les points de terminaison régionaux vous permettent d'exécuter vos charges de travail de manière conforme aux exigences de résidence des données et de souveraineté des données, où le trafic de votre requête est directement acheminé vers la région spécifiée dans le point de terminaison.

Présentation

Les points de terminaison régionaux limitent le traitement des requêtes aux ressources de catalogue concernées qui existent dans l'emplacement spécifié par le point de terminaison. Par exemple, si vous utilisez le point de terminaison https://biglake.us-central1.rep.googleapis.com pour accéder à un catalogue, un espace de noms ou une table, la requête n'est exécutée que si le catalogue se trouve dans us-central1.

Contrairement aux points de terminaison mondiaux, où les requêtes peuvent être acheminées vers un emplacement différent de celui où se trouve la ressource, les points de terminaison régionaux limitent vos requêtes à l'emplacement spécifié par le point de terminaison, où réside la ressource. Les points de terminaison régionaux interrompent les sessions TLS (Transport Layer Security) à l'emplacement spécifié par le point de terminaison pour les requêtes reçues d'Internet, d'autres ressources Google Cloud telles que les machines virtuelles Compute Engine, les services sur site utilisant Cloud VPN ou Cloud Interconnect, et les clouds privés virtuels (VPC).

Les points de terminaison régionaux contribuent à assurer la résidence des données en conservant vos demandes de catalogue en transit dans l'emplacement spécifié par le point de terminaison. Pour en savoir plus sur la façon dont les métadonnées de service sont traitées, consultez Remarque sur les données de service.

Les points de terminaison de catalogue suivants du catalogue d'environnements d'exécution Lakehouse peuvent être utilisés avec des points de terminaison régionaux :

Point de terminaison du catalogue URL du point de terminaison régional Référence
Point de terminaison du catalogue REST Apache Iceberg https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Point de terminaison du catalogue Apache Hive (aperçu) https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

Pays acceptés

Vous pouvez utiliser des points de terminaison régionaux avec le catalogue d'exécution Lakehouse dans les régions suivantes :

  • Asie-Pacifique

    • Delhi asia-south2
    • Mumbai (asia-south1)

  • Europe

    • Belgique europe-west1
    • Francfort (europe-west3)
    • Londres (europe-west2)
    • Milan europe-west8
    • Pays-Bas europe-west4
    • Paris europe-west9
    • Zurich (europe-west6)

  • Moyen-Orient

    • Dammam me-central2

  • Amériques

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

Opérations et emplacements de stockage compatibles

Les points de terminaison régionaux ne peuvent être utilisés que pour effectuer des opérations qui accèdent à des ressources de catalogue répliquées dans l'emplacement spécifié par le point de terminaison ou les modifient :

  • Isolation régionale des catalogues : la liste des catalogues via https://biglake.LOCATION.rep.googleapis.com ne renvoie que les catalogues situés dans LOCATION. Les requêtes permettant d'obtenir, de mettre à jour ou de supprimer un catalogue, un espace de noms ou une table situés en dehors de LOCATION renvoient une erreur 404 NOT_FOUND.
  • Emplacement de stockage par défaut : lorsque vous créez un catalogue à l'aide d'un point de terminaison régional, le bucket Cloud Storage spécifié dans default_location pour un catalogue à plusieurs buckets (CATALOG_TYPE_BIGLAKE) ou le bucket associé à un catalogue à un seul bucket (CATALOG_TYPE_GCS_BUCKET) doit résider dans LOCATION.
  • Emplacements restreints pour les catalogues à plusieurs buckets : pour les catalogues à plusieurs buckets, vous pouvez configurer des buckets Cloud Storage supplémentaires dans restricted_locations à condition qu'ils se trouvent dans la même juridiction géographique (par exemple, aux États-Unis ou en Europe) que LOCATION. Pour en savoir plus, consultez Catalogue multibuckets.

Limites et restrictions

Les points de terminaison régionaux ne peuvent pas être utilisés pour effectuer les opérations suivantes :

  • Opérations qui lisent ou modifient des catalogues, des espaces de noms ou des tables situés en dehors de la région spécifiée par le point de terminaison.
  • Le routage des points de terminaison multirégionaux (comme US ou EU). Les points de terminaison régionaux doivent spécifier une seule région.

Gardez à l'esprit les restrictions suivantes lorsque vous utilisez des points de terminaison régionaux :

Configurer des outils et des moteurs de requête

Vous pouvez configurer la Google Cloud CLI, Apache Spark, Trino et les requêtes directes de l'API REST pour utiliser des points de terminaison régionaux.

gcloud CLI

Pour configurer la gcloud CLI afin d'utiliser des points de terminaison régionaux avec les commandes gcloud biglake, définissez la propriété api_endpoint_overrides/biglake sur le point de terminaison régional que vous souhaitez utiliser :

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

Vous pouvez également définir la variable d'environnement CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE pour des commandes individuelles :

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

Remplacez les éléments suivants :

  • LOCATION : région prise en charge pour votre catalogue (par exemple, us-central1).
  • PROJECT_ID : ID de votre projet Google Cloud .

Apache Spark

Lorsque vous configurez une session Spark pour vous connecter au point de terminaison du catalogue Apache Iceberg REST, définissez la propriété spark.sql.catalog.CATALOG_NAME.uri sur l'URL du point de terminaison régional :

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

Remplacez les éléments suivants :

  • CATALOG_NAME : nom du catalogue Spark local (par exemple, my_catalog).
  • APP_NAME : nom de votre session Spark.
  • LOCATION : région prise en charge où se trouve le catalogue (par exemple, us-central1).
  • PROJECT_ID : ID de votre projet Google Cloud .
  • CATALOG_ID : ID de votre catalogue multiboutique.

Pour en savoir plus sur les options de configuration, consultez Configurer le point de terminaison du catalogue Apache Iceberg REST.

Trino

Lorsque vous créez un cluster Managed Service pour Apache Spark avec le composant Trino, définissez trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri sur l'URL du point de terminaison régional :

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"

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom de votre cluster.
  • LOCATION : région prise en charge pour votre cluster et votre catalogue.
  • DATAPROC_VERSION : version de l'image Managed Service pour Apache Spark (par exemple, 2.2).
  • NETWORK_ID : ID du réseau du cluster.
  • CATALOG_NAME : nom de votre catalogue Trino.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • CATALOG_ID : ID de votre catalogue multiboutique.

API REST

Au lieu d'envoyer une requête REST au point de terminaison global (https://biglake.googleapis.com), envoyez-la au point de terminaison régional au format suivant : https://biglake.LOCATION.rep.googleapis.com.

Par exemple, pour lister les catalogues dans LOCATION à l'aide de l'API d'extensions de point de terminaison du catalogue 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"

Restreindre l'utilisation des points de terminaison d'API mondiaux

Pour appliquer l'utilisation de points de terminaison régionaux, utilisez la contrainte de règle d'administration constraints/gcp.restrictEndpointUsage afin de bloquer les requêtes envoyées au point de terminaison de l'API mondial (biglake.googleapis.com). Pour en savoir plus, consultez Restreindre l'utilisation des points de terminaison.

L'exemple de fichier YAML de règle d'administration suivant refuse les requêtes envoyées au point de terminaison biglake.googleapis.com mondial, tout en autorisant les requêtes envoyées aux points de terminaison régionaux :

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

Étapes suivantes