Configurar o endpoint do catálogo REST do Lakehouse Iceberg

Para novos catálogos, recomendamos usar o endpoint do catálogo REST do Apache Iceberg no catálogo do ambiente de execução do Lakehouse. Esse endpoint fornece uma interface totalmente gerenciada e padronizada com base na API de catálogo REST do Apache Iceberg (link em inglês) de código aberto.

Esse endpoint atua como uma única fonte de verdade, permitindo a interoperabilidade perfeita entre os mecanismos de consulta. Ele permite que mecanismos como o Apache Spark descubram, leiam e gerenciem suas tabelas do Lakehouse do Google Cloud.

Essa abordagem é uma boa opção se você usa mecanismos de OSS ou de terceiros compatíveis para acessar dados no Cloud Storage e precisa de interoperabilidade com outros mecanismos, incluindo o BigQuery. Ele oferece suporte a recursos como venda de credenciais para controle de acesso refinado e replicação entre regiões e recuperação de desastres.

Em contraste, o endpoint do catálogo personalizado do Apache Iceberg para BigQuery é uma integração anterior. Embora os fluxos de trabalho atuais possam continuar usando esse recurso, o catálogo REST oferece uma experiência mais padronizada e rica em recursos.

Antes de começar

Familiarize-se com o catálogo de ambientes de execução do Lakehouse e a visão geral do endpoint do catálogo REST do Iceberg antes de continuar.

Se você tiver tabelas do Apache Iceberg da versão 1 (V1), faça upgrade delas antes de usá-las com o endpoint do catálogo REST do Apache Iceberg. Para mais informações, consulte Fazer upgrade de tabelas do Iceberg V1 para V2.

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

Funções exigidas

Para receber as permissões necessárias a fim de usar o endpoint do catálogo REST do Apache Iceberg no catálogo de tempo de execução do Lakehouse, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Realize tarefas administrativas, como gerenciar o acesso de usuários ao catálogo, o acesso ao armazenamento e o modo de venda de credenciais do catálogo:
  • Registrar tabelas em um catálogo do BigLake: Administrador do BigLake (roles/biglake.admin) no projeto.
  • Ler dados da tabela no modo de venda de credenciais: Leitor do BigLake (roles/biglake.viewer) no projeto. Se você usar mecanismos de consulta, como o Serviço gerenciado para Apache Spark ou o Dataflow, para ler dados de tabelas, conceda essa função à conta de serviço usada para executar jobs nesse mecanismo.
  • Gravar dados da tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor) no projeto. Se você usar mecanismos de consulta, como o Serviço gerenciado para Apache Spark ou o Dataflow, para gravar dados de tabela, conceda essa função à conta de serviço usada para executar jobs nesse mecanismo.
  • Use a conta de serviço do catálogo de tempo de execução do Lakehouse provisionada automaticamente no modo de venda de credenciais: Usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets associados do Cloud Storage. Depois de criar o catálogo, conceda explicitamente o papel de usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets de armazenamento associados à conta de serviço do catálogo de tempo de execução do Lakehouse provisionada automaticamente.
  • Ler recursos do catálogo e dados da tabela no modo sem venda de credenciais:
  • Gerencie recursos de catálogo e grave dados de tabela no modo sem venda de credenciais:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Limitações

O endpoint do catálogo REST do Apache Iceberg está sujeito às seguintes limitações:

Limitações gerais

  • As tabelas do Apache Iceberg V2 (GA) e V3 (prévia) são compatíveis. Não há suporte para tabelas do Iceberg V1. Antes de usar tabelas V1 com o endpoint do catálogo REST do Apache Iceberg, é necessário fazer upgrade para uma versão compatível.
  • O Trino só é compatível com a federação de catálogos do BigQuery ao usar o Serviço Gerenciado para Apache Spark no Compute Engine 2.3 versões 2.3.16 e mais recentes.
  • Ao usar o modo de venda de credenciais, se o mecanismo de consulta permitir definir a propriedade io-impl para uma conexão de catálogo, defina-a como org.apache.iceberg.gcp.gcs.GCSFileIO.
  • No momento, não há suporte para buckets de namespaces hierárquicos no modo de venda de credenciais.

