Criar um catálogo

A criação de um endpoint de catálogo (como um endpoint de catálogo REST do Apache Iceberg ou um endpoint de catálogo 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 de catálogo do Lakehouse para Apache Iceberg, você pode escolher entre credenciais de 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 Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos 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 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

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 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 ter as permissões necessárias para criar um catálogo e registrar tabelas, peça ao administrador que conceda a você as seguintes funções do IAM:

• Criar um catálogo:
  • Administrador do BigLake (roles/biglake.admin) no seu projeto
  • Administrador do Storage (roles/storage.admin) no seu projeto
• Criar (registrar) tabelas: Administrador do BigLake (roles/biglake.admin) no seu projeto. O registro de tabelas em um catálogo de vários buckets exige a permissão específica de registro de tabelas (biglake.tables.register), que está incluída na função de administrador do BigLake.
• Usar a conta de serviço do catálogo provisionada automaticamente no modo de venda de credenciais: Usuário do objeto de armazenamento (roles/storage.objectUser) nos buckets de destino do Cloud Storage. Depois de criar o catálogo, conceda explicitamente a função de usuário do objeto de armazenamento (roles/storage.objectUser) nos 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 com papéis personalizados ou outros papéis predefinidos.

Observação: a criação da conta de serviço do catálogo provisionada automaticamente é eventualmente consistente. Isso significa que leva algum 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 propagadas, consulte Propagação de mudança de acesso.

Criar um catálogo

Crie um catálogo.

Criar um catálogo

Siga estas etapas para criar um catálogo com base no modo de credencial e no tipo de bucket preferidos. Para mais informações sobre os diferentes tipos de catálogo, consulte Sobre o endpoint de catálogo REST do Apache Iceberg.

Console

Criar um catálogo de vários buckets (bl://) (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 Google Cloud console.

   Acessar o Lakehouse

2. Clique em Criar catálogo.

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 a 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 , adicione outros caminhos do Cloud Storage, se necessário.

10. Clique em Continuar.

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

12. Clique em Criar.

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

13. Se você selecionou Modo de venda 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.

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

Atenção:o uso da configuração de bucket único não é recomendado 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. Em Tipo de catálogo, selecione Catálogo REST do Iceberg ou Hive Metastore.
2. Em Opções de bucket do catálogo do Lakehouse, selecione Catálogo de bucket único.
3. Em Caminho padrão do Cloud Storage do catálogo, insira ou procure o caminho do Cloud Storage a ser usado com o 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 corresponde ao nome do bucket.
4. Clique em Continuar.
5. Em Método de autenticação, selecione Credenciais de usuário final ou Modo de venda de credenciais.
6. Clique em Criar.
7. Se você selecionou Modo de venda 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 (bl://) (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 (bl://) (recomendado), execute o gcloud biglake iceberg catalogs create comando.

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 (bl://) (recomendado), esse é o nome personalizado do catálogo.
• PROJECT_ID: o ID do seu Google Cloud projeto.
• 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 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 Modo de venda de credenciais.

  Observação: se você usar o Modo de venda de credenciais, conceda explicitamente a função Usuário do objeto de armazenamento (roles/storage.objectUser) em todos os buckets de armazenamento associados à conta de serviço do catálogo de ambientes de execução do Lakehouse provisionada automaticamente.

• RESTRICTED_LOCATIONS: (opcional) 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 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 bucket na Europa. Para conferir uma lista de locais aceitos, 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 (gs://)

Atenção:o uso da configuração de bucket único não é recomendado 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 (gs://), execute o comando a seguir:

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 (gs://), ele corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST.
• PROJECT_ID: o ID do seu Google Cloud projeto.
• CREDENTIAL_MODE: o método de autenticação. Use end-user para Credenciais de 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 POST solicitação para o CreateIcebergCatalog endpoint:

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

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

Substitua:

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