Skip to main content

​
Componentes

O ClickHouse Connector executa três daemons, todos embutidos no binary clicklink:
  • O executor mantém um canal de comandos de saída com o seu connector endpoint e aplica os comandos de ciclo de vida que o ClickHouse Cloud envia para os serviços que gerencia no seu cluster. Os comandos são: criação, escalonamento, parada e início, reinicialização, backup e exclusão de backup, exclusão e atualizações de plataforma que você aprovou. Toda ação é uma chamada à Kubernetes API. Ele não abre nenhuma connection com o ClickHouse nem mantém credenciais dos seus buckets ou do IAM. É executado apenas no modo managed.
  • O scraper lê uma allowlist de tabelas de sistema do ClickHouse em um intervalo fixo e armazena os resultados localmente em buffer. Em seguida, os envia ao seu connector endpoint junto com metadado de infraestrutura e status de saúde.
  • O troubleshooter mantém um canal de comandos de saída com o seu connector endpoint e executa diagnósticos read-only durante uma sessão de suporte ativa. Fora de uma session, ele não executa nada.
No Kubernetes, o chart do Helm clicklink-connector implanta os daemons em um espaço de nomes de sua escolha (padrão: clicklink). O executor é uma Implantação de réplica única que mantém o estado de seus comandos em um volume persistente. Em uma Linux VM, os daemons são executados como os systemd units clicklink-scraper, clicklink-troubleshooter e clicklink-executor, sob um usuário de sistema clicklink sem privilégios.

​
Conexões

Toda conexão feita pelo connector é de saída. A lista completa: Toda request de API leva um header Authorization com uma assinatura HMAC-SHA256 sobre o método, o caminho, o timestamp e um hash do corpo. As requests não podem ser reproduzidas nem alteradas em trânsito, nem mesmo dentro do canal TLS. Na entrada, cada daemon expõe uma única porta local de saúde: 8082 para o scraper, 8084 para o troubleshooter e 8086 para o executor. Essa porta atende /livez, /readyz, /healthz e as métricas Prometheus do daemon em /metrics; não há porta separada para métricas. A API local de comandos do executor escuta apenas em loopback e nenhum Service a expõe. O único outro listener é o gateway de sessão opcional; consulte sessões de suporte. O ClickHouse Cloud nunca se conecta a nenhum deles.

​
Ciclo de vida do certificado

O connector se autentica no seu endpoint com um certificado de cliente que ele mesmo obtém e mantém. Os três daemons apresentam o mesmo certificado.
  • Inscrição. O clicklink clctl init gera localmente uma chave privada e uma solicitação de assinatura de certificado (CSR). A CSR leva o ID da sua organização como common name e o host do seu endpoint como único DNS SAN. A chave privada nunca sai do seu ambiente.
  • Primeira emissão. O init envia a CSR ao endpoint de assinatura de inscrição em /v1/pcm/cert/sign, autenticado com HMAC. Se já existir um certificado não expirado para a sua organização, o endpoint recusa a solicitação com um 409. O CLI então exibe como concluir o processo usando o certificado existente ou substituí-lo com --force.
  • Renovação automática. Os três daemons verificam o ciclo de vida do certificado a cada 12 horas. Quando restam 10 dias, eles solicitam um certificado renovado de 30 dias por meio de /v1/pcm/cert/renew (mTLS mais HMAC). No Kubernetes, o certificado renovado é gravado de volta no Secret clicklink-mtls por meio de um grant de RBAC com nome exato; em uma VM, cada daemon o grava em /etc/clicklink/tls. A renovação não exige nenhuma ação do operator.
O connector verifica o certificado do servidor do seu endpoint com base no system trust store. Quando api.tls.ca_file (VM) ou api.tls.caFile (Helm) está definido, a CA chain do seu pacote de enrollment é anexada a essas raízes.

​
Fluxo de dados

​
O que sai do seu ambiente

  • Métricas de tabelas de sistema na allowlist. O conjunto padrão do scraper inclui metric_log, asynchronous_metric_log, tables, warnings e server_settings. A allowlist é configurada explicitamente; o scraper não lê nada fora dela.
  • Metadados de infraestrutura. Inventário de serviços, infraestrutura e backups sincronizado pela API. Para um serviço gerenciado, isso inclui seu estado, a quantidade atual e esperada de réplicas, além da versão do servidor em execução e da versão da configuração.
  • Integridade e autométricas. Status dos componentes e métricas operacionais do próprio connector. O heartbeat do executor também informa se seu canal de comandos está conectado. Ele carrega o resultado da última atualização da plataforma, as versões dos componentes da plataforma e o digest do último pacote aplicado. Em uma instalação em VM, ele acrescenta se seu pacote de acesso ao Kubernetes está ok, expiring, expired ou ausente.
  • Resultados de comandos. Para cada comando de ciclo de vida executado pelo executor: o progresso durante a convergência e, em seguida, sucesso ou falha com o texto do erro em caso de falha.
  • Definições de serviço que você envia. clicklink clctl instances create envia o ID do seu ambiente, a nuvem e a região, o nome do serviço, os nomes de seus buckets e o ARN da IAM role, além de uma chave de idempotência. Também envia dois hashes da senha do default user (SHA-256 e SHA-1 duplo).
  • Saída da sessão de suporte. Resultados de diagnósticos read-only executados durante uma sessão habilitada por você, após o mascaramento de informações sensíveis.

