Criar um catálogo

O catálogo do ambiente de execução do Lakehouse permite criar endpoints de catálogo no Lakehouse sem fronteiras.

Um endpoint de catálogo aponta para um bucket do Cloud Storage e fornece uma camada de metadados que permite que mecanismos de consulta e cargas de trabalho de código aberto interajam diretamente com suas tabelas. Ao criar um endpoint de catálogo, é possível escolher entre as credenciais do usuário final e o modo de venda de credenciais para delegação de acesso ao armazenamento.

Antes de começar

1. Leia Sobre o catálogo do ambiente de execução do Lakehouse para entender como ele funciona e as limitações do serviço.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Funções exigidas

Para receber as permissões necessárias para criar um catálogo e registrar tabelas, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Crie um catálogo:
  • Administrador do BigLake (roles/biglake.admin) no projeto
  • Administrador do Storage (roles/storage.admin) no projeto
• Criar (registrar) tabelas: Administrador do BigLake (roles/biglake.admin) no projeto. O registro de tabelas requer a permissão específica de registro de tabelas (biglake.tables.register), que está incluída no papel de administrador do BigLake.
• Use a conta de serviço do catálogo provisionada automaticamente no modo de venda de credenciais: Usuário de objetos do Storage (roles/storage.objectUser) nos buckets de destino do Cloud Storage. Depois de criar o catálogo, conceda explicitamente o papel de Usuário de objetos do Storage (roles/storage.objectUser) nos buckets de armazenamento à conta de serviço de provisionamento automático.

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.

Observação: a criação da conta de serviço de catálogo com provisionamento automático é eventualmente consistente, o que significa que leva tempo para que a conta de serviço seja propagada pelo sistema. Se você tentar conceder papéis à conta de serviço imediatamente após a criação, a solicitação poderá falhar. Para saber quanto tempo leva, em média, para as alterações de acesso serem propagadas, consulte Propagação de mudança de acesso.

Se os buckets do Cloud Storage associados a um endpoint de catálogo no modo de venda de credenciais estiverem protegidos por um perímetro de serviço do VPC Service Controls, também será necessário configurar uma regra de entrada para a conta de serviço do endpoint de catálogo. Para mais informações, consulte Usar o VPC Service Controls com a venda de credenciais.

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. Para mais informações sobre os diferentes tipos de catálogo, consulte Sobre o endpoint do catálogo REST do Apache Iceberg.