Limitações da tabela

  • Não é possível criar ou modificar tabelas no endpoint do catálogo REST do Apache Iceberg usando instruções da linguagem de definição de dados (DDL) ou da linguagem de manipulação de dados (DML) do BigQuery. É possível modificar essas tabelas usando a API BigQuery (com a ferramenta de linha de comando bq ou bibliotecas de cliente), mas isso pode causar mudanças incompatíveis com o mecanismo externo.
  • As tabelas gerenciadas pelo endpoint do catálogo REST do Apache Iceberg não são compatíveis com o controle de acesso refinado (FGAC), como segurança em nível de linha e coluna.
  • Não é permitido definir as propriedades da tabela do Iceberg write.data.path ou write.metadata.path com valores diferentes dos padrões.
  • Os caminhos de tabela precisam estar aninhados no caminho do namespace principal (por exemplo, gs://{namespace_path}/.../{table_name}). Para evitar conflitos e melhorar a segurança, um sufixo de string aleatório é anexado automaticamente ao local resultante (por exemplo, gs://{namespace_path}/{table_name}/{random_suffix}).

Limitações de dados

  • Somente arquivos Parquet são aceitos. Para mais detalhes sobre como o BigQuery processa arquivos Parquet, consulte Carregar dados Parquet do Cloud Storage.
  • O tamanho do arquivo metadata.json do Iceberg é limitado a 1 MB. Para solicitar um aumento desse limite, entre em contato com a equipe da sua Conta do Google.

Limitações de consulta

  • Não é possível consultar tabelas de metadados do Apache Iceberg (como .snapshots ou .files) no BigQuery usando identificadores de nome de cinco partes. É possível consultar essas tabelas usando o Spark.

Configurar o endpoint do catálogo REST do Iceberg

Antes de configurar o catálogo, recomendamos ler a visão geral do endpoint do catálogo REST do Apache Iceberg para entender a hierarquia de recursos, os tipos de catálogo e a estrutura de nomenclatura.

Estas são as etapas gerais a seguir ao usar o endpoint do catálogo REST do Apache Iceberg no catálogo do ambiente de execução do Lakehouse:

  1. Com base na visão geral do endpoint do catálogo REST do Iceberg, escolha o tipo de catálogo. Isso pode configurar um catálogo multi-bucket (bl://) (recomendado) ou um catálogo single-bucket (gs://).
  2. Crie um catálogo que aponte para o local do seu depósito.
  3. Configure seu aplicativo cliente para usar o endpoint do catálogo REST do Apache Iceberg.
  4. Crie um namespace ou esquema para organizar as tabelas.
  5. Crie e consulte tabelas usando o cliente configurado.

Considerações

Considere as seguintes opções para o modo de credencial e a configuração de armazenamento.

Modo de credencial (escopo)

É possível criar um catálogo que usa credenciais de usuário final ou o modo de venda de credenciais.

  • Credenciais do usuário final:o catálogo transmite a identidade do usuário final que está acessando o Cloud Storage para verificações de autorização.

  • Modo de venda de credenciais:um mecanismo de delegação de acesso ao armazenamento que permite que os administradores do catálogo de tempo de execução do Lakehouse controlem as permissões diretamente nos recursos do catálogo de tempo de execução do Lakehouse, eliminando a necessidade de os usuários do catálogo terem acesso direto aos buckets do Cloud Storage. Ele permite que os administradores do Lakehouse do Google Cloud concedam permissões aos usuários em arquivos de dados específicos.

Tipo de bucket

É possível criar um catálogo de um único bucket ou de vários buckets.

  • Vários buckets (bl://) (recomendado): essa configuração permite que seu catálogo associe vários buckets e que você nomeie o catálogo independente do nome de qualquer bucket. Não é possível usar catálogos de vários buckets no console Google Cloud .
  • Bucket único (gs://): essa configuração restringe seu catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket. Não é recomendável para novos projetos.

Local

Familiarize-se com os requisitos de local antes de criar um catálogo.

  • Quando você cria um namespace, ele usa automaticamente a mesma região do seu catálogo.

  • Se o catálogo usar um bucket multirregional e você quiser usá-lo com as multirregiões do BigQuery (US ou EU), exclua e recrie o catálogo para especificar o local principal.

Criar um catálogo

Siga estas etapas para criar um catálogo com base no modo de credencial e no tipo de bucket de sua preferência.

Credenciais do usuário final

Console

  1. Abra a página Lakehouse no console do Google Cloud .

    Acessar Lakehouse

  2. Clique em Criar catálogo.

  3. Em Tipo de catálogo, selecione Bucket do Cloud Storage.

  4. Insira ou procure o bucket do Cloud Storage a ser usado com seu catálogo. Para um catálogo de bucket único (gs://), só é possível ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.

  5. Em Método de autenticação, selecione Credenciais do usuário final.

  6. Clique em Criar.

gcloud

Criar um catálogo de vários buckets (bl://) (recomendado)

Essa configuração permite que seu catálogo associe vários buckets e permite nomear o catálogo de forma independente de qualquer nome de bucket.

Para criar um catálogo de vários buckets (bl://), que é o recomendado, execute o comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

Criar um catálogo de bucket único (gs://)

Para criar um catálogo de bucket único (gs://), execute o seguinte comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

Substitua:

  • CATALOG_NAME: um nome para o catálogo. Para catálogos de vários buckets (bl://), que é o recomendado, esse é o nome do catálogo personalizado. Para catálogos de bucket único (gs://), isso corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST. Esse nome também é usado como o identificador do catálogo ao consultar essas tabelas no BigQuery.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • DEFAULT_LOCATION: especifique o local de armazenamento padrão do catálogo. É possível especificar um bucket (gs://my-bucket) ou um subcaminho (gs://my-bucket/path). Todos os namespaces e tabelas no catálogo precisam estar no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não poderá criar namespaces ou tabelas em gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS: (opcional) lista separada por vírgulas de locais de armazenamento permitidos adicionais, no formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se você especificar um caminho (como gs://my-bucket/path), todos os namespaces ou tabelas nesse bucket precisarão estar nesse caminho. Todos os locais de armazenamento em nuvem configurados no local padrão e nos locais restritos precisam estar no mesmo grupo de região geográfica ou jurisdição (como Estados Unidos, Europa, Canadá ou Ásia). Por exemplo, não é possível misturar um bucket nos EUA com um na Europa. Para conferir uma lista de locais compatíveis, consulte Locais do Lakehouse. Aviso de segurança:evite configurar caminhos sobrepostos com outros catálogos para impedir a exposição não autorizada de credenciais. Para mais informações, consulte Armazenamento em vários buckets.
  • LOCATION: (opcional) a região principal do catálogo para garantir a interoperabilidade com o BigQuery. Para buckets do Cloud Storage na região dos EUA (por exemplo, US ou us-central1) ou na região da UE (por exemplo, EU ou europe-west4), especifique US ou EU, respectivamente, para garantir que o catálogo esteja acessível e disponível para consultas nas multirregiões correspondentes do BigQuery. Para mais informações, consulte Regiões de bucket e catálogo.

Modo de fornecimento de credenciais

Um administrador do catálogo ativa a venda de credenciais ao criar ou atualizar um catálogo. Como usuário do catálogo, você pode instruir o endpoint do catálogo REST do Apache Iceberg a retornar credenciais de armazenamento com escopo reduzido especificando a delegação de acesso ao configurar o endpoint do catálogo REST do Apache Iceberg.

A conta de serviço do catálogo de tempo de execução do Lakehouse provisionada automaticamente exige a função explícita de Usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets associados do Cloud Storage. Por padrão, ele não tem acesso. Sem essa função, as credenciais vendidas não terão escopo suficiente para realizar gravações de armazenamento. Se você usa ferramentas como gcloud ou Terraform, precisa conceder essa função manualmente.

Console

  1. No console do Google Cloud , abra a página Lakehouse.

    Acessar Lakehouse

  2. Clique em Criar catálogo. A página Criar catálogo é aberta.

  3. Em Tipo de catálogo, selecione Bucket do Cloud Storage.

  4. Insira ou procure o bucket do Cloud Storage a ser usado com seu catálogo. Para um catálogo de bucket único (gs://), só é possível ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.

  5. Em Método de autenticação, selecione Modo de fornecimento de credenciais.

  6. Clique em Criar.

    Seu catálogo é criado e a página Detalhes do catálogo é aberta.

  7. Em Método de autenticação, clique em Definir permissões do bucket.

  8. Na caixa de diálogo, clique em Confirmar.

    Isso verifica se a conta de serviço do catálogo tem o papel de usuário de objetos do Storage em todos os buckets de armazenamento associados.

gcloud

Criar um catálogo de vários buckets (bl://) (recomendado)

Essa configuração permite que seu catálogo associe vários buckets e permite nomear o catálogo de forma independente de qualquer nome de bucket.

Para criar um catálogo de vários buckets (bl://), que é o recomendado, execute o comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS