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

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.

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: criar um volume externo na Snowsight¶

Para criar um volume externo no Snowflake usando a Snowsight, siga estes passos:

1. Faça login no Snowsight.

2. No canto inferior esquerdo, selecione seu nome » Switch role e, em seguida, selecione ACCOUNTADMIN ou uma função que tenha o privilégio CREATE EXTERNAL VOLUME.

   Para obter mais informações, consulte Mudar sua função primária.

3. No menu de navegação, selecione Catalog » External data.

4. Selecione a guia External volumes.

5. Selecione + Create.

6. Selecione AWS S3 e depois selecione Next.

   Nota

   Você já configurou seu provedor de nuvem antes quando criou uma política de IAM que concede acesso ao seu local do S3 e criou uma função do IAM.

7. Na página Grant storage access, copie a política de confiança do campo Trust policy para um editor de texto.

   Na próxima etapa, você colará essa política de confiança na AWS.

8. Para conceder acesso ao armazenamento, siga estas etapas:

   1. Na AWS, faça login no Console de Gerenciamento da AWS.

   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. Substitua a política de confiança para sua função de IAM com a política que você copiou na Snowsight.

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

   9. No Snowsight, selecione Next.

9. No Snowsight, selecione Next.

10. Para configurar seu volume externo, na página Configure external volume, preencha os campos:

    Campo	Descrição
    External volume name	Insira um nome para o seu volume externo.
    Region type	Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados. Standard (default): armazenamento S3 em regiões públicas da AWS fora da China. Government (GovCloud): armazenamento S3 em regiões governamentais da AWS.
    S3 role ARN	Especifica o Amazon Resource Name (ARN) que diferencia maiúsculas e minúsculas da função AWS de gerenciamento de identidade e acesso (IAM) que concede privilégios no bucket S3 que contém seus arquivos de dados. Você registrou esse valor quando criou uma função de IAM.
    Encryption (optional)	Especifica o tipo de criptografia utilizado. Os valores possíveis são: None (default): sem criptografia. SSE-S3: criptografia no lado do servidor usando chaves de criptografia gerenciadas por S3. Para obter mais informações, consulte `Como usar a criptografia no lado do servidor com chaves de criptografia gerenciadas pelo Amazon S3 (SSE-S3)<https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html>`_. SSE-KMS (enter key): criptografia do lado do servidor usando chaves armazenadas em KMS. Para obter mais informações, consulte Como usar criptografia no lado do servidor com o serviço de gerenciamento de chaves AWS (SSE-KMS).
    Scope	Escolha onde este volume externo deve se tornar o local padrão para futuras tabelas Iceberg. Os valores possíveis são: Do not set a default: não defina o volume externo como padrão em nenhum lugar. Account: defina o volume externo como padrão para tabelas Iceberg criadas no âmbito da conta. Specific database: defina o volume externo como padrão para tabelas Iceberg criadas no banco de dados que você especificar. Para especificar esse banco de dados, use o menu suspenso Database que aparece quando você seleciona Specific database. Specific schema: defina o volume externo como padrão para tabelas Iceberg criadas no esquema que você especificar. Para especificar esse esquema, use o menu suspenso Database que aparece para selecionar primeiro o banco de dados pai do esquema e, em seguida, o esquema.
    Comment (optional)	Especifica um comentário para o volume externo.
    Connectivity	Especifica se a conectividade privada de saída deve ser usada para reforçar sua postura de segurança. Para obter informações sobre como usar esse parâmetro, consulte Conectividade privada com volumes externos para Amazon Web Services. Os valores possíveis são: Public (default): usar a internet pública. Private (AWS PrivateLink): usar a conectividade privada de saída.
    Storage base URL	Especifica o URL base para seu local de armazenamento em nuvem.
    Access scope	Especifica se as operações de gravação são permitidas para o volume externo. Deve ser definido como Allow writes para as seguintes tabelas: Tabelas Iceberg que usam o Snowflake como catálogo. Tabelas Iceberg que usam um catálogo externo e são graváveis. As tabelas Iceberg gerenciadas externamente são graváveis quando você as acessa por meio de um banco de dados vinculado a catálogo que tem o parâmetro ALLOWED_WRITE_OPERATIONS definido como TRUE. Para tabelas Iceberg criadas de arquivos de tabela Delta, definir esse parâmetro como Allow writes permite que o Snowflake grave metadados Iceberg em seu armazenamento externo. Para obter mais informações, consulte Tabelas baseadas em Delta. O valor deste campo também deve corresponder às permissões definidas na conta de armazenamento em nuvem para cada local de armazenamento especificado. Nota Se você planeja usar o volume externo para ler tabelas Iceberg gerenciadas externamente, pode definir este campo como Desativado. O Snowflake não grava dados ou arquivos de metadados do Iceberg no seu armazenamento em nuvem quando você lê tabelas em um catálogo Iceberg externo.

11. Selecione Next.

    Na página Verify connection & create volume, o Snowflake verifica sua conexão com o AWS e depois exibe uma mensagem informando que a conexão foi bem-sucedida.

    Nota

    Se o Snowflake não puder verificar a conexão, confira sua permissão ou a configuração de volume externo e selecione Verify again.

12. Selecione Create.