Configuração de uma integração para o Google Cloud Storage

Este tópico descreve como configurar o acesso seguro a arquivos de dados armazenados em um bucket Google Cloud Storage.

Neste tópico:

Configuração de uma integração de armazenamento do Snowflake

Esta seção descreve como usar as integrações de armazenamento para permitir que o Snowflake leia e grave dados em um bucket Google Cloud Storage referenciado em um estágio externo (ou seja, o armazenamento em nuvem). As integrações são objetos Snowflake nomeados e de primeira classe que evitam a necessidade de passar credenciais explícitas de provedores de nuvens, tais como chaves secretas ou tokens de acesso; em vez disso, os objetos de integração fazem referência a uma conta do serviço de armazenamento em nuvem. Um administrador em sua organização concede as permissões da conta de serviço na conta de armazenamento em nuvem.

Os administradores também podem restringir os usuários a um conjunto específico de buckets de armazenamento em nuvem (e caminhos opcionais) acessados por estágios externos que utilizam a integração.

Nota

Completar as instruções nesta seção requer acesso ao seu projeto de armazenamento em nuvem como um editor de projeto. Se você não for um editor de projeto, peça a seu administrador do armazenamento em nuvem para realizar estas tarefas.

O diagrama a seguir mostra o fluxo de integração para um estágio do armazenamento em nuvem:

Fluxo de integração do estágio do Google Cloud Storage
  1. Um estágio externo (ou seja, o armazenamento em nuvem) faz referência a um objeto de integração de armazenamento em sua definição.

  2. O Snowflake associa automaticamente a integração do armazenamento com uma conta de serviço de armazenamento em nuvem criada para sua conta. O Snowflake cria uma única conta de serviço que é referenciada por todas as integrações de armazenamento GCS em sua conta Snowflake.

  3. Um editor de projeto para seu projeto de armazenamento em nuvem concede permissões à conta de serviço para acessar o bucket referenciado na definição do estágio. Observe que muitos objetos de preparação externos podem fazer referência a diferentes buckets e caminhos e usar a mesma integração para autenticação.

Quando um usuário carrega ou descarrega dados de ou para um estágio, o Snowflake verifica as permissões concedidas à conta de serviço no bucket antes de permitir ou negar o acesso.

Nesta seção:

Etapa 1: Criar uma integração de armazenamento em nuvem no Snowflake

Crie uma integração usando o comando CREATE STORAGE INTEGRATION. Uma integração é um objeto Snowflake que delega a responsabilidade pela autenticação do armazenamento externo em nuvem a uma entidade gerada pelo Snowflake (ou seja, uma conta de serviço de armazenamento em nuvem). Para acessar os buckets de armazenamento em nuvem, o Snowflake cria uma conta de serviço que pode receber permissões para acessar os buckets que armazenam seus arquivos de dados.

Uma única integração de armazenamento pode oferecer suporte a vários estágios externos (ou seja, GCS). A URL na definição do estágio deve estar alinhada com os buckets GCS (e caminhos opcionais) especificados para o parâmetro STORAGE_ALLOWED_LOCATIONS.

Nota

Somente administradores de conta (usuários com a função ACCOUNTADMIN) ou uma função com o privilégio global CREATE INTEGRATION podem executar este comando SQL.

CREATE STORAGE INTEGRATION <integration_name>
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('gcs://<bucket>/<path>/', 'gcs://<bucket>/<path>/')
  [ STORAGE_BLOCKED_LOCATIONS = ('gcs://<bucket>/<path>/', 'gcs://<bucket>/<path>/') ]
Copy

Onde:

  • integration_name é o nome da nova integração.

  • bucket é o nome de um bucket de armazenamento em nuvem que armazena seus arquivos de dados (por exemplo, mybucket). O parâmetro STORAGE_ALLOWED_LOCATIONS obrigatório e o parâmetro STORAGE_BLOCKED_LOCATIONS opcional restringem ou bloqueiam o acesso a estes buckets, respectivamente, quando os estágios que fazem referência a esta integração são criados ou modificados.

  • path é um caminho opcional que pode ser usado para proporcionar um controle granular sobre objetos no bucket.

O exemplo a seguir cria uma integração que limita explicitamente os estágios externos que utilizam a integração para referenciar um de dois buckets ou caminhos. Em uma etapa posterior, criaremos um estágio externo que referencia um desses buckets e caminhos.

Os estágios externos adicionais que também utilizam esta integração podem fazer referência aos buckets e caminhos permitidos:

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('gcs://mybucket1/path1/', 'gcs://mybucket2/path2/')
  STORAGE_BLOCKED_LOCATIONS = ('gcs://mybucket1/path1/sensitivedata/', 'gcs://mybucket2/path2/sensitivedata/');
Copy

Etapa 2: Recuperar a conta de serviço de armazenamento em nuvem para sua conta Snowflake

