Configuração do ClickHouse

O chart tdp-clickhouse empacota o ClickHouse 25.8.11.66 para Kubernetes, utilizando o Altinity ClickHouse Operator (ClickHouseInstallation).

O que é o ClickHouse?

O ClickHouse é um base de dados colunar de alta performance voltado para analytics.

Em vez de armazenar dados linha por linha (como o PostgreSQL), ele armazena coluna por coluna — o que permite leituras extremamente rápidas quando você precisa agregar grandes volumes de dados (soma de vendas por mês, médias, contagens).

No TDP Kubernetes, o ClickHouse é usado como destino de dados já processados: pipelines carregam dados transformados para ele, e ferramentas como Superset e CloudBeaver consultam esses dados para análise e visualização.

Para saber mais

Consulte ClickHouse — Conceitos para uma visão completa da ferramenta, sua arquitetura e funcionamento.

O modelo de operador: Altinity ClickHouse Operator

O chart usa o Altinity ClickHouse Operator, que funciona de forma similar ao Strimzi para o Kafka: você descreve o estado desejado do cluster em um recurso Kubernetes chamado ClickHouseInstallation (CHI), e o operador cuida de criar e manter os Pods, Services e PVCs correspondentes.

Isso significa que, depois de instalar o chart, você verá um recurso chi no cluster (além dos Pods e Services).

A maioria das customizações avançadas é feita via extraConfig (XML do ClickHouse) ou via blocos comentados no values.yaml.

Componentes implantados

Componente	Descrição
Altinity Operator	Gerencia o ciclo de vida do ClickHouseInstallation
ClickHouseInstallation	CRD que define o cluster: shards, réplicas, storage
Job TDP User (opcional)	Cria usuário dedicado TDP com grants adequados
Job S3 (opcional)	Cria bucket S3 e Secret de conexão para o ClickHouse
Job Cleanup	Remove recursos do ClickHouse antes de desinstalar o chart

Visão geral

O pacote inclui, entre outros:

• Deploy opcional do operador (dependência do chart)
• Deploy do cluster ClickHouse (ClickHouseInstallation)
• Storage persistente
• Integrações opcionais TDP: job de bucket/Secret S3 (TDPConfigurations.s3Connection), usuário TDP dedicado e job de grants, job de cleanup pré-delete

Pré-requisitos

• Kubernetes e Helm 3
• StorageClass padrão ou tdp-clickhouse.clickhouse.persistence.storageClass definido

Instalação (OCI)

Terminal input

helm upgrade --install <release> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
  -n <namespace> --create-namespace

Todas as opções estão na exportação helm show values; use um ficheiro de valores privado para sobrescritas.

Parâmetros principais

Parâmetro	Descrição	Padrão (referência)
tdp-clickhouse.clickhouse.enabled	Habilitar cluster	true
tdp-clickhouse.clickhouse.persistence.*	PVC (tamanho, storageClass, accessModes)	ver helm show values
tdp-clickhouse.clickhouse.resources	Requests/limits CPU e memória	ver helm show values
tdp-clickhouse.clickhouse.defaultUser.password	Senha do usuário default	""
tdp-clickhouse.clickhouse.tdpUser.enabled	Usuário TDP + job de grants	false
tdp-clickhouse.operator.enabled	Operador Altinity	true
tdp-clickhouse.cleanup.enabled	Job de cleanup pré-delete	true
TDPConfigurations.s3Connection.*	Bucket/Secret S3 (job opcional)	desabilitado por predefinição

Recursos (CPU e memória)

tdp-clickhouse:
  clickhouse:
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

Atenção

Use o prefixo tdp-clickhouse.clickhouse.resources (não tdp-clickhouse.resources isolado).

Alta disponibilidade (HA)

A exportação de valores traz blocos comentados de exemplo (shards/réplicas, Keeper opcional, etc.). Descomente e ajuste apenas quando necessário.

Para inspecionar o cluster após o deploy:

Terminal input

kubectl -n <namespace> get pods
kubectl -n <namespace> get chi

Para consultas de diagnóstico, use um pod do ClickHouse listado pelos labels do operador (o nome exato depende do ClickHouseInstallation):

Terminal input

POD=$(kubectl -n <namespace> get pods \
  -l clickhouse.altinity.com/chi=<chi-name> \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n <namespace> exec -it "$POD" -- clickhouse-client -q "SELECT * FROM system.clusters"

Substitua <chi-name> pelo nome do recurso chi do seu ambiente (kubectl get chi -n <namespace>).

TDPConfigurations.s3Connection (opcional)

Quando enabled: true, um job tenta criar o bucket (se não existir) e gera o Secret tdp-clickhouse-s3-connection. Use placeholders e armazene credenciais fora do Git:

TDPConfigurations:
  s3Connection:
    enabled: true
    bucket: "<s3-bucket-name>"
    accessKey: "<s3-access-key>"
    secretKey: "<s3-secret-key>"
    uri: "https://<s3-endpoint>"
    selfSigned: false

O ClickHouse em si usa S3 via tdp-clickhouse.clickhouse.extraConfig (XML), alinhado a esse endpoint — siga o exemplo completo em helm show values e a documentação do ClickHouse.

Usuário TDP opcional

• tdp-clickhouse.clickhouse.tdpUser.enabled: cria Secret (tdp-clickhouse-tdp-user) e job pós-install/upgrade para grants.
• Senha: informe via ficheiro de valores privado (tdp-clickhouse.clickhouse.tdpUser.password).

Acesso

Port-forward (HTTP)

Terminal input

kubectl -n <namespace> port-forward svc/<service-name> 8123:8123
curl "http://localhost:8123/?query=SELECT%201"

<service-name> é o Service HTTP do ClickHouse gerado pelo chart/release (consulte kubectl get svc -n <namespace>).

Resolução de nomes

Para endpoints S3 ou outros alvos acessíveis apenas por hostname customizado, garanta resolução DNS no cluster (por exemplo CoreDNS/ExternalDNS) ou, se aplicável ao seu ambiente, entradas equivalentes no pod — evite documentar IPs fixos aqui.

Solução de problemas

Terminal input

kubectl -n <namespace> get pods
kubectl -n <namespace> get chi
kubectl -n <namespace> logs deployment/<operator-deployment-name>
kubectl -n <namespace> logs -l clickhouse.altinity.com/chi=<chi-name>

Desinstalação

Terminal input

helm -n <namespace> uninstall <release>