Observação: ao criar ou gerenciar um catálogo de vários buckets no Google Cloud, especifique os caminhos do Cloud Storage (gs://) para os locais de armazenamento padrão e restrito. O formato de URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID é usado exclusivamente durante a configuração do cliente para identificar o data warehouse do catálogo ao se conectar de mecanismos de consulta (como Apache Spark ou Trino).

Console

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

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

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

   Acessar o Lakehouse

2. Clique em Criar catálogo e selecione Catálogo do ambiente de execução do Lakehouse.

3. Em Tipo de catálogo, selecione Catálogo REST do Iceberg.

4. Em Opções de bucket do catálogo do Lakehouse, selecione Catálogo de vários buckets.

5. Em Caminho padrão do Cloud Storage do catálogo, insira ou procure o caminho do Cloud Storage que será usado com o catálogo.

6. Em ID do catálogo, insira um nome personalizado para o catálogo.

7. Em Local principal, selecione um local. O local precisa estar perto das regiões do bucket principal.

8. Clique em Continuar.

9. Na etapa Caminhos de dados, se você quiser adicionar outros caminhos do Cloud Storage, clique em Adicionar caminho e insira ou procure um caminho.

10. Clique em Continuar.

11. Em Método de autenticação, selecione Credenciais de usuário final ou Modo de venda de credenciais.

    Observação: se você selecionar Credenciais do usuário final, o catálogo do ambiente de execução do Lakehouse não vai gerenciar automaticamente as tabelas no catálogo. Não é possível ativar tarefas de gerenciamento de tabelas, como compactação e expiração de snapshot.

12. Clique em Criar.

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

13. Se você selecionou Modo de fornecimento de credenciais, siga estas etapas adicionais:

    1. Em Método de autenticação, clique em Definir permissões de bucket (ou Definir permissões para buckets se o catálogo usar mais de um bucket).
    2. Na caixa de diálogo, clique em Confirmar.

Criar um catálogo de bucket único

Atenção: evite usar a configuração de bucket único para novos projetos. Essa configuração restringe o catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket.

1. Na página Lakehouse, clique em Criar catálogo e selecione Catálogo do ambiente de execução do Lakehouse.
2. Em Tipo de catálogo, selecione Catálogo REST do Iceberg ou Hive Metastore.
3. Se você selecionou Catálogo REST do Iceberg, em Opções de bucket do catálogo do Lakehouse, selecione Catálogo de bucket único.
4. Em Bucket padrão do Cloud Storage do catálogo (ou Caminho padrão do Cloud Storage do catálogo para um endpoint de catálogo do Apache Hive), insira ou procure o bucket do Cloud Storage que será usado com seu catálogo. Em um catálogo de bucket único, só é possível ter um catálogo por bucket, e o nome do catálogo corresponde ao nome do bucket.
5. Clique em Continuar.
6. Em Método de autenticação, selecione Credenciais de usuário final ou Modo de venda de credenciais.
7. Clique em Criar.
8. Se você selecionou Modo de fornecimento de credenciais, siga estas etapas adicionais:
   1. Em Método de autenticação, clique em Definir permissões do bucket.
   2. Na caixa de diálogo, clique em Confirmar.

gcloud

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

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

Para criar um catálogo de vários buckets (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 \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

Substitua:

• CATALOG_NAME: um nome para o catálogo. Para catálogos de vários buckets (recomendado), esse é o nome do catálogo personalizado.
• PROJECT_ID: o ID do projeto do Google Cloud.
• DEFAULT_LOCATION: 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 residir no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não será possível criar namespaces ou tabelas em gs://my-bucket/another/path.

• CREDENTIAL_MODE: o método de autenticação. Use end-user para credenciais de usuário final ou vended-credentials para o modo de venda de credenciais. Se você especificar end-user, o catálogo do ambiente de execução do Lakehouse não gerenciará automaticamente as tabelas no catálogo. Não é possível ativar tarefas de gerenciamento de tabelas, como compactação e expiração de snapshots.

  Observação: se você usar o modo de venda de credenciais, precisará conceder 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 do ambiente de execução do Lakehouse provisionada automaticamente do seu catálogo.

• RESTRICTED_LOCATIONS: opcional: uma lista separada por vírgulas de outros locais de armazenamento permitidos, 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 dentro desse bucket precisarão estar nesse caminho. Todos os locais do Cloud Storage 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 bucket na Europa. Para conferir uma lista de locais compatíveis, consulte Locais do Lakehouse.

  Aviso: evite configurar caminhos sobrepostos com outros catálogos para evitar 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 consulta nas multirregiões correspondentes do BigQuery. Para mais informações, consulte Regiões de bucket e catálogo.

Criar um catálogo de bucket único

Atenção: evite usar a configuração de bucket único para novos projetos. Essa configuração restringe o catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket.

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

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

Substitua:

• CATALOG_NAME: um nome para o catálogo. Para catálogos de bucket único, ele corresponde ao ID do bucket do Cloud Storage usado com o catálogo.
• PROJECT_ID: o ID do projeto do Google Cloud.
• CREDENTIAL_MODE: o método de autenticação. Use end-user para credenciais de usuário final ou vended-credentials para o modo de venda de credenciais.

REST

Criar um endpoint de catálogo REST do Apache Iceberg

Para criar um endpoint de gerenciamento de catálogo usando a API REST, faça uma solicitação POST ao endpoint CreateIcebergCatalog:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

O corpo da solicitação precisa conter um payload JSON IcebergCatalog que defina a configuração do catálogo, como o warehouse do bucket do Cloud Storage subjacente e o modo de autenticação.

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse.