Conexões entre o plano de controle do ClickHouse e sua VPC de BYOC
O plano de controle do ClickHouse Cloud mantém vários tipos de conexão para operar e dar suporte à sua implantação de BYOC:APIs do provedor de Cloud vs. a API do Kubernetes
É fácil confundir dois caminhos de controle distintos. Eles diferem quanto à origem do tráfego, à forma de autenticação e à aplicabilidade do Tailscale:
Em resumo: apenas o tráfego da API do Kubernetes e de solução de problemas pode usar o Tailscale. As chamadas de gerenciamento descritas acima sempre partem da rede do ClickHouse Cloud e chegam aos endpoints do provedor — não é possível roteá-las pelo Tailscale, pois elas nunca entram na sua rede.
As APIs do provedor de Cloud também são chamadas no sentido inverso, por controllers em execução dentro do seu próprio cluster — o controller do balanceador de carga, o driver CSI, o escalonador automático, o controller de DNS e o cert-manager. Essas chamadas usam identidades internas ao cluster e saem pelo seu próprio caminho de egress, portanto aparecem na sua trilha de auditoria com uma identidade e um endereço de origem diferentes dos das chamadas de gerenciamento. Consulte Conexões de saída.
Limites de permissões por origem de rede
Se a sua organização restringe a assunção de funções do IAM ou as chamadas à Cloud API com base na origem de rede (por exemplo, SCPs da AWS ou condições de confiança de funções que usamaws:SourceIp ou aws:SourceVpc), essas condições bloquearão a automação do ClickHouse: as chamadas se originam legitimamente da rede do ClickHouse Cloud, e não da sua. Isente as funções criadas pelo ClickHouse dessas condições ou entre em contato com o ClickHouse para obter os intervalos atuais de IPs de egress, caso seja necessário usar uma allowlist por origem.
A seção a seguir descreve como a rede privada Tailscale é usada para solução de problemas e acesso opcional de gerenciamento.
Rede privada Tailscale
O Tailscale fornece uma conexão de rede privada de confiança zero entre os serviços de gerenciamento do ClickHouse Cloud e sua implantação BYOC. Esse canal seguro permite que engenheiros do ClickHouse realizem solução de problemas e operações de gerenciamento sem exigir acesso de entrada à rede pública nem configurações complexas de VPN; os próprios agentes fazem conexões somente de saída e precisam de acesso à internet de saída para alcançar o serviço de coordenação do Tailscale.Visão geral
- Operações de gerenciamento: serviços de gerenciamento do ClickHouse que coordenam com a sua infraestrutura de BYOC
- Acesso para solução de problemas: engenheiros do ClickHouse acessando servidores da API do Kubernetes e tabelas de sistema do ClickHouse para diagnóstico
- Acesso a métricas: os dashboards centralizados de monitoramento do ClickHouse acessam métricas da stack Prometheus implantada na sua VPC de BYOC, fornecendo aos engenheiros do ClickHouse observabilidade do ambiente.
Como o Tailscale funciona no BYOC
Para cada serviço ou endpoint que precisa ser acessado via Tailscale, o ClickHouse BYOC implanta:-
Registro de endereço tailnet: cada endpoint registra um endereço tailnet exclusivo (por exemplo,
k8s.xxxx.us-east-1.aws.byoc.clickhouse-prd.compara o servidor da API do Kubernetes) -
Contêiner do agente Tailscale: um contêiner do agente Tailscale é executado no seu cluster do Kubernetes e é responsável por:
- Conectar-se ao servidor de coordenação do Tailscale
- Registrar serviços para torná-los detectáveis
- Coordenar a configuração da rede com os pods do Kubernetes do Nginx
-
Pod do Kubernetes do Nginx: um pod do Kubernetes do Nginx que:
- Faz a terminação do tráfego TLS do Tailscale
- Encaminha o tráfego para os IPs apropriados dentro do seu cluster do Kubernetes
Processo de conexão de rede
-
Conexão inicial:
- Os agentes do Tailscale em ambas as pontas (o ambiente do engenheiro do ClickHouse e seu cluster do Kubernetes BYOC) se conectam ao servidor de coordenação do Tailscale
- O agente do cluster registra o serviço do Kubernetes para que ele possa ser descoberto
- Os engenheiros do ClickHouse precisam fazer um escalonamento interno para obter visibilidade do serviço
-
Modo de conexão:
- Modo direto: os agentes tentam estabelecer uma conexão direta por meio de um túnel de travessia de NAT
- Modo de retransmissão: se o modo direto falhar, a comunicação passa a usar o modo de retransmissão por meio de um servidor DERP (Distributed Encrypted Relay Protocol) do Tailscale
-
Criptografia:
- Toda a comunicação é criptografada de ponta a ponta
- Cada agente do Tailscale gera seu próprio par de chaves pública e privada (semelhante a uma PKI)
- O tráfego permanece criptografado independentemente de usar o modo direto ou de retransmissão
Recursos de segurança
- Os agentes do Tailscale no seu cluster do Kubernetes iniciam conexões de saída com os servidores de coordenação/relay do Tailscale
- Nenhuma conexão de entrada é necessária — nenhuma regra do Security Group precisa permitir tráfego de entrada para os agentes do Tailscale
- Isso reduz a superfície de ataque e simplifica a configuração de segurança da rede
- Os engenheiros precisam solicitar acesso por meio de um fluxo interno de aprovação antes que o Tailscale possa encaminhá-los para um endpoint do cliente
- O acesso é limitado no tempo e expira automaticamente
- Todo acesso é auditado e registrado
Acesso aos serviços de gerenciamento
Por padrão, os serviços de gerenciamento da ClickHouse alcançam seu cluster do Kubernetes BYOC por meio do endpoint público do servidor da API, que cada nuvem controla de forma diferente — na AWS, por uma IP allow list contendo apenas os endereços do gateway NAT da ClickHouse; no GCP e no Azure, pelo IAM da nuvem. Consulte Exposição do servidor da API do Kubernetes para os detalhes de cada nuvem. Configuração opcional de endpoint privado:- Você pode configurar o servidor da API do Kubernetes para usar apenas um endpoint privado
- Nesse caso, os serviços de gerenciamento acessam o servidor de API via Tailscale (semelhante ao acesso humano para solução de problemas) ou, na AWS, via VPC Lattice (consulte Conexão privada com a API do Kubernetes)
- Por padrão, o endpoint público é mantido como mecanismo de contingência para necessidades emergenciais de investigação e suporte; após a verificação do acesso privado, ele pode ser totalmente desabilitado em coordenação com a ClickHouse
Fluxo de tráfego de rede
- Agente do Tailscale no seu cluster do Kubernetes → servidor de coordenação do Tailscale (saída)
- Agente do Tailscale na máquina do engenheiro → servidor de coordenação do Tailscale (saída)
- Conexão direta ou retransmitida estabelecida entre os agentes
- O tráfego criptografado flui pelo túnel estabelecido
- O pod do Kubernetes do Nginx no seu cluster do Kubernetes faz a terminação de TLS e roteia para os serviços internos
- As conexões do Tailscale são usadas apenas para gerenciamento e solução de problemas
- O tráfego de consulta e os dados do cliente nunca passam pelo Tailscale
- Todos os dados do cliente permanecem na sua própria conta de nuvem
Fronteiras de rede
Esta seção apresenta a visão de firewall de uma implantação BYOC: cada conexão que atravessa a fronteira da sua rede BYOC, em qualquer direção. Aplica-se a AWS, GCP e Azure; quando o comportamento varia entre as nuvens, a nuvem é indicada explicitamente. Termos usados ao longo do texto:- Entrada: tráfego que entra na sua rede BYOC — uma VPC na AWS, uma rede VPC no GCP ou uma VNet no Azure.
- Saída: tráfego originado na sua rede BYOC e enviado a um destino externo.
- Público: um endpoint acessível pela internet pública.
- Privado: um endpoint acessível somente por um caminho privado — peering de VPC/VNet, AWS PrivateLink, GCP Private Service Connect, Azure Private Link ou Tailscale.
Equivalentes por provedor
O restante desta página usa nomes neutros em relação à nuvem. Esta tabela os mapeia para cada provedor:
Em todas as nuvens, o egress para a internet pública sai da sua rede BYOC por um conjunto pequeno e fixo de endereços NAT, o que permite fixá-los nos seus próprios controles de egress. Solicite à equipe da ClickHouse os valores atuais da sua implantação. Na AWS e no GCP, o tráfego para as APIs de armazenamento do próprio provedor é uma exceção: ele segue o caminho privado indicado na linha acima e nunca chega ao NAT gateway.
Conexões de entrada
Às vezes duas portas ficam visíveis nesses balanceadores de carga, mas elas não são voltadas ao cliente: a TCP 15021 atende às verificações de integridade do próprio provedor sobre o gateway de entrada e não transporta tráfego de consultas, e a interface MySQL (porta 3306) não está exposta no BYOC atualmente — consulte o FAQ.
O certificado do gateway de entrada é emitido pelo cert-manager a partir de uma certificate authority ACME pública (Let’s Encrypt) usando validação DNS-01, e é armazenado como um Kubernetes secret dentro do seu próprio cluster. O tráfego entre o gateway de entrada e os pods do ClickHouse permanece dentro da sua rede BYOC — consulte Tráfego intrarrede.
Qual dos dois balanceadores de carga fica habilitado por padrão depende do seu modelo de rede. Com uma VPC gerenciada pela ClickHouse, cada service recebe o balanceador de carga público, protegido por uma lista de acesso por IP, e o balanceador de carga privado pode ser habilitado junto com ele. Com uma VPC gerenciada pelo cliente, os padrões se invertem: apenas o balanceador de carga privado é habilitado, e seus services não têm nenhuma superfície de entrada pública, a menos que você adicione uma. Consulte Conecte-se ao seu serviço BYOC.
Sempre que o caminho público estiver habilitado, recomendamos fortemente configurar um filtro de IP. Você também pode adicionar um caminho privado — consulte Configuração de rede privada — e depois desabilitar totalmente o acesso público. Observe que a filtragem de IP é aplicada na camada do proxy de entrada, ou seja, as portas do balanceador de carga podem aparecer abertas em uma varredura, mesmo que conexões de origens não listadas sejam rejeitadas.
Além dos listeners acima, não há SSH, nem host bastion, nem credencial administrativa permanente. O tráfego de consultas nunca atravessa a infraestrutura da ClickHouse em nenhuma direção: seus clientes se conectam diretamente à entrada dentro da sua própria rede.Portas de protocolo adicionais podem ser habilitadas por implantação — acesso nativo autenticado por certificado e Arrow Flight são os exemplos atuais —, portanto confirme o conjunto exato de portas da sua implantação com sua equipe ClickHouse antes de escrever regras de firewall a partir desta tabela.
Exposição do servidor da API do Kubernetes
A forma como os serviços de gerenciamento do ClickHouse alcançam o servidor da API do Kubernetes, e o que restringe esse access, varia conforme a cloud:- AWS (EKS): o endpoint público é restrito às faixas CIDR de egress do ClickHouse por meio da lista de CIDRs de acesso público do cluster. É possível alternar para acesso exclusivamente privado via Tailscale ou VPC Lattice — consulte Kubernetes API Private Connection.
- GCP (GKE): os nodes são sempre privados. O plano de controle é acessado por meio de seu endpoint baseado em DNS (
*.gke.goog), autorizado pela permission IAMcontainer.clusters.connectna service account personificada, e não por uma IP allow list. A request termina no frontend do Google, e não dentro da sua rede VPC, mas ainda assim é um caminho de access ao plano de controle do seu cluster, portanto avalie-o como acesso de entrada. O endpoint público separado, baseado em IP, pode ser desabilitado, o que deixa o endpoint baseado em DNS como o único caminho para o plano de controle — consulte Kubernetes API Private Connection. - Azure (AKS): o API server é acessado por meio de seu FQDN público e autorizado pelo Microsoft Entra ID em conjunto com o Azure RBAC. As faixas de IP autorizadas do API server não são aplicadas por padrão; entre em contato com a ClickHouse se sua policy as exigir. Como alternativa, o cluster pode ser criado como um cluster privado acessado via Azure Private Link, com seu FQDN público desabilitado — consulte Kubernetes API Private Connection.
Somente o tráfego da Kubernetes API e de solução de problemas pode ser movido para um caminho privado. As chamadas de gerenciamento às APIs do seu provedor de Cloud originam-se da rede do ClickHouse Cloud e não podem ser roteadas por ele — consulte APIs do provedor de Cloud vs. a Kubernetes API, que também aborda as API calls ao provedor feitas por controllers dentro do seu próprio cluster.
Troubleshooting access
Entrada, Privado Os engenheiros do ClickHouse Cloud acessam sua implantação para troubleshooting somente via Tailscale, nunca pela internet pública, em todas as nuvens. O acesso é just-in-time e baseado em certificados: o engenheiro o solicita por meio de um fluxo interno de aprovação, a plataforma emite uma credencial individual de curta duração para cada engenheiro e ela expira automaticamente. Não há identidade administrativa compartilhada nem standing access. Consulte ClickHouse data access para conhecer a política completa, incluindo quais tabelas os engenheiros podem ler.Conexões de saída
Coletor de faturamento
Saída, Private O coletor de faturamento reúne dados de uso do ClickHouse e os envia para um bucket pertencente ao ClickHouse Cloud — S3 na AWS, Cloud Storage no GCP, Blob Storage no Azure. Ele é executado como um sidecar junto ao contêiner do servidor ClickHouse e coleta periodicamente métricas de CPU e memória das system tables do ClickHouse. Os registros são indexados por um identificador de serviço opaco e pelo nome do pod do Kubernetes. As requisições na mesma região seguem o caminho privado até as storage APIs do provedor listadas em Equivalentes por provedor, de modo que esse tráfego não passa pela internet pública na AWS nem no GCP.Alertas
Saída, Público O AlertManager é configurado para enviar alertas ao ClickHouse Cloud quando o seu cluster ClickHouse não está saudável. Os payloads de alerta do BYOC são deliberadamente reduzidos a um nome de alerta e a um identificador de service. O conjunto completo de dados de monitoramento permanece na sua própria conta em todas as nuvens. Distinga duas coisas aqui, pois elas têm fronteiras diferentes:- Exportado continuamente. A telemetria reduzida de uso e saúde descrita em Billing scraper, somada a esses payloads de alerta, é o único dado de observabilidade gravado em sistemas de propriedade da ClickHouse. O remote-write do Prometheus para o ClickHouse Cloud está desabilitado nas compilações BYOC.
- Lido no local. Os dashboards de monitoramento da ClickHouse e, mediante escalation aprovada, seus engenheiros consultam a stack do Prometheus dentro do cluster e os seus logs via Tailscale — consulte Tailscale Private Network. Os resultados das consultas necessariamente chegam às ferramentas do lado da ClickHouse para serem exibidos, mas nada é persistido lá e os dados subjacentes nunca saem da sua conta.
Estado do serviço
Saída, Público O state exporter envia informações sobre o estado do serviço ClickHouse e dos backups — eventos de status operacional, e não o conteúdo dos backups — para uma fila pertencente ao ClickHouse Cloud: SQS na AWS, Pub/Sub no GCP e Service Bus no Azure. É isso que permite ao console do ClickHouse Cloud exibir o status de um serviço em execução na sua conta.Tráfego intrarrede
O tráfego entre componentes dentro do cluster — do ClickHouse para o ClickHouse Keeper, o operator, da entrada para os pods do ClickHouse, scrapes de monitoramento — nunca sai da sua rede BYOC. Cada provider criptografa o tráfego entre suas próprias instances na camada de rede: consulte AWS, GCP e Azure. Por padrão, o egress não sofre restrições nas camadas de security group, regra de firewall e network security group; os destinos efetivamente contatados são os que constam em Conexões de saída. Como alternativa, um firewall de egress opcional por service pode impor uma allowlist de destinos — entre em contato com a equipe da ClickHouse caso precise disso.Auditando a fronteira
Como todo o data plane é executado na sua própria conta, os fluxos descritos nesta página podem ser observados com as suas próprias ferramentas. Algumas fontes vêm ativadas por padrão; outras você mesmo habilita:- Trilha de auditoria da nuvem (CloudTrail, Cloud Audit Logs ou o Azure Activity log): cada role assumption, impersonation de service account ou login de service principal feito pela automação da ClickHouse, e cada chamada de Cloud API realizada com ela.
- Flow logs (VPC Flow Logs, VPC flow logs ou NSG flow logs): as connections acima que atravessam a sua própria rede — entrada de clientes, cada fluxo de saída e o canal Tailscale. Habilite-os você mesmo caso queira retê-los. O acesso de gerenciamento ao Kubernetes API server é a exceção: enquanto o public endpoint estiver em uso, ele termina no endpoint do control-plane gerenciado do seu provider, e não dentro da sua rede, portanto não aparece nos seus flow logs. Procure por ele nos audit logs do Kubernetes e na trilha de auditoria da sua nuvem; ele só aparece nos flow logs depois que o API server passar a usar um Private Endpoint.
- Audit logs do Kubernetes: na AWS, os logs do control-plane do EKS, incluindo o audit log, são entregues a um log group do CloudWatch na sua conta; no GCP e no Azure, contact support para confirmar ou habilitar o logging de auditoria do control-plane do seu cluster.
- Logs de acesso ao armazenamento de objetos nos seus buckets de dados e de backup, e no bucket de retenção de longo prazo de Monitoring, onde você tiver isso habilitado.
- Seu próprio
system.query_log: cada statement executado pela automação da ClickHouse ou por um engenheiro, com a identity associada.