Versão 3.0.0

Configuração do ClickHouse

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

Esta página foca a configuração base do componente: instalação, parâmetros principais, persistência, recursos e um cenário de alta disponibilidade como exemplo de partida.

Detalhes de segurança e integrações ficam nas páginas dedicadas:

O que é o ClickHouse?

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

Em vez de armazenar dados linha por linha, ele armazena coluna por coluna. Isso favorece leituras rápidas em cenários de agregação, relatórios e consultas analíticas sobre grandes volumes de dados.

No TDP Kubernetes, o ClickHouse é normalmente usado como destino de dados já processados, sendo depois consultado por ferramentas como Superset, CloudBeaver e Trino.

Para saber mais

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

Como o ClickHouse opera no Kubernetes

No TDP Kubernetes, o ClickHouse é implantado com o Altinity ClickHouse Operator, no mesmo espírito declarativo de outros operadores da plataforma (por analogia ao Kafka com Strimzi): em vez de criar manualmente Pods e Services, declara-se o estado desejado num recurso ClickHouseInstallation (CHI), e o operador reconcilia esse estado com o cluster.

Na prática, no namespace do release, os elementos típicos são:

Componente	Descrição
Altinity Operator	Gerencia o ciclo de vida do ClickHouseInstallation
ClickHouseInstallation	Recurso que define shards, réplicas, storage e configuração do cluster
Pods do ClickHouse	Pods de dados criados a partir do CHI
Services	Endpoints de acesso ao ClickHouse
PVCs	Volumes persistentes para os dados
Jobs opcionais	Recursos auxiliares para TDP user, S3 e cleanup

Pré-requisitos

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

Instalação (OCI)

Use o registry de produção:

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

Configuração

Todas as opções do chart ficam no values.yaml. Na prática, as chaves mais importantes para começar estão sob:

