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)
- Délhi
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)
- Bélgica
Oriente Médio
- Damã
me-central2
- Damã
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
- Columbus, Ohio
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.comretorna apenas catálogos localizados emLOCATION. As solicitações para receber, atualizar ou excluir um catálogo, namespace ou tabela localizada fora deLOCATIONretornam um erro404 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_locationpara 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 emLOCATION. - 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) queLOCATION. 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
USouEU). Os endpoints regionais precisam especificar uma única região.
Considere as seguintes restrições ao usar endpoints regionais:
- Os endpoints regionais não são compatíveis com o Mutual Transport Layer Security (mTLS).
- O uso de um endpoint regional não impede que os usuários criem
recursos em outras regiões ou chamem o endpoint global
(
biglake.googleapis.com). Para aplicar restrições regionais, configure a restrição de locais de recursos do serviço de políticas da organização e restrinja o uso do endpoint de API global da API.
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:
LOCATION: a região com disponibilidade para seu catálogo (por exemplo,us-central1).PROJECT_ID: o ID do projeto Google Cloud .
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
- Saiba mais sobre o endpoint do catálogo REST do Apache Iceberg.
- Configure o endpoint do catálogo REST do Apache Iceberg.
- Saiba mais sobre o Identity and Access Management e o controle de acesso.