Configuração de um volume externo para Amazon S3¶

Pré-requisitos¶

Antes de configurar um volume externo, você precisa do seguinte:

• Um bucket de armazenamento S3.

  • Para usar o volume externo para tabelas Iceberg gerenciadas externamente, todos os dados da tabela e arquivos de metadados devem estar localizados em um bucket que hospeda sua conta Snowflake.

  • O Snowflake não é compatível com volumes externos com nomes de bucket S3 que contenham pontos (por exemplo, my.s3.bucket). O S3 não oferece suporte a SSL para buckets do tipo de hospedam virtual com pontos no nome, e o Snowflake usa caminhos do tipo de hospedam virtual e HTTPS para acessar dados no S3.

  • Para oferecer suporte à recuperação de dados, ative o controle de versão para seu local de armazenamento em nuvem externo.

• Permissões no AWS para criar e gerenciar políticas e funções IAM. Se você não for um administrador AWS, peça ao seu administrador AWS para executar essas tarefas.

Etapa 1: Crie uma política de IAM que conceda acesso ao seu local S3¶

Para configurar permissões de acesso para Snowflake no AWS Management Console, faça o seguinte:

1. Faça login no AWS Management Console.

2. No painel inicial, pesquise e selecione IAM.

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

4. Em Security Token Service (STS), na lista Endpoints, encontre a região do Snowflake onde sua conta está localizada. Se o STS status estiver inativo, mude o seletor para Active.

5. Selecione Policies no painel de navegação à esquerda.

6. Selecione Create Policy.

   

7. Para Policy editor, selecione JSON.

8. Adicione uma política para fornecer ao Snowflake as permissões necessárias para ler e gravar dados em seu local S3.

   O exemplo de política a seguir concede acesso a todos os locais no bucket especificado.

   Nota

   • Substitua my_bucket com o nome real de seu bucket. Você também pode especificar um caminho no bucket; por exemplo, my_bucket/path.

   • Definir a condição "s3:prefix": para ["*"] concede acesso a todos os prefixos no bucket especificado; defini-lo como ["path/*"] concede acesso a um caminho especificado no bucket.

   • Para buckets em regiões governamentais, os ARNs de bucket usam o prefixo arn:aws-us-gov:s3:::.

   • Se você estiver usando um ponto de acesso S3, especifique o ARN do ponto de acesso em vez de um ARN do bucket. Para obter mais informações, consulte Configuração de políticas de IAM para usar pontos de acesso.

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

   Copy

9. Selecione Next.

10. Insira um Policy name (por exemplo, snowflake_access) e uma Description opcional.

11. Selecione Create policy.

Etapa 2: Crie uma função IAM¶

Crie uma função AWS IAM para conceder privilégios ao bucket S3 com seus arquivos de dados.

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

2. Selecione Create role.

3. Para o tipo de entidade de confiança, selecione AWS account.

4. Em An AWS account, selecione This account. Em uma etapa posterior, você modifica a relação de confiança e concede acesso ao Snowflake.

5. Selecione a opção Require external ID. Insira um ID externo de sua escolha. Por exemplo, iceberg_table_external_id.

   Um ID externo é usado para conceder acesso aos seus recursos AWS (como buckets S3) a terceiros, como o Snowflake.

   

6. Selecione Next.

7. Selecione a política que você criou para o volume externo e selecione Next.

8. Insira um Role name e uma descrição para a função e selecione Create role.

   Agora você criou uma política IAM para um local S3, criou uma função IAM e anexou a política à função.

9. Selecione View role para exibir a página de resumo da função. Localize e registre o valor do nome de recurso da Amazon (ARN) para a função.

   

Etapa 3: conceder privilégios necessários para criptografia SSE-KMS à função IAM (opcional)¶

Se você quiser carregar um objeto criptografado com uma chave AWS KMS para o Amazon S3, a função IAM que você criou para seu volume externo precisa de permissões kms:GenerateDataKey na chave. Para baixar um objeto criptografado com uma chave AWS KMS, a função IAM precisa de permissões kms:Decrypt na chave.

Se você quiser usar uma chave KMS para criptografia no lado do servidor, siga estas etapas para criar uma chave e referenciá-la.

1. No Console de Gerenciamento da AWS, acesse Key Management Service (KMS). Na navegação esquerda, selecione Customer managed keys e selecione Create key. Você deve criar uma chave na mesma região do seu bucket.

2. Crie um tipo de chave Symmetric. Para o uso da chave, selecione Encrypt and decrypt. Selecione Next.

3. Para Alias, insira um nome para a chave e selecione Next.

4. Se necessário, selecione um administrador para a chave e selecione Next.

5. Para Define key usage permissions, selecione sua função IAM e, em seguida, selecione Next.

