Configurando o armazenamento S3 para pg_lake¶

Pré-requisitos¶

Antes de configurar o armazenamento S3 para pg_lake, certifique-se de ter:

• Uma conta AWS ativa com permissões para criar e gerenciar `buckets S3<https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html>`_ e funções do IAM.

• Um bucket S3 na mesma região da AWS que sua conta Snowflake. Para determinar a região da sua conta Snowflake, execute a seguinte consulta no Snowflake (não na sua instância do Postgres):

  SELECT CURRENT_REGION();
  

  Copy

• Familiaridade com as funções e políticas do AWS IAM.

• Uma instância do Snowflake Postgres compatível com pg_lake.

• Privilégios para criar integrações de armazenamento no Snowflake (requer a função ACCOUNTADMIN ou uma função com o privilégio CREATE e INTEGRATION na conta).

Etapa 1: Criar um bucket S3¶

Se você ainda não tiver um, crie um bucket S3 na mesma região da AWS da sua conta Snowflake. Por exemplo, se a sua conta Snowflake estiver em us-west-2, crie o bucket S3 na região us-west-2.

Consulte a documentação da AWS para obter instruções sobre como criar um bucket S3.

Etapa 2: Criar uma política IAM para acesso ao S3¶

Crie uma política IAM que conceda as permissões necessárias para que a pg_lake leia e grave no seu bucket S3:

1. Faça login no console de gerenciamento da AWS e navegue até o serviço IAM.

2. Selecione Account settings no painel de navegação à esquerda.

3. Em Security Token Service (STS), na lista de pontos de extremidade, encontre a região do Snowflake em que sua conta está localizada. Se o status do STS estiver inativo, mova o botão para Active. Para obter mais informações, consulte Ativando e desativando o AWS STS em uma região AWS.

4. No painel de navegação à esquerda, selecione Policies e, em seguida, escolha Create policy.

5. Para Policy editor, selecione JSON.

6. Adicione um documento de política que permita que o Snowflake acesse o bucket S3 e a pasta. Substitua bucket_name e prefix pelo nome real do seu bucket e pelo prefixo do caminho da pasta:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:GetObjectVersion",
                   "s3:DeleteObject",
                   "s3:DeleteObjectVersion"
               ],
               "Resource": "arn:aws:s3:::bucket_name/prefix/*"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket",
                   "s3:GetBucketLocation"
               ],
               "Resource": "arn:aws:s3:::bucket_name",
               "Condition": {
                   "StringLike": {
                       "s3:prefix": [
                           "prefix/*"
                       ]
                   }
               }
           }
       ]
   }
   

   Copy

   Esta política fornece permissões para:

   • Ler, gravar e excluir objetos no caminho do S3 especificado

   • Listar o conteúdo do bucket e recuperar a localização do bucket

   • Compatibilidade com a capacidade da pg_lake de criar e gerenciar tabelas Iceberg

7. Escolha Next.

8. Insira um nome para a política (por exemplo, snowflake_pg_lake_access) e uma descrição opcional.

9. Escolha Create policy.

Etapa 3: Crie uma função IAM¶

Crie uma função IAM que o Snowflake assumirá para acessar seu bucket S3.

1. Na seção de navegação à esquerda do painel de gerenciamento de identidade e acesso (IAM), selecione Roles.

2. Selecione Create role.

3. Selecione AWS account como o tipo de entidade confiável.

4. Selecione Another AWS account.

5. No campo Account ID, digite temporariamente sua própria AWS de conta ID. Você modificará a relação de confiança em uma etapa posterior para conceder acesso ao Snowflake.

6. Selecione a opção Require external ID. Insira um ID externo de espaço reservado, como 0000. Você atualizará isso com o ID externo real gerado pelo Snowflake em uma etapa posterior.

   Nota

   Um ID externo é usado para conceder acesso aos seus recursos AWS (como buckets S3) a terceiros, como o Snowflake. Para obter mais informações, consulte Como usar um ID externo ao conceder acesso aos seus recursos do AWS a terceiros.

7. Selecione Next.

8. Pesquise e selecione a política que você criou na Etapa 2: Criar uma política IAM para acesso ao S3.

9. Selecione Next.

10. Insira um nome e uma descrição para a função (por exemplo, snowflake_pg_lake_role) e selecione Create role.

