Gerenciar ACLs de endpoint do catálogo REST do Apache Iceberg

O Lakehouse sem fronteiras oferece suporte ao controle de acesso no nível do catálogo, do namespace e da tabela para tabelas do Apache Iceberg no Cloud Storage que usam o catálogo do ambiente de execução do Lakehouse.

O catálogo do ambiente de execução do Lakehouse gerencia os metadados, enquanto as políticas do Identity and Access Management (IAM) definem as permissões. Use o console doGoogle Cloud ou a CLI gcloud para receber e definir essas políticas do IAM.

Antes de começar

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

2. Ative a API BigLake, se ainda não tiver feito isso.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

3. Instale e inicialize a Google Cloud CLI.
4. Verifique se você tem um endpoint e um namespace do catálogo REST do Apache Iceberg.
5. Verifique se você tem uma tabela do Apache Iceberg gerenciada pelo Lakehouse no catálogo e no namespace especificados.

Funções exigidas

Para receber as permissões necessárias para gerenciar listas de controle de acesso (ACLs) para catálogos, namespaces e tabelas do Iceberg, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Todos: Administrador do BigLake (roles/biglake.admin) no projeto

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.

Como funciona

As políticas do IAM definem quais principais têm papéis e permissões específicos para um recurso. Para gerenciar o acesso aos recursos, receba e defina essas políticas.

Escopo dos papéis do IAM

É possível conceder papéis do IAM em diferentes níveis da hierarquia de recursos:

• Nível do projeto: concede acesso a todos os recursos do Lakehouse no projeto.
• Nível do catálogo: concede acesso aos recursos que pertencem ao catálogo especificado.
• Nível de namespace: concede acesso aos recursos que pertencem ao namespace especificado.
• Nível da tabela: concede acesso apenas à tabela especificada.

Papéis relevantes do IAM

A lista a seguir mostra alguns dos papéis comuns do IAM que podem ser aplicados aos recursos do Lakehouse. Para uma lista completa dos papéis disponíveis e as permissões associadas, consulte Papéis do IAM do Lakehouse.

• roles/biglake.admin: fornece acesso total a todos os recursos do Lakehouse.
• roles/biglake.editor: fornece acesso de leitura e gravação a todos os recursos do Lakehouse.
• roles/biglake.viewer: fornece acesso somente leitura a todos os recursos do Lakehouse.
• roles/biglake.metadataViewer: fornece acesso somente leitura aos metadados de todos os recursos do Lakehouse.

Práticas recomendadas

• Privilégio mínimo: conceda apenas as permissões necessárias aos usuários e às contas de serviço.
• Use Etags: sempre inclua o etag de uma chamada get-iam-policy recente no arquivo de política ao usar set-iam-policy para evitar substituições não intencionais.
• Geração de registros de auditoria: verifique se os Registros de Auditoria do Cloud estão ativados para rastrear mudanças nas políticas do IAM.
• Controle de versões: armazene os arquivos de política em um sistema de controle de versões.

Aplicar papéis de ACL a catálogos

A seção a seguir mostra como aplicar ACLs a catálogos.

gcloud

Receber a política do IAM

Para visualizar a política atual do IAM em um catálogo do Iceberg do Lakehouse, use o comando gcloud biglake iceberg catalogs get-iam-policy.

1. Para receber a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg catalogs get-iam-policy CATALOG_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • PROJECT_ID: o ID do projeto do Google Cloud.

2. A resposta ao comando gera a política do IAM no formato YAML, que mostra as vinculações de papéis e os membros atuais.

Definir a política do IAM

Para atualizar a política do IAM em um catálogo do Lakehouse Iceberg, use o comando gcloud biglake iceberg catalogs set-iam-policy. Esse comando usa um arquivo JSON ou YAML local que contém a política que você quer aplicar.

1. Crie um arquivo de política local no formato JSON ou YAML. O arquivo de política precisa conter as vinculações e um etag. O valor etag fornece controle de simultaneidade otimista para evitar a substituição de alterações. Para ver o etag atual, execute o comando get-iam-policy primeiro.

   O exemplo a seguir mostra um arquivo de política chamado policy.json:

   {
     "bindings": [
       {
         "role": "roles/biglake.viewer",
         "members": [
           "user:[e-mail]"
         ]
       },
       {
         "role": "roles/biglake.editor",
         "members": [
           "user:[e-mail]"
         ]
       }
     ],
     "etag": "BwYXa9UuR8w=",
     "version": 3
   }
   

2. Para definir a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg catalogs set-iam-policy CATALOG_NAME POLICY_FILE \
       --project=PROJECT_ID
   

   Substitua:

   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • POLICY_FILE: o caminho para o arquivo de política local.
   • PROJECT_ID: o ID do projeto do Google Cloud .

Aplicar papéis de ACL a namespaces

A seção a seguir mostra como aplicar ACLs a namespaces.

O console do Google Cloud não exibe nem gerencia políticas herdadas do IAM.

Console

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

   Acessar o Lakehouse

2. Selecione um catálogo ou crie um, se ainda não tiver.

3. Na tabela Detalhes do namespace, selecione um namespace e expanda as opções do menu ().

4. Clique em Gerenciar permissões.

   A caixa de diálogo Permissões de compartilhamento vai aparecer.

5. Clique em Adicionar principal.

