Endpoints regionais do Lakehouse

Neste documento, descrevemos como usar os endpoints regionais do Private Service Connect para acessar recursos no catálogo do ambiente de execução do Lakehouse. Os endpoints regionais permitem que você execute as cargas de trabalho de maneira que obedeça aos requisitos de residência de dados e de soberania de dados, em que o tráfego da solicitação é roteado diretamente para a região especificada no endpoint.

Visão geral

Os endpoints regionais restringem as solicitações para que elas prossigam apenas se o recurso de catálogo afetado existir no local especificado pelo endpoint. Por exemplo, se você usar o endpoint https://biglake.us-central1.rep.googleapis.com para acessar um catálogo, namespace ou tabela, a solicitação só vai prosseguir se o catálogo estiver localizado em us-central1.

Ao contrário dos endpoints globais, em que as solicitações podem ser roteadas por um local diferente de onde o recurso reside, os endpoints regionais restringem as solicitações ao local especificado pelo endpoint em que o recurso reside. Os endpoints regionais encerram sessões do Transport Layer Security (TLS) no local especificado pelo endpoint para solicitações recebidas da Internet, outros recursos do Google Cloud , como máquinas virtuais do Compute Engine, serviços locais que usam o Cloud VPN ou o Cloud Interconnect e nuvens privadas virtuais (VPCs).

Os endpoints regionais ajudam a garantir a residência de dados, mantendo as solicitações de catálogo em trânsito no local especificado pelo endpoint. Para mais informações sobre como os metadados de serviço são processados, consulte Observação sobre dados do cliente e dados de serviço.

Os seguintes endpoints do catálogo do ambiente de execução do Lakehouse estão disponíveis para uso com endpoints regionais:

Endpoint do catálogo URL do endpoint regional Referência
Endpoint do catálogo REST do Apache Iceberg https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Endpoint do catálogo do Apache Hive https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

Locais suportados

É possível usar endpoints regionais com o catálogo do ambiente de execução do Lakehouse nos seguintes locais:

  • Ásia-Pacífico

    • Délhi asia-south2
    • Mumbai (asia-south1)
  • Europa

    • Bélgica europe-west1
    • Berlim europe-west10
    • Frankfurt (europe-west3)
    • Londres (europe-west2)
    • Milão europe-west8
    • Países Baixos europe-west4
    • Paris europe-west9
    • Zurique (europe-west6)
  • Oriente Médio

    • Damã me-central2
  • Américas

    • Columbus, Ohio us-east5
    • Dallas us-south1
    • Iowa us-central1
    • Las Vegas (us-west4)
    • Los Angeles (us-west2)
    • Montreal (northamerica-northeast1)
    • Norte da Virgínia (us-east4)
    • Oregon us-west1
    • Salt Lake City (us-west3)
    • Carolina do Sul (us-east1)
    • Toronto northamerica-northeast2

Operações e locais de armazenamento compatíveis

Os endpoints regionais só podem ser usados para executar operações que acessam ou modificam recursos de catálogo replicados no local especificado pelo endpoint:

  • Isolamento de catálogo regional: listar catálogos por meio de https://biglake.LOCATION.rep.googleapis.com retorna apenas catálogos localizados em LOCATION. As solicitações para receber, atualizar ou excluir um catálogo, namespace ou tabela localizada fora de LOCATION retornam um erro 404 NOT_FOUND.
  • Local de armazenamento padrão: quando você cria um catálogo usando um endpoint regional, o bucket do Cloud Storage especificado em default_location para um catálogo de vários buckets (CATALOG_TYPE_BIGLAKE) ou o bucket associado a um catálogo de bucket único (CATALOG_TYPE_GCS_BUCKET) precisa residir em LOCATION.
  • Locais restritos do catálogo de vários buckets: para catálogos de vários buckets, é possível configurar outros buckets do Cloud Storage em restricted_locations, desde que eles estejam na mesma jurisdição geográfica (como os EUA ou a Europa) que LOCATION. Para mais informações, consulte Catálogo de vários buckets.

Limitações e restrições

Os endpoints regionais não podem ser usados para realizar as seguintes operações:

  • Operações que leem ou modificam catálogos, namespaces ou tabelas localizados fora da região especificada pelo endpoint.
  • Roteamento de endpoint multirregional (como US ou EU). Os endpoints regionais precisam especificar uma única região.

Considere as seguintes restrições ao usar endpoints regionais:

Configurar ferramentas e mecanismos de consulta

É possível configurar a Google Cloud CLI, o Apache Spark, o Trino e as solicitações diretas da API REST para usar endpoints regionais.

CLI da gcloud

Para configurar a CLI gcloud para usar endpoints regionais com comandos gcloud biglake, defina a propriedade api_endpoint_overrides/biglake como o endpoint regional que você quer usar:

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

Como alternativa, é possível definir a variável de ambiente CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE para comandos individuais:

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

Substitua:

Apache Spark

Ao configurar uma sessão do Spark para se conectar ao endpoint do catálogo REST do Apache Iceberg, defina a propriedade spark.sql.catalog.CATALOG_NAME.uri como o URL do 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()

Substitua:

  • CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog).
  • APP_NAME: um nome para a sessão do Spark.
  • LOCATION: a região com disponibilidade em que o catálogo está localizado (por exemplo, us-central1).
  • PROJECT_ID: o ID do projeto Google Cloud .
  • CATALOG_ID: o ID do catálogo de vários buckets.

Para mais opções de configuração, consulte Configurar o endpoint do catálogo REST do Apache Iceberg.

Trino

Ao criar um cluster do Serviço Gerenciado para Apache Spark com o componente Trino, defina trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri como o URL do 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"

Substitua:

  • CLUSTER_NAME: um nome para o cluster.
  • LOCATION: a região com disponibilidade para o cluster e o catálogo.
  • DATAPROC_VERSION: a versão de imagem do Serviço Gerenciado para Apache Spark (por exemplo, 2.2).
  • NETWORK_ID: o ID da rede do cluster.
  • CATALOG_NAME: o nome do catálogo do Trino.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • CATALOG_ID: o ID do catálogo de vários buckets.

APIs REST

Em vez de enviar uma solicitação REST para o endpoint global (https://biglake.googleapis.com), envie a solicitação para o endpoint regional no seguinte formato: https://biglake.LOCATION.rep.googleapis.com.

Por exemplo, para listar catálogos em LOCATION usando a API de extensões de endpoint do catálogo REST do 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"

Restringir o uso de endpoints de API globais

Para ajudar a aplicar o uso de endpoints regionais, utilize a restrição de política da organização constraints/gcp.restrictEndpointUsage para bloquear solicitações ao endpoint de API global (biglake.googleapis.com). Para mais informações, consulte Restringir o uso de endpoints.

O exemplo de arquivo YAML de política da organização a seguir nega solicitações ao endpoint global biglake.googleapis.com, mas permite solicitações a endpoints regionais:

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

A seguir