tdp-clickhouse.commonLabels
tdp-clickhouse.operator.*
tdp-clickhouse.clickhouse.*
tdp-clickhouse.cleanup.*
TDPConfigurations.s3Connection.* quando houver integração com S3

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` e `accessModes`	execute `helm show values`
`tdp-clickhouse.clickhouse.resources`	Requests e limits de CPU/memória	execute `helm show values`
`tdp-clickhouse.clickhouse.defaultUser.password`	Senha do usuário `default`	`""`
`tdp-clickhouse.clickhouse.extraUsers`	Perfis e usuários adicionais via XML	execute `helm show values`
`tdp-clickhouse.clickhouse.tdpUser.enabled`	Usuário TDP com job de grants	`false`
`tdp-clickhouse.operator.enabled`	Habilitar o Altinity Operator	`true`
`tdp-clickhouse.cleanup.enabled`	Habilitar job de cleanup pré-delete	`true`
`TDPConfigurations.s3Connection.*`	Integração opcional com bucket/Secret S3	desabilitado por padrão

Labels comuns

tdp-clickhouse.commonLabels permite aplicar labels adicionais aos recursos criados pelo chart. É útil quando o cluster usa convenções próprias de inventário, observabilidade ou governança.

Operador

O parâmetro tdp-clickhouse.operator.enabled controla a instalação do Altinity Operator como dependência do chart. Na maioria dos ambientes, o padrão true é suficiente.

ClickHouse: persistência e recursos

Os parâmetros abaixo costumam ser os primeiros ajustados por quem vai instalar o componente:

tdp-clickhouse:
  clickhouse:
    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""
      accessModes: ["ReadWriteOnce"]

    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

Atenção

Use o prefixo tdp-clickhouse.clickhouse.resources e tdp-clickhouse.clickhouse.persistence. Não use tdp-clickhouse.resources isolado.

Usuário TDP opcional

Quando tdp-clickhouse.clickhouse.tdpUser.enabled: true, o chart cria um Secret (tdp-clickhouse-tdp-user) e executa um Job pós-install/pós-upgrade para aplicar grants.

Isso é útil quando você quer evitar o uso do usuário default por aplicações do ecossistema TDP.

Alta disponibilidade (HA)

O chart suporta clusters ClickHouse com múltiplos shards e réplicas gerenciados pelo ClickHouse Keeper.

A topologia de referência apresentada abaixo é um exemplo de partida para ambientes com HA: 2 shards × 2 réplicas = 4 pods de dados.

Exemplo de partida

O exemplo de HA desta página não é obrigatório nem deve ser copiado cegamente para todos os ambientes. Use-o como base para adaptar recursos, storage, topologia e políticas de acesso à sua realidade.

Conceitos fundamentais

Conceito	O que faz	Quando usar
Shard	Divide os dados horizontalmente entre nós	Quando um único nó deixa de ser suficiente para o volume de dados
Réplica	Mantém uma cópia idêntica do shard	Quando é necessário tolerância a falhas e continuidade de leitura
ClickHouse Keeper	Coordena a replicação entre os pods	Obrigatório quando `replicasCount > 1`

Tabelas devem ser Replicated

Para aproveitar a replicação, as tabelas precisam ser criadas com engine ReplicatedMergeTree ou variante equivalente. Tabelas MergeTree simples não são replicadas automaticamente.

Topologia 2×2 (4 pods)

Shard 1 ──┬── Réplica 1  (pod: chi-<release>-tdp-clickhouse-0-0)
           └── Réplica 2  (pod: chi-<release>-tdp-clickhouse-0-1)

Shard 2 ──┬── Réplica 1  (pod: chi-<release>-tdp-clickhouse-1-0)
           └── Réplica 2  (pod: chi-<release>-tdp-clickhouse-1-1)

ClickHouse Keeper ── (pod: tdp-clickhouse-keeper-0)

Cada par de réplicas sincroniza dados via Keeper. A perda de um pod não interrompe o acesso ao shard correspondente, desde que a tabela esteja configurada com engine replicada.

Exemplo de `values-ha.yaml`

Crie um arquivo separado para HA, por exemplo values-ha.yaml, para não misturar esse cenário com os valores base do componente.

1. Topologia do cluster e recursos

tdp-clickhouse:
  clickhouse:
    antiAffinity: false   # mude para true se houver nós suficientes
    shardsCount: 2
    replicasCount: 2

    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""
      accessModes: ["ReadWriteOnce"]

    resources:
      requests:
        cpu: "1"
        memory: "512Mi"
      limits:
        cpu: "2"
        memory: "1Gi"

2. Configuração do cluster ClickHouse

    configuration:
      clusters:
        - name: tdp-clickhouse
          layout:
            shardsCount: 2
            replicasCount: 2

      zookeeper:
        nodes:
          - host: tdp-clickhouse-keeper-0.tdp-clickhouse-keeper-service.<namespace>.svc.cluster.local
            port: 2181
          # Se keeper.replicaCount=3, adicione os nós adicionais:
          # - host: tdp-clickhouse-keeper-1.tdp-clickhouse-keeper-service.<namespace>.svc.cluster.local
          #   port: 2181
          # - host: tdp-clickhouse-keeper-2.tdp-clickhouse-keeper-service.<namespace>.svc.cluster.local
          #   port: 2181

      settings:
        distributed_ddl:
          enable: true
        max_replicated_merges_in_queue: 16
        max_replicated_sends_in_queue: 16
        background_pool_size: 16
        background_schedule_pool_size: 16
        distributed_replica_error_cap: 0.1
        distributed_replica_error_half_life: 60

      macros:
        cluster: tdp-clickhouse
        shard: '{shard}'
        replica: '{replica}'

3. ClickHouse Keeper

  keeper:
    enabled: true
    replicaCount: 1   # use número ímpar: 1 ou 3

    image: registry.tecnisys.com.br/community/images/clickhouse/clickhouse-keeper
    tag: "25.8.11.66"

    localStorage:
      size: 5Gi
      storageClass: ""

    resources:
      requests:
        cpu: "1"
        memory: "1Gi"
      limits:
        cpu: "1"
        memory: "1Gi"

    settings:
      coordination:
        session_timeout_ms: 30000
        operation_timeout_ms: 10000
        heart_beat_interval_ms: 3000
      logging:
        level: INFO

    zoneSpread: false   # mude para true em clusters multi-zona

4. Senha do usuário default via Secret (opcional, mas recomendável)

Se for definir senha para o usuário default nesse cenário, use um Secret Kubernetes em vez de texto claro no arquivo de valores:

Terminal input

kubectl -n <namespace> create secret generic tdp-clickhouse-credentials \
  --from-literal=password='<senha-forte>'

tdp-clickhouse:
  clickhouse:
    configuration:
      users:
        default/password:
          valueFrom:
            secretKeyRef:
              name: tdp-clickhouse-credentials
              key: password

Para controle de acesso LDAP, allowExternalAccess, hostIP e boas práticas de credenciais, consulte Segurança — ClickHouse.

Aplicar a configuração HA

Terminal input
helm upgrade --install <release> \
  oci://registry.tecnisys.com.br/tdp/charts/tdp-clickhouse \
  -n <namespace> \
  -f values-ha.yaml

Verificação após o deploy

Após o deploy, devem aparecer os pods do ClickHouse, o recurso chi e, se ativado, o pod do Keeper:

Terminal input

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

Verifique se o ClickHouse reconhece o cluster e todos os nós:

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 cluster, shard_num, replica_num, host_name FROM system.clusters"

A saída esperada deve listar os hosts do cluster configurado. No exemplo 2×2, serão 4 hosts.

Parâmetros HA principais

Parâmetro	Descrição	Padrão
`tdp-clickhouse.clickhouse.shardsCount`	Número de shards	`1`
`tdp-clickhouse.clickhouse.replicasCount`	Réplicas por shard	`1`
`tdp-clickhouse.clickhouse.antiAffinity`	Distribuir pods em nós físicos diferentes	`false`
`tdp-clickhouse.keeper.enabled`	Ativar ClickHouse Keeper	`false`
`tdp-clickhouse.keeper.replicaCount`	Número de pods Keeper	`1`
`tdp-clickhouse.keeper.image`	Imagem do Keeper	`registry.tecnisys.com.br/community/images/clickhouse/clickhouse-keeper`
`tdp-clickhouse.keeper.localStorage.size`	Storage do Keeper	`5Gi`
`tdp-clickhouse.keeper.zoneSpread`	Distribuir Keeper em zonas	`false`

Integrações

Para bucket S3, Secret de conexão, política de storage S3 e consumo por outras ferramentas TDP, consulte Integrações — ClickHouse.

Segurança

Para autenticação LDAP, gestão de senhas, controle de acesso do usuário default e perfis adicionais, consulte Segurança — ClickHouse.

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 ou pelo release. Consulte kubectl get svc -n <namespace> para confirmar o nome.

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>

O que é o ClickHouse?​

Como o ClickHouse opera no Kubernetes​

Pré-requisitos​

Instalação (OCI)​

Configuração​

Parâmetros principais​

Labels comuns​

Operador​

ClickHouse: persistência e recursos​

Usuário TDP opcional​

Alta disponibilidade (HA)​

Conceitos fundamentais​

Topologia 2×2 (4 pods)​

Exemplo de values-ha.yaml​

Aplicar a configuração HA​

Verificação após o deploy​

Parâmetros HA principais​

Integrações​

Segurança​

Acesso​

Port-forward (HTTP)​

Solução de problemas​

Desinstalação​

O que é o ClickHouse?

Como o ClickHouse opera no Kubernetes

Pré-requisitos

Instalação (OCI)

Configuração

Parâmetros principais

Labels comuns

Operador

ClickHouse: persistência e recursos

Usuário TDP opcional

Alta disponibilidade (HA)

Conceitos fundamentais

Topologia 2×2 (4 pods)

Exemplo de `values-ha.yaml`

Aplicar a configuração HA

Verificação após o deploy

Parâmetros HA principais

Integrações

Segurança

Acesso

Port-forward (HTTP)

Solução de problemas

Desinstalação