6. No campo Novos principais, insira a conta principal a que você quer atribuir papéis.

7. Em Selecionar um papel, escolha um papel para atribuir à conta principal.

8. Clique em Salvar.

9. Clique em Fechar.

gcloud

Receber a política do IAM

Para conferir a política do IAM atual em um namespace do Iceberg do Lakehouse, use o comando gcloud biglake iceberg namespaces get-iam-policy.

1. Para receber a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg namespaces get-iam-policy NAMESPACE_NAME \
       --catalog=CATALOG_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • NAMESPACE_NAME: o nome do namespace de destino no catálogo.
   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • PROJECT_ID: o ID do projeto do Google Cloud.

2. A resposta ao comando gera a política do IAM no formato YAML, que mostra as vinculações de papéis e os membros atuais.

Definir a política do IAM

Para atualizar a política do IAM em um namespace do Lakehouse Iceberg, use o comando gcloud biglake iceberg namespaces set-iam-policy. Esse comando usa um arquivo JSON ou YAML local que contém a política que você quer aplicar.

1. Crie um arquivo de política local no formato JSON ou YAML. O arquivo de política precisa conter as vinculações e um etag. O valor etag fornece controle de simultaneidade otimista para evitar a substituição de alterações. Para ver o etag atual, execute o comando get-iam-policy primeiro.

   O exemplo a seguir mostra um arquivo de política chamado policy.json:

   {
     "bindings": [
       {
         "role": "roles/biglake.viewer",
         "members": [
           "user:[e-mail]"
         ]
       },
       {
         "role": "roles/biglake.editor",
         "members": [
           "user:[e-mail]"
         ]
       }
     ],
     "etag": "BwYXa9UuR8w=",
     "version": 3
   }
   

2. Para definir a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg namespaces set-iam-policy NAMESPACE_NAME POLICY_FILE \
       --catalog=CATALOG_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • NAMESPACE_NAME: o nome do namespace de destino no catálogo.
   • POLICY_FILE: o caminho para o arquivo de política local.
   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • PROJECT_ID: o ID do projeto do Google Cloud .

Aplicar papéis de ACL a tabelas

A seção a seguir mostra como aplicar ACLs a tabelas.

O console do Google Cloud não exibe nem gerencia políticas herdadas do IAM.

Console

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

   Acessar o Lakehouse

2. Selecione um catálogo ou crie um, se ainda não tiver.

3. Na tabela Detalhes do namespace, clique no nome do namespace que contém sua tabela.

4. Na página Detalhes da tabela, selecione uma tabela e expanda as opções do menu ().

5. Clique em Gerenciar permissões.

   A caixa de diálogo Permissões de compartilhamento vai aparecer.

6. Clique em Adicionar principal.

7. No campo Novos principais, insira a conta principal a que você quer atribuir papéis.

8. Em Selecionar um papel, escolha um papel para atribuir à conta principal.

9. Clique em Salvar.

10. Clique em Fechar.

gcloud

Receber a política do IAM

Para visualizar a política do IAM atual em uma tabela do Iceberg do Lakehouse, use o comando gcloud biglake iceberg tables get-iam-policy.

1. Para receber a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg tables get-iam-policy TABLE_NAME \
       --catalog=CATALOG_NAME \
       --namespace=NAMESPACE_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • TABLE_NAME: o nome da tabela de destino do Apache Iceberg.
   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • NAMESPACE_NAME: o nome do namespace no catálogo.
   • PROJECT_ID: o ID do projeto do Google Cloud.

2. A resposta ao comando gera a política do IAM no formato YAML, que mostra as vinculações de papéis e os membros atuais.

Definir a política do IAM

Para atualizar a política do IAM em uma tabela do Apache Iceberg gerenciada pelo Lakehouse, use o comando gcloud biglake iceberg tables set-iam-policy. Esse comando usa um arquivo JSON ou YAML local que contém a política que você quer aplicar.

1. Crie um arquivo de política local no formato JSON ou YAML. O arquivo de política precisa conter as vinculações e um etag. O valor etag fornece controle de simultaneidade otimista para evitar a substituição de alterações. Para ver o etag atual, execute o comando get-iam-policy primeiro.

   O exemplo a seguir mostra um arquivo de política chamado policy.json:

   {
     "bindings": [
       {
         "role": "roles/biglake.viewer",
         "members": [
           "user:[e-mail]"
         ]
       },
       {
         "role": "roles/biglake.editor",
         "members": [
           "user:[e-mail]"
         ]
       }
     ],
     "etag": "BwYXa9UuR8w=",
     "version": 3
   }
   

2. Para definir a política do IAM, execute o seguinte comando:

   gcloud biglake iceberg tables set-iam-policy TABLE_NAME POLICY_FILE \
       --catalog=CATALOG_NAME \
       --namespace=NAMESPACE_NAME \
       --project=PROJECT_ID
   

   Substitua:

   • TABLE_NAME: o nome da tabela de destino do Apache Iceberg.
   • POLICY_FILE: o caminho para o arquivo de política local.
   • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
   • NAMESPACE_NAME: o nome do namespace no catálogo.
   • PROJECT_ID: o ID do projeto do Google Cloud .

A seguir

• Aprenda mais sobre o IAM.
• Confira a lista completa de papéis e permissões do IAM do Lakehouse.
• Saiba mais sobre os conceitos do Lakehouse.