Execute o comando DESCRIBE INTEGRATION para recuperar a ID para a conta de serviço de armazenamento em nuvem que foi criada automaticamente para sua conta Snowflake:

DESC STORAGE INTEGRATION <integration_name>;
Copy

Onde:

Por exemplo:

DESC STORAGE INTEGRATION gcs_int;

+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
| property                    | property_type | property_value                                                              | property_default |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------|
| ENABLED                     | Boolean       | true                                                                        | false            |
| STORAGE_ALLOWED_LOCATIONS   | List          | gcs://mybucket1/path1/,gcs://mybucket2/path2/                               | []               |
| STORAGE_BLOCKED_LOCATIONS   | List          | gcs://mybucket1/path1/sensitivedata/,gcs://mybucket2/path2/sensitivedata/   | []               |
| STORAGE_GCP_SERVICE_ACCOUNT | String        | service-account-id@project1-123456.iam.gserviceaccount.com                  |                  |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
Copy

A propriedade STORAGE_GCP_SERVICE_ACCOUNT na saída mostra a conta do serviço de armazenamento em nuvem criada para sua conta Snowflake (por exemplo, service-account-id@project1-123456.iam.gserviceaccount.com). Fornecemos uma única conta de serviço de armazenamento em nuvem para toda a sua conta Snowflake. Todas as integrações de armazenamento em nuvem utilizam essa conta de serviço.

Etapa 3: Conceder as permissões da conta de serviço para acessar os objetos do bucket

As seguintes instruções passo a passo descrevem como configurar as permissões de acesso IAM ao Snowflake em seu Console Google Cloud Platform para que você possa usar um bucket de armazenamento em nuvem para carregar e descarregar dados:

Criação de uma função IAM personalizada

Crie uma função personalizada que tenha as permissões necessárias para acessar o bucket e obter objetos.

  1. Acesse o Console Google Cloud Platform como editor de projeto.

  2. No painel inicial, escolha IAM & admin » Roles.

  3. Clique em Create Role.

  4. Digite um nome e uma descrição para a função personalizada.

  5. Clique em Add Permissions.

  6. Filtre a lista de permissões e adicione o seguinte da lista:

    Ação(ões)

    Permissões necessárias

    Somente carregamento de dados

    • storage.buckets.get

    • storage.objects.get

    • storage.objects.list

    Carregamento de dados com opção de limpeza, executando o comando REMOVE no estágio

    • storage.buckets.get

    • storage.objects.delete

    • storage.objects.get

    • storage.objects.list

    Carregamento e descarregamento de dados

    • storage.buckets.get (para calcular custos de transferência de dados)

    • storage.objects.create

    • storage.objects.delete

    • storage.objects.get

    • storage.objects.list

    Apenas descarregamento de dados

    • storage.buckets.get

    • storage.objects.create

    • storage.objects.delete

    • storage.objects.list

  7. Clique em Create.

Atribuição da função personalizada à conta de serviço de armazenamento em nuvem

  1. Acesse o Console Google Cloud Platform como editor de projeto.

  2. No painel inicial, escolha Cloud Storage » Browser:

    Lista de buckets no console do Google Cloud Platform
  3. Selecione um bucket a ser configurado para acesso.

  4. Clique em SHOW INFO PANEL no canto superior direito. O painel de informações do bucket é exibido.

  5. Clique no botão ADD PRINCIPAL.

  6. No campo New principals, procure o nome da conta de serviço a partir da saída DESCRIBE INTEGRATION da Etapa 2: Recuperar a conta de serviço de armazenamento em nuvem para sua conta Snowflake (neste tópico).

    Painel de informações do bucket no console do Google Cloud Platform
  7. No menu suspenso Select a role, selecione Custom » <função>, em que <função> é a função de armazenamento em nuvem personalizada que você criou em Criação de uma função IAM personalizada (neste tópico).

  8. Clique no botão Save. O nome da conta de serviço é adicionado ao menu suspenso da função Storage Object Viewer no painel de informações.

    Lista de funções do visualizador de objetos de armazenamento no console do Google Cloud Platform

Concessão de permissões de conta do serviço de armazenamento em nuvem para chaves criptográficas do Cloud Key Management Service

Nota

Esta etapa é necessária apenas se seu bucket GCS estiver criptografado usando uma chave armazenada no Google Cloud Key Management Service (Cloud KMS).

  1. Acesse o Console Google Cloud Platform como editor de projeto.

  2. No painel inicial, escolha Security » Cryptographic keys.

  3. Selecione o chaveiro que é atribuído ao seu bucket GCS.

  4. Clique em SHOW INFO PANEL no canto superior direito. O painel de informações do chaveiro é exibido.

  5. Clique no botão ADD PRINCIPAL.

  6. No campo New principals, procure o nome da conta de serviço a partir da saída DESCRIBE INTEGRATION da Etapa 2: Recuperar a conta de serviço de armazenamento em nuvem para sua conta Snowflake (neste tópico).

  7. A partir do menu suspenso Select a role, selecione a função Cloud KMS CrytoKey Encryptor/Decryptor.

  8. Clique no botão Save. O nome da conta de serviço é adicionado ao menu suspenso da função Cloud KMS CrytoKey Encryptor/Decryptor no painel de informações.

