Pular para o conteúdo principal
Este guia mostra como se autenticar com segurança no Google Cloud Storage (GCS) e acessar seus dados no ClickHouse Cloud.

​
Introdução

O ClickHouse Cloud se conecta ao GCS usando chaves HMAC (Hash-based Message Authentication Code) associadas a uma conta de serviço do Google Cloud. Essa abordagem fornece acesso seguro aos seus buckets do GCS sem incorporar credenciais diretamente nas consultas. Como funciona:
  1. Você cria uma conta de serviço do Google Cloud com as permissões apropriadas no GCS
  2. Você gera chaves HMAC para essa conta de serviço
  3. Você fornece essas credenciais HMAC ao ClickHouse Cloud
  4. O ClickHouse Cloud usa essas credenciais para acessar seus buckets do GCS
Essa abordagem permite gerenciar todo o acesso aos buckets do GCS por meio de políticas do IAM na conta de serviço, facilitando conceder ou revogar acesso sem modificar políticas individuais de bucket.

​
Pré-requisitos

Para seguir este guia, você precisará de:
  • Um serviço do ClickHouse Cloud ativo
  • Um projeto do Google Cloud com o Cloud Storage ativado
  • Permissões para criar contas de serviço e gerar chaves HMAC no seu projeto do GCP

​
Setup

1

​
Criar uma conta de serviço do Google Cloud

  1. No Google Cloud Console, navegue até IAM & Admin → Service Accounts
  1. No menu à esquerda, clique em Service accounts e depois em Create service account:
Insira um nome e uma descrição para sua conta de serviço, por exemplo:
Clique em Create and continueConceda à conta de serviço o papel Storage Object User:Esse papel fornece acesso de leitura e gravação aos objetos do GCS
Para acesso somente leitura, use Storage Object Viewer Para um controle mais granular, você pode criar um papel personalizado
Clique em Continue e, em seguida, em DoneAnote o endereço de e-mail da conta de serviço:
2

​
Conceda à conta de serviço acesso ao bucket

Você pode conceder acesso no nível do projeto ou no nível de buckets individuais.

​
Opção 1: Conceder acesso a buckets específicos (recomendado)

  1. Navegue até Cloud Storage → Buckets
  2. Clique no bucket ao qual você deseja conceder acesso
  3. Vá para a guia Permissions
  4. Em “Permissions”, clique em Grant access para o principal criado nas etapas anteriores
  5. No campo “New principals”, insira o e-mail da sua conta de serviço
  6. Selecione a Role apropriada:
  • Storage Object User para acesso de leitura/gravação
  • Storage Object Viewer para acesso somente leitura
  1. Clique em Save
  2. Repita o processo para quaisquer buckets adicionais

​
Opção 2: Conceder acesso no nível do projeto

  1. Navegue até IAM & Admin → IAM
  2. Clique em Grant access
  3. Insira o e-mail da sua conta de serviço no campo New principals
  4. Selecione Storage Object User (ou Storage Object Viewer para acesso somente leitura)
  5. Clique em SAVE
Prática recomendada de segurançaConceda acesso apenas aos buckets específicos que o ClickHouse precisa acessar, em vez de conceder permissões para todo o projeto.
3

​
Gere chaves HMAC para a conta de serviço

Navegue até Cloud Storage → Settings → Interoperability:Se você não vir uma seção “Access keys”, clique em Enable interoperability accessEm “Access keys for service accounts”, clique em Create a key for a service account:Selecione a conta de serviço que você criou anteriormente (por exemplo, clickhouse-gcs-access@your-project.iam.gserviceaccount.com)Clique em Create key:A chave HMAC será exibida. Salve imediatamente a Access Key e a Secret — você não poderá visualizar a secret novamente.Exemplos de chaves são mostrados abaixo:
ImportanteArmazene essas credenciais em segurança. O segredo n’o poderá ser recuperado depois que esta tela for fechada. Você precisará gerar novas chaves se perder o segredo.

​
Use chaves HMAC com ClickHouse Cloud

Agora você pode usar as credenciais HMAC para acessar o GCS no ClickHouse Cloud. Para isso, use a função de tabela do GCS:
Use curingas para vários arquivos:

​
Autenticação HMAC no ClickPipes para GCS

O ClickPipes usa chaves HMAC (Hash-based Message Authentication Code) para se autenticar no Google Cloud Storage.Ao configurar um ClickPipe do GCS:
  1. Selecione Credentials em Authentication method durante a configuração do ClickPipe
  2. Informe as credenciais HMAC obtidas nas etapas anteriores
No momento, a autenticação com conta de serviço não é compatível - você deve usar chaves HMAC A URL do bucket do GCS deve usar o formato: https://storage.googleapis.com/<bucket>/<path> (não gs://)
As chaves HMAC devem estar associadas a uma conta de serviço que tenha o papel roles/storage.objectViewer, que inclui:
  • storage.objects.list: para listar objetos no bucket
  • storage.objects.get: para recuperar/ler objetos

​
Boas práticas

​
Use contas de serviço separadas para ambientes diferentes

Crie contas de serviço separadas para os ambientes de desenvolvimento, staging e produção. Por exemplo:
  • clickhouse-gcs-dev@project.iam.gserviceaccount.com
  • clickhouse-gcs-staging@project.iam.gserviceaccount.com
  • clickhouse-gcs-prod@project.iam.gserviceaccount.com
Isso permite revogar com facilidade o acesso de um ambiente específico sem afetar os demais.

​
Aplique o princípio do menor privilégio

Conceda apenas as permissões mínimas necessárias:
  • Use Storage Object Viewer para acesso somente leitura
  • Conceda acesso a buckets específicos em vez de ao projeto inteiro
  • Considere usar condições no nível do bucket para restringir o acesso a caminhos específicos

​
Faça a rotação regular das chaves HMAC

Implemente um cronograma de rotação de chaves:
  • Gere novas chaves HMAC
  • Atualize as configurações do ClickHouse com as novas chaves
  • Verifique o funcionamento com as novas chaves
  • Exclua as chaves HMAC antigas
O Google Cloud não impõe expiração às chaves HMAC, portanto você deve implementar sua própria política de rotação.

​
Monitore o acesso com os Cloud Audit Logs

Ative e monitore os Cloud Audit Logs do Cloud Storage:
  1. Acesse IAM & Admin → Audit Logs
  2. Encontre Cloud Storage na lista
  3. Ative Admin Read, Data Read e Data Write logs
  4. Use esses logs para monitorar padrões de acesso e detectar anomalias
Última modificação em 19 de junho de 2026