6. Revise os detalhes da configuração de chave e selecione Finish para criar a chave.

7. Encontre a chave na lista de chaves gerenciadas pelo cliente, selecione-a e registre seu ARN. A seguir está um exemplo de ARN para uma chave: arn:aws:kms:us-west-2:111111122222:key/1a1a11aa-aa1a-aaa1a-a1a1-000000000000.

   Ao criar seu volume externo, defina o valor KMS_KEY_ID como ARN da sua chave.

Etapa 4: criar um volume externo no Snowflake¶

Crie um volume externo usando o comando CREATE EXTERNAL VOLUME. O exemplo a seguir cria um volume externo nomeado iceberg_external_volume, que define um local de armazenamento único do Amazon S3 com criptografia.

CREATE OR REPLACE EXTERNAL VOLUME iceberg_external_volume
   STORAGE_LOCATIONS =
      (
         (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://<my_bucket>/'
            STORAGE_AWS_ROLE_ARN = '<arn:aws:iam::123456789012:role/myrole>'
            STORAGE_AWS_EXTERNAL_ID = 'iceberg_table_external_id'
         )
      )
      ALLOW_WRITES = TRUE;

O exemplo especifica o ID externo (iceberg_table_external_id) associado à função IAM que você criou para o volume externo. Especificar um ID externo permite que você use a mesma função IAM (e ID externo) em vários volumes externos.

Etapa 5: recuperar o usuário AWS IAM para sua conta Snowflake¶

1. Recupere o ARN do usuário AWS IAM criado automaticamente para sua conta Snowflake, usando o comando DESCRIBE EXTERNAL VOLUME. Especifique o nome do seu volume externo.

   O exemplo a seguir descreve um volume externo nomeado iceberg_external_volume.

   DESC EXTERNAL VOLUME iceberg_external_volume;
   

   Copy

2. Registre o valor para a propriedade STORAGE_AWS_IAM_USER_ARN, que é o usuário AWS IAM criado para sua conta Snowflake; por exemplo, arn:aws:iam::123456789001:user/abc1-b-self1234.

   O Snowflake fornece um único usuário IAM para toda a sua conta Snowflake. Todos os volumes externos S3 da sua conta usam esse usuário IAM.

   Nota

   Se você não especificou um ID externo (STORAGE_AWS_EXTERNAL_ID) ao criar um volume externo, o Snowflake gerará um ID para você usar. Registre o valor para que você possa atualizar sua política de confiança da função IAM com o ID externo gerado.

Etapa 6: conceder ao usuário IAM permissões para acessar objetos de bucket¶

Nesta etapa, você configura permissões que permitem que o usuário IAM da sua conta Snowflake acesse objetos no seu bucket S3.

1. Faça login no AWS Management Console.

2. No painel inicial, pesquise e selecione IAM.

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

4. Selecione a função IAM que você criou para seu volume externo.

5. Selecione a guia Trust relationships.

6. Selecione Edit trust policy.

7. Modifique o documento de política com valores de saída DESC EXTERNAL VOLUME que você registrou.

   

   Documento de política da função IAM

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

   Copy

   Onde:

   • snowflake_user_arn é o valor STORAGE_AWS_IAM_USER_ARN que você registrou.

   • iceberg_table_external_id é seu ID externo. Se você já especificou um ID externo ao criar a função e usou o mesmo ID para criar seu volume externo, deixe o valor como está. Caso contrário, atualize sts:ExternalId com o valor que você registrou.

   Nota

   Você deverá atualizar este documento de política se criar um novo volume externo (ou recriar um volume externo existente usando a sintaxe CREATE OR REPLACE EXTERNAL VOLUME) e não fornecer seu próprio ID externo. Por motivos de segurança, um volume externo novo ou recriado tem um ID externo diferente e não pode resolver a relação de confiança, a menos que você atualize esta política de confiança.

8. Selecione Update policy para salvar suas alterações.

Etapa 7: verificar o acesso ao armazenamento¶

Para verificar se o Snowflake pode se autenticar com sucesso no seu provedor de armazenamento, chame a função SYSTEM$VERIFY_EXTERNAL_VOLUME.

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_external_volume');

Error assuming AWS_ROLE:
STS is not activated in this region for account:<external volume id>. Your account administrator can activate STS in this region using the IAM Console.

Próximos passos¶

Depois de configurar um volume externo, você poderá criar uma tabela Iceberg.

• Para criar uma tabela Iceberg somente leitura que usa um catálogo externo, consulte Configurar uma integração de catálogo.

• Para criar uma tabela Iceberg com suporte completo à plataforma Snowflake, consulte Criar uma tabela gerenciada pelo Snowflake.