​
O que nunca sai por padrão

  • Texto bruto das consultas, no caminho de scrape. A system.query_log fica fora do conjunto padrão de scrape porque suas colunas de consulta podem conter valores literais e, junto com eles, PII ou secrets. Reincluí-la é um override feito em cada implantação. A allowlist padrão de tabelas de sessão inclui a system.processes, que exibe o texto das consultas em execução; consulte sessões de suporte para saber como restringi-la.
  • Os dados das suas tabelas e os backups. Eles permanecem em buckets na sua conta. O executor não possui credenciais para os seus buckets e não consegue lê-los.
  • Credenciais. O init não grava credenciais em arquivos de configuração. O ClickHouse armazena apenas hashes bcrypt das senhas dos usuários do connector, e os secrets permanecem em Kubernetes Secrets ou em arquivos legíveis apenas pelo root no host. A senha do default user de um managed service é gerada do seu lado e exibida uma única vez; apenas seus hashes são enviados. Nada nos caminhos de scrape ou de sincronização transmite uma credencial.
  • Saída do troubleshooter sem ocultação de dados sensíveis. Tudo o que o troubleshooter retorna passa por padrões de mascaramento (os internos e os seus) antes de sair. Consulte sessões de suporte.

​
Fronteiras de confiança

  • Seu ambiente é a fronteira. O ClickHouse Cloud recebe apenas o que o connector envia: scrapes, heartbeats e status, resultados de comandos e o que uma sessão de suporte ativa retorna. Ele nunca inicia uma conexão de fora para dentro.
  • O gateway de sessão é seu. Ele só é acessível dentro do seu ambiente (via kubectl port-forward no Kubernetes, ou localmente em uma VM), a menos que você opte por expô-lo por meio de um Ingress. O ClickHouse Cloud nunca se conecta a ele.
  • O acesso ao ClickHouse é read-only. Os usuários pcm_scraper e pcm_troubleshooter possuem grants SELECT por tabela, o READ ON REMOTE do scraper (necessário para clusterAllReplicas()) e um único grant SYSTEM FLUSH LOGS exclusivo do scraper. Não existem grants de INSERT, DDL ou de gerenciamento de usuários. O executor não tem usuário no ClickHouse. A listagem exata está no modelo de privilégios.
  • O scraper e o troubleshooter não podem alterar seu cluster. O RBAC deles vem de Funções nos espaços de nomes do connector e dos serviços. Essas Funções concedem verbos read-only sobre recursos de workload e acesso por nome exato aos Secrets do próprio connector. Não há permissão de exec, delete ou patch.
  • O executor altera o estado do cluster nos espaços de nomes de serviço como pcm-executor. Ele cria e exclui espaços de nomes que carregam o prefixo de serviço (ns- por padrão) e exclui pods para reiniciá-los. Dentro desses espaços de nomes, ele escreve os objetos ClickHouseCluster, Backup e ScalingOverride e os Secrets, ServiceAccounts e Services de que um serviço precisa. Ele também escreve a Função e o RoleBinding que dão acesso de leitura ao scraper. Uma ValidatingAdmissionPolicy nega qualquer escrita dessa ServiceAccount fora do prefixo. As exceções, todas em seu espaço de nomes de origem, são a renovação do seu próprio token, o ConfigMap clicklink-instance-registry e, no Kubernetes, o certificado de cliente renovado no Secret de mTLS. A policy falha de forma fechada quando não pode ser avaliada. A admission não é executada em leituras, portanto as leituras dessas famílias de recursos não ficam limitadas pelo prefixo.
  • O executor altera espaços de nomes de plataforma apenas como pcm-platform, durante uma atualização aprovada por você. O clicklink clctl platform approve emite o token dessa identidade por 2 horas; ele nunca é renovado. Com ele, o executor pode escrever apenas Deployments, Services, ConfigMaps, Secrets, Jobs e PodDisruptionBudgets. Espaços de nomes, CRDs, ServiceAccounts, RBAC, configurações de webhook e admission, PriorityClasses e a StorageClass são aplicados com as suas credenciais durante a aprovação. Consulte atualizações de plataforma.
  • O executor não possui credenciais para seus buckets ou IAM. O clicklink clctl executor prepare cria os buckets de dados e de backup de um serviço e sua role IAM. O clicklink clctl executor teardown os remove. Ambos são executados com as suas credenciais. A role confia apenas nos pods daquele serviço, de modo que nem o executor nem o ClickHouse podem assumi-la. Suas únicas chamadas de nuvem vão para o Amazon ECR e o STS. Ele faz login no registry quando um sync de plataforma ou uma criação baixa um chart. Durante uma atualização de plataforma, ele verifica as imagens sob a role de pull read-only.
  • Política de rede. No Kubernetes, o chart renderiza uma NetworkPolicy de negação padrão para cada daemon. O egress é permitido apenas para DNS, para os CIDRs que você lista para o endpoint do seu connector e para os CIDRs do servidor de API do Kubernetes. As políticas do scraper e do troubleshooter também permitem os ClickHouse Services em espaços de nomes gerenciados pelo executor (selecionados pelo rótulo que ele aplica neles) ou que você liste por nome. A política do executor não tem regra para o ClickHouse. Se os charts de um pacote de plataforma residirem no Amazon ECR, adicione os intervalos do ECR e do STS (ou o espelho do seu registry) a allowEgressCIDRs. Sem eles, o sync não consegue baixar os charts sob um CNI que aplica políticas. Sem um CNI com enforcement, a política é inerte. Consulte configuração.
  • Endurecimento do host em VMs. As units são executadas como um usuário de sistema sem login, com ProtectSystem=strict, NoNewPrivileges, caminhos de configuração read-only e o modo FIPS habilitado.
Para conhecer os grants e as regras de RBAC exatos do connector, consulte a referência do modelo de privilégios. Se a própria ClickHouse provisiona e opera o cluster, o modelo de confiança é diferente; consulte as páginas arquitetura do BYOC e privilégios do BYOC.