Criar um catálogo

A criação de um endpoint de catálogo (como um endpoint de catálogo REST do Apache Iceberg ou do Apache Hive) estabelece um endpoint de gerenciamento no catálogo de ambientes de execução do Lakehouse.

Esse endpoint aponta para um bucket do Cloud Storage subjacente, fornecendo 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 o endpoint do catálogo para o Lakehouse para Apache Iceberg, você pode escolher entre credenciais do usuário final ou modo de venda de credenciais para delegação de acesso ao armazenamento.

Antes de começar

1. Leia Sobre o catálogo de ambientes de execução do Lakehouse para entender como ele funciona e as limitações do serviço.
Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 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
• Registrar tabelas: Administrador do BigLake (roles/biglake.admin) no seu projeto. Para registrar tabelas em um catálogo de vários buckets, é necessário ter a permissão específica de registro de tabela (biglake.tables.register), que está incluída na função 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 seus buckets de armazenamento à conta de serviço provisionada automaticamente.

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 do catálogo provisionada automaticamente tem consistência eventual. Isso significa que leva algum tempo para que a conta de serviço se propague 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 mudanças de acesso serem propagadas, consulte Propagação de mudança de acesso.

Criar um catálogo

Crie um catálogo.

Console

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

Observação: os catálogos de vários buckets (bl://), que são recomendados, não são compatíveis com o console do Google Cloud . Para atualizar esse tipo de catálogo, use gcloud ou a API REST.

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

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

   Acessar Lakehouse

2. Selecione Criar catálogo. A página Criar catálogo é aberta.

3. Selecione a configuração do catálogo:

   • Para criar um catálogo REST do Apache Iceberg, selecione Catálogo REST do Iceberg.

4. Configure o catálogo:

   • Se você escolher Catálogo REST do Iceberg, selecione Bucket do Cloud Storage para o tipo de catálogo e selecione o bucket do Cloud Storage a ser usado com seu catálogo.
   • Se você escolher Catálogo do Hive, insira um nome exclusivo e selecione o caminho associado do Cloud Storage.

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

   Se você selecionar o modo de venda de credenciais, a conta de serviço do catálogo de tempo de execução do Lakehouse provisionada automaticamente vai exigir o papel explícito 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 têm escopo suficiente para realizar gravações de armazenamento.

6. Selecione Criar.

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

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

8. Na caixa de diálogo, selecione Confirmar.

   Isso verifica se a conta de serviço do catálogo tem o papel Usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets de armazenamento associados. Se você criar catálogos usando gcloud ou Terraform, conceda essa função manualmente.

gcloud

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

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

Substitua:

• CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse.
• PROJECT_ID: o ID do projeto Google Cloud .
• DEFAULT_LOCATION: o caminho base do Cloud Storage para os dados e metadados do catálogo, no formato gs://my-bucket/path ou gs://my-bucket. Todos os namespaces e tabelas no catálogo precisam estar localizados nesse caminho. Por exemplo, se você especificar gs://my-bucket/path, não poderá hospedar namespaces ou tabelas em gs://my-bucket/another/path.
• RESTRICTED_LOCATIONS: (opcional) uma lista separada por vírgulas de outros buckets ou caminhos de armazenamento permitidos. Da mesma forma, se você especificar um caminho (como gs://my-bucket/path), todos os namespaces e tabelas criados no bucket desse caminho precisarão estar dentro dele. 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.
• CREDENTIAL_MODE: o método de autenticação. Use end-user para Credenciais do usuário final ou vended-credentials para Modo de venda de credenciais.
• PRIMARY_LOCATION: (opcional) a região principal do catálogo (como US ou EU) para garantir a compatibilidade com o BigQuery.

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

Observação: catálogo de bucket único. Não é recomendável usar a configuração de bucket único em novos projetos. Essa configuração restringe seu 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 (gs://), defina --catalog-type como gcs-bucket:

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

Substitua:

• CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse. Para catálogos de um único bucket (gs://), esse valor precisa corresponder ao nome do bucket do Cloud Storage.
• PROJECT_ID: o ID do projeto Google Cloud .
• CREDENTIAL_MODE: o método de autenticação. Use end-user para Credenciais do usuário final ou vended-credentials para Modo de venda de credenciais.

REST

Criar um catálogo REST do Iceberg

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

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

O corpo da solicitação precisa conter um payload JSON IcebergCatalog que defina a configuração do catálogo, como o bucket do Cloud Storage 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.