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 de ambiente de execução do Lakehouse.

O catálogo de tempo 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.

   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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

3. Instale e inicialize o SDK Google Cloud.
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 namespace especificados.

Funções exigidas

Para receber as permissões necessárias para gerenciar listas de controle de acesso (ACLs) em 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) ativado para o 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. É possível gerenciar o acesso aos seus recursos recebendo e definindo 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 a recursos pertencentes ao catálogo especificado.
• Nível de namespace: concede acesso a recursos pertencentes 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 de 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 a usuários e 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 indesejadas.
• Registro 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 seus arquivos de política em um sistema de controle de versões.

Aplicar funções 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 conferir a política do IAM atual em um catálogo do Lakehouse Iceberg, use o comando gcloud alpha biglake iceberg catalogs get-iam-policy.

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

   gcloud alpha 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. O 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 alpha 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 oferece controle de simultaneidade otimista para evitar a substituição de mudanças. Para receber o etag atual, execute primeiro o comando get-iam-policy.

   Confira abaixo um exemplo de 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 alpha 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 funções de ACL a namespaces

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

O console Google Cloud não mostra 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 você não tiver.

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

4. Clique em Gerenciar permissões.

   A caixa de diálogo Permissões de compartilhamento aparece.

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 uma função 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 alpha biglake iceberg namespaces get-iam-policy.

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

   gcloud alpha 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. O 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 alpha 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 oferece controle de simultaneidade otimista para evitar a substituição de mudanças. Para receber o etag atual, execute primeiro o comando get-iam-policy.

   Confira abaixo um exemplo de 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 alpha 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 às tabelas

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

O console Google Cloud não mostra 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 você 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 de menu ().

5. Clique em Gerenciar permissões.

   A caixa de diálogo Permissões de compartilhamento aparece.

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 uma função para atribuir à conta principal.

9. Clique em Salvar.

10. Clique em Fechar.

gcloud

Receber a política do IAM

Para conferir 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. O 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 oferece controle de simultaneidade otimista para evitar a substituição de mudanças. Para receber o etag atual, execute primeiro o comando get-iam-policy.

   Confira abaixo um exemplo de 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 de Lakehouse.