Etapa 4: criar um estágio externo

Crie um estágio externo que faça referência à integração que você criou.

Nota

  • Você deve usar uma função que tenha recebido ou herdado o privilégio USAGE no banco de dados e no esquema e o privilégio CREATESTAGE no esquema. O proprietário do estágio (ou seja, a função com o privilégio OWNERSHIP no estágio) deve então ter o privilégio USAGE sobre a integração de armazenamento.

    Consulte Requisitos de controle de acesso para CREATE STAGE.

  • Para carregar ou descarregar dados de um estágio que utiliza uma integração, uma função deve ter o privilégio USAGE sobre o estágio. Não é necessário ter também o privilégio USAGE sobre a integração de armazenamento.

Criação de um estágio externo usando SQL

Certifique-se de que a função em uso tenha recebido ou herdado os privilégios necessários para criar um estágio que use uma integração de armazenamento. Por exemplo:

GRANT USAGE ON DATABASE mydb TO ROLE myrole;
GRANT USAGE ON SCHEMA mydb.stages TO ROLE myrole;
GRANT CREATE STAGE ON SCHEMA mydb.stages TO ROLE myrole;
GRANT USAGE ON INTEGRATION gcs_int TO ROLE myrole;
Copy

Você pode criar um estágio externo usando o comando CREATE STAGE.

Por exemplo, defina mydb.stages como o esquema e banco de dados atual para a sessão do usuário e depois crie um estágio chamado my_gcs_stage. Neste exemplo, o estágio faz referência ao bucket de armazenamento em nuvem e ao caminho mybucket1/path1, que são compatíveis com a integração. O estágio também faz referência a um objeto de formato de arquivo nomeado chamado my_csv_format:

USE SCHEMA mydb.stages;

CREATE STAGE my_gcs_stage
  URL = 'gcs://mybucket1/path1'
  STORAGE_INTEGRATION = gcs_int
  FILE_FORMAT = my_csv_format;
Copy

Nota

  • Coloque uma barra (/) no valor do URL para filtrar o caminho de pasta especificado. Se a barra for omitida, todos os arquivos e pastas começando com o prefixo para o caminho especificado serão incluídos.

    Note que a barra é obrigatória para acessar e recuperar arquivos de dados não estruturados no estágio.

  • O parâmetro STORAGE_INTEGRATION é tratado separadamente de outros parâmetros de estágio, tais como FILE_FORMAT. O suporte para esses outros parâmetros é o mesmo independentemente da integração usada para acessar seu bucket GCS:

Criação de um estágio externo usando Snowsight

Para usar Snowsight para criar um estágio externo nomeado, faça o seguinte:

  1. Entre em Snowsight.

  2. No menu de navegação, selecione Data » Databases.

  3. Selecione o banco de dados e o esquema no qual você deseja criar um estágio.

  4. Selecione Create » Stage.

  5. Selecione Google Cloud Platform.

  6. Insira um Stage Name.

  7. Digite o URL de seu bucket do Google Cloud Storage.

  8. Note que Enable Directory Table é selecionado por padrão. Isso permite que você veja os arquivos no estágio, mas requer um warehouse e, portanto, incorre em um custo. Você pode optar por desmarcar essa opção por enquanto e ativar uma tabela de diretórios posteriormente.

  9. Habilite Authentication.

  10. Selecione sua integração de armazenamento no menu.

  11. Opcionalmente, expanda o SQL Preview para visualizar uma instrução SQL gerada. Para especificar opções adicionais para seu estágio, como AUTO_REFRESH, você pode abrir essa versão preliminar de SQL em uma planilha.

  12. Selecione Create.

Edição de estágios existentes para uso das integrações de armazenamento

Você pode editar uma configuração de estágio externo existente para usar uma integração de armazenamento usando SQL ou a interface da Web.

Nota

  • Não é possível desativar as configurações de autenticação ou criptografia de um estágio.

  • Você pode atualizar um estágio para usar uma integração de armazenamento para autenticação. No entanto, você não poderá alterar o tipo de autenticação para credenciais se o estágio já estiver usando uma integração de armazenamento. Para alterar o tipo de autenticação, você pode descartar e recriar o estágio.

Edição de um estágio usando SQL

Use ALTER STAGE para modificar o estágio. Por exemplo:

ALTER STAGE my_gcs_stage
  SET STORAGE_INTEGRATION = gcs_int;
Copy

Edição de um estágio usando Snowsight

  1. Entre em Snowsight.

  2. No menu de navegação, selecione Data » Databases.

  3. Selecione o estágio que você deseja editar.

  4. Selecione Mais opções » Edit.

  5. Faça as alterações desejadas no estágio.

  6. Selecione Save.