11. Na página de resumo da função, localize e registre o valor Role ARN. Você precisará disso ao criar a integração de armazenamento no Snowflake.

12. Na página de resumo da função, selecione Edit na seção de resumo e altere Maximum session duration para 12 hours. Selecione Save changes. Para obter mais informações, consulte Modificando a duração máxima da sessão de uma função (AWS).

Etapa 4: Criar uma integração de armazenamento no Snowflake¶

Crie um objeto de integração de armazenamento no Snowflake que faça referência à função IAM que você criou. Para obter a sintaxe completa do comando, consulte CREATE STORAGE INTEGRATION.

CREATE STORAGE INTEGRATION my_pg_lake_integration
  TYPE = POSTGRES_EXTERNAL_STORAGE
  STORAGE_PROVIDER = 'S3'
  ENABLED = TRUE
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/snowflake_pg_lake_role'
  STORAGE_ALLOWED_LOCATIONS = ('s3://my-bucket/my-prefix/');

Onde:

• my_pg_lake_integration é o nome que você escolheu para a integração de armazenamento.

• TYPE = POSTGRES_EXTERNAL_STORAGE especifica que essa integração é para uso com o Snowflake Postgres.

• STORAGE_AWS_ROLE_ARN é o ARN da função que você registrou na Etapa 3: Criar uma função IAM.

• STORAGE_ALLOWED_LOCATIONS especifica o bucket S3 e o prefixo do caminho. Substitua my-bucket e my-prefix pelo nome do bucket e pelo caminho da pasta que você criou na Etapa 1: Criar um bucket S3. Observe que apenas um local é permitido para integrações de armazenamento do Postgres.

Etapa 5: Recuperar o ARN do usuário do IAM Snowflake e o ID externo¶

Após criar a integração de armazenamento, use o comando DESCRIBE INTEGRATION para recuperar o usuário do AWS IAM e o ID externo que o Snowflake gerou para essa integração:

DESCRIBE STORAGE INTEGRATION my_pg_lake_integration;

Na saída, localize e registre os seguintes valores:

• STORAGE_AWS_IAM_USER_ARN: o ARN do usuário do IAM que o Snowflake usará para assumir a função

• STORAGE_AWS_EXTERNAL_ID: o ID externo a ser utilizado na política de confiança

Você usará esses valores na próxima etapa para configurar a política de confiança da função IAM.

Etapa 6: Atualizar a política de confiança da função IAM¶

Atualize a política de confiança da função IAM que você criou na Etapa 3: Criar uma função IAM para permitir que o Snowflake assuma a função:

1. Faça login no console de gerenciamento da AWS e navegue até o serviço IAM.

2. Selecione Roles no painel de navegação à esquerda.

3. Selecione a função que você criou na Etapa 3: Criar uma função IAM.

4. Selecione a guia Trust relationships.

5. Selecione Edit trust policy.

6. Substitua o documento de política pelo seguinte texto:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "AWS": "<storage_aws_iam_user_arn>"
               },
               "Action": "sts:AssumeRole",
               "Condition": {
                   "StringEquals": {
                       "sts:ExternalId": "<storage_aws_external_id>"
                   }
               }
           }
       ]
   }
   

   Copy

   Substitua os valores de espaço reservado pelos valores que você registrou na Etapa 5: Recuperar o ARN do usuário do Snowflake IAM e o ID externo:

   • Substitua storage_aws_iam_user_arn pelo valor STORAGE_AWS_IAM_USER_ARN. Este é um ARN completo no formato arn:aws:iam::<account_id>:user/snowflake-postgres-integration-management, em que o nome de usuário é sempre o mesmo e apenas o ID da conta AWS varia.

   • Substitua storage_aws_external_id pelo valor STORAGE_AWS_EXTERNAL_ID.

7. Selecione Update policy para salvar as alterações.

Etapa 7: Anexar a integração de armazenamento à sua instância do Postgres¶

Anexe a integração de armazenamento à sua instância do Snowflake Postgres. Quando a integração de armazenamento é anexada, as credenciais do S3 são sincronizadas automaticamente com o plano de controle do Postgres e disponibilizadas para a pg_lake:

ALTER POSTGRES INSTANCE my_postgres_instance
  SET STORAGE_INTEGRATION = my_pg_lake_integration;

Você também pode especificar a integração de armazenamento ao criar uma nova instância do Postgres:

CREATE POSTGRES INSTANCE my_postgres_instance
  ...
  STORAGE_INTEGRATION = my_pg_lake_integration;

Para remover uma integração de armazenamento de uma instância do Postgres:

ALTER POSTGRES INSTANCE my_postgres_instance
  UNSET STORAGE_INTEGRATION;

Etapa 8: Configurar e usar a pg_lake¶

Após anexar a integração de armazenamento, conecte-se à sua instância do Postgres e configure a pg_lake. Para obter uma lista das extensões disponíveis, consulte Extensões do Snowflake Postgres.

1. Crie a extensão pg_lake:

   CREATE EXTENSION pg_lake CASCADE;
   

   Copy

2. Defina o local de armazenamento padrão para tabelas Iceberg. Isso deve corresponder ao local especificado na sua integração de armazenamento.

   O comando SET aplica-se apenas à sessão atual:

   SET pg_lake_iceberg.default_location_prefix = 's3://my-bucket/my-prefix';
   

   Copy

   Para definir o valor de todas as sessões atuais e futuras, use o comando ALTER DATABASE. Se você usa vários bancos de dados Postgres, certifique-se de definir o local de armazenamento para cada um deles:

   -- Substitute the name of your database
   ALTER DATABASE my_database SET pg_lake_iceberg.default_location_prefix = 's3://my-bucket/my-prefix';
   

   Copy

3. Verifique se a integração de armazenamento está configurada corretamente listando o conteúdo do seu bucket S3:

   SELECT * FROM lake_file.list('s3://my-bucket/my-prefix/*');
   

   Copy

   Substitua my-bucket e my-prefix pelo nome e caminho reais do seu bucket. Se a configuração estiver correta, a consulta retornará uma lista de arquivos nesse local. Se o bucket estiver vazio, a consulta retornará um conjunto de resultados vazio sem erros.

4. Verifique a configuração de ponta a ponta criando uma tabela Iceberg, inserindo dados e consultando-a novamente. Se isso for bem-sucedido, a pg_lake poderá ler e gravar no seu bucket S3:

   CREATE TABLE my_table (
       id INT,
       data TEXT
     ) USING iceberg;
   
   INSERT INTO my_table VALUES (1, 'hello iceberg');
   
   SELECT * FROM my_table;
   

   Copy

Considerações de segurança¶

Ao configurar o acesso ao S3 para a pg_lake, tenha em mente estas práticas recomendadas de segurança:

• Usar funções IAM: o Snowflake Postgres usa a assunção de funções IAM em vez de credenciais estáticas, proporcionando maior segurança por meio de credenciais temporárias e rotação automática de credenciais.

• Limitar permissões do IAM: conceda apenas as permissões mínimas necessárias aos caminhos do bucket S3 que a pg_lake precisa acessar. A política IAM deve restringir o acesso a prefixos de bucket específicos.

• Monitorar o ID externo: o ID externo na política de confiança garante que somente sua conta Snowflake possa assumir a função IAM.

• Revisar alterações na integração de armazenamento: quaisquer atualizações em STORAGE_AWS_ROLE_ARN ou STORAGE_ALLOWED_LOCATIONS da integração de armazenamento são sincronizadas automaticamente com a instância do Postgres.

• Usar políticas de bucket: considere usar políticas de bucket S3 além das políticas IAM para garantir defesa em profundidade.

• Habilitar o registro de acesso ao S3: habilite o registro de acesso no seu bucket S3 para monitorar e auditar os padrões de acesso.

• Alinhamento regional: certifique-se de que seu bucket S3 esteja na mesma região da AWS que sua conta Snowflake para obter o melhor desempenho e atender aos requisitos de residência de dados.

Solução de problemas¶

Informações relacionadas¶

• Option 1: Configure a Snowflake storage integration to access Amazon S3 – fluxo de trabalho de acesso ao S3 semelhante ao descrito neste tópico

• Tabelas Apache Iceberg™ – visão geral do suporte a tabelas Iceberg no Snowflake

• Criar uma tabela Apache Iceberg™ no Snowflake – criação de tabelas Iceberg a partir de diferentes fontes de catálogo

• Configuração de um volume externo – configuração de um volume externo para tabelas Iceberg

• Configurar uma integração de catálogo para arquivos no armazenamento de objetos – configuração de integração de catálogo para arquivos no armazenamento de objetos

• Documentação da extensão pg_lake