Endpoints regionais do Lakehouse

Neste documento, descrevemos como usar 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 suas cargas de trabalho de maneira que obedeça aos requisitos de residência de dados e 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 só sejam processadas 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 encaminhadas por um local diferente de onde o recurso reside, os endpoints regionais restringem suas solicitações ao local especificado pelo endpoint onde o recurso reside. Os endpoints regionais encerram sessões 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 usando 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 tratados, consulte Observação sobre 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 (prévia) https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

Locais suportados

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

  • Ásia-Pacífico

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

  • Europa

    • Bélgica europe-west1
    • 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: a listagem de catálogos usando 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: ao criar 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 um único bucket (CATALOG_TYPE_GCS_BUCKET) precisa estar em LOCATION.
  • Locais restritos de catálogos com vários buckets: para catálogos com 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 EUA ou Europa) de 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 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 sua 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 seu catálogo de vários intervalos.

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 seu catálogo de vários intervalos.

APIs REST

Em vez de enviar uma solicitação REST para o endpoint global (https://biglake.googleapis.com), envie 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 a seguir de arquivo YAML de política da organização nega solicitações ao endpoint global biglake.googleapis.com, mas permite solicitações aos endpoints regionais:

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

A seguir