Configuração do ClickHouse

ChartVersion3.0.1TypeapplicationAppVersion25.8.11.66

CompatibilidadeKubernetes1.32+OpenShift4.19+Rancher2.10.x+

Suporte a recursosLDAPsuportadoS3suportadoIngresssuportadoGateway APIsuportado

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.

Para instaladores e operadores, o fluxo típico é: garantir StorageClass e limites de recurso adequados, aplicar o chart com valores base, validar o ClickHouseInstallation (CHI) e os Services, e só então avançar para HA, LDAP ou integração S3 quando o ambiente exigir.

Para detalhes de segurança e integrações, veja Segurança — ClickHouse e Integrações — ClickHouse.

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

Estrutura de valores (Helm)

O chart tdp-clickhouse distribui a configuração nos blocos abaixo:

• tdp-clickhouse: — configuração principal do componente, incluindo clickhouse.*, operator.*, keeper.* e cleanup.*.
• TDP-Settings: — configurações TDP opcionais para integração S3 e controle de exposição via Ingress ou Gateway API.
• ingress: e gatewayApi: — parâmetros usados quando a exposição externa é habilitada.

tdp-clickhouse:
  clickhouse:
    enabled: true
  operator:
    enabled: true
  cleanup:
    enabled: true

TDP-Settings:
  s3Connection:
    enabled: false
  gateway:
    ingress:
      enabled: false
    gatewayApi:
      enabled: false

ingress:
  hosts:
    - host: clickhouse.tdp.local

gatewayApi:
  clickhouse:
    enabled: true

Visão geral

Propriedade	Valor
Chart	tdp-clickhouse
Versão do ClickHouse	25.8.11.66
Versão do chart	3.0.1
Operador	Altinity ClickHouse Operator
Recurso principal	ClickHouseInstallation
Persistência	PVCs para os dados do ClickHouse e, em HA, para o ClickHouse Keeper
Exposição HTTP	Service interno, Ingress ou Gateway API para a interface HTTP

Páginas relacionadas

• Integrações — ClickHouse — S3/Ozone, usuários TDP e integrações de consumo
• Segurança — ClickHouse — LDAP, Secrets, TLS e permissões
• Exposição externa: Ingress e Gateway API — exposição HTTP/HTTPS da interface

Pré-requisitos

• Kubernetes 1.32+, Red Hat OpenShift 4.19+ ou Rancher Manager 2.10.x+.
• Helm 3.2.0+.
• StorageClass padrão no cluster ou tdp-clickhouse.clickhouse.persistence.storageClass definido explicitamente.

Instalação

Instalação (OCI)

O helm upgrade --install é idempotente: na primeira execução cria o release; nas seguintes aplica apenas o diff de valores. Use sempre o registry de produção indicado e um arquivo de valores versionado (sem credenciais em texto claro) para reproduzir o mesmo comportamento entre ambientes.

Use o registry de produção:

Terminal input

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

Parâmetros principais

Parâmetros principais

Parâmetro	Descrição	Padrão (referência)
tdp-clickhouse.clickhouse.enabled	Habilitar cluster	true
tdp-clickhouse.clickhouse.image.repository	Repositório da imagem do ClickHouse	clickhouse/clickhouse-server
tdp-clickhouse.clickhouse.image.tag	Tag da imagem do ClickHouse	25.8.11.66
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.clickhouse.tdpUser.password	Senha do usuário TDP (definir via values override privado quando necessário)	""
tdp-clickhouse.operator.enabled	Habilitar o Altinity Operator	true
tdp-clickhouse.cleanup.enabled	Habilitar job de cleanup pré-delete	true
TDP-Settings.s3Connection.enabled	Habilitar job de criação de bucket e Secret S3	false
TDP-Settings.s3Connection.bucket	Nome do bucket S3	""
TDP-Settings.s3Connection.accessKey	Chave de acesso S3	""
TDP-Settings.s3Connection.secretKey	Chave secreta S3	""
TDP-Settings.s3Connection.uri	URI do endpoint S3	""
TDP-Settings.s3Connection.selfSigned	Ignorar verificação TLS para endpoints autoassinados	false

Detalhes de configuraçã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.

Desabilitar o operador só faz sentido quando você já possui uma instalação do Altinity no cluster compatível com o chart e deseja reutilizá-la — caso contrário, o CHI não será reconciliado e os pods de ClickHouse não aparecerão como esperado. Em dúvida, mantenha true e trate o operador como pré-requisito implícito da stack TDP.

Logging

O chart substitui o arquivo de configuração de logging do ClickHouse via tdp-clickhouse.operator.configs.configdFiles.01-clickhouse-02-logger.xml.

Nível de log

Use sempre <level>information</level> — não <level>info</level>. O valor info não é reconhecido pelo ClickHouse/Poco e pode causar comportamento inesperado no logging.

ClickHouse: persistência e recursos

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

Persistência em PVC significa que dados e estado sobrevivem ao reinício do pod; sem ela (ou com tamanho subdimensionado), você arrisca falta de espaço, throttling de disco ou perda de dados em recriações. Requests e limits de CPU/memória definem quanto o scheduler reserva e até onde o pod pode crescer: valores baixos economizam cluster mas podem causar OOM ou consultas lentas sob carga — alinhe ao volume de dados e ao padrão de consultas (analytics costuma exigir mais memória).

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.

StorageClass Portworx

Quando o cluster usa Portworx para volumes de banco de dados, ajuste tdp-clickhouse.clickhouse.persistence.storageClass e as annotations de volume conforme o padrão operacional do cluster:

tdp-clickhouse:
  clickhouse:
    persistence:
      enabled: true
      size: 10Gi
      storageClass: "px-db"
      accessModes: ["ReadWriteOnce"]
      annotations:
        portworx.io/repl: "3"
        portworx.io/io_priority: "high"
        portworx.io/snapshot: "true"
        portworx.io/block_size: "64"

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.

O usuário default continua existindo para cenários legados ou administrativos; habilitar o usuário TDP centraliza permissões e convenção de nome para ferramentas que se conectam ao ClickHouse no TDP (por exemplo Superset ou CloudBeaver quando configurados para tdpuser), reduzindo a necessidade de compartilhar a conta administrativa padrão.

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.

Ao adaptar o exemplo, ajuste em conjunto shards, réplicas, tamanho de PVC por pod, antiAffinity (se há nós suficientes para dispersão) e keeper.replicaCount (quórum ímpar, 1 ou 3).

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_NAME>-tdp-clickhouse-0-0)
           └── Réplica 2  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-0-1)

Shard 2 ──┬── Réplica 1  (pod: chi-<RELEASE_NAME>-tdp-clickhouse-1-0)
           └── Réplica 2  (pod: chi-<RELEASE_NAME>-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: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

2. Configuração do cluster ClickHouse

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

      settings:
        distributed_ddl:
          enable: true

      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: ""

Para definir senha do usuário default, controle de acesso LDAP e boas práticas de credenciais, consulte Segurança — ClickHouse.

Aplicar a configuração HA

Terminal input

helm upgrade --install <RELEASE_NAME> \
  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=<RELEASE_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

Integrações

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

Acesso & Segurança

Segurança

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

Exposição externa (Ingress e Gateway API)

Configuração obrigatória antes de expor o ClickHouse externamente

Por padrão, o ClickHouse só aceita conexões de 127.0.0.1/::1. Requisições de um controlador Ingress ou Gateway são rejeitadas com AUTHENTICATION_FAILED.

Antes de habilitar Ingress ou Gateway API, certifique-se de incluir extraUsers com permissão de rede aberta — os exemplos completos estão em Exposição externa: Ingress e Gateway API.

Para configuração detalhada de Ingress e Gateway API, consulte Exposição externa: Ingress e Gateway API.

Acesso

Port-forward (HTTP)

Terminal input

kubectl -n <NAMESPACE> port-forward svc/clickhouse-<RELEASE_NAME> 8123:8123
curl "http://localhost:8123/?query=SELECT%201"

clickhouse-<RELEASE_NAME> é o Service HTTP do ClickHouse. Confirme com kubectl get svc -n <NAMESPACE>.

Solução de problemas

Solução de problemas

Terminal input

kubectl -n <NAMESPACE> get pods
kubectl -n <NAMESPACE> get chi
kubectl -n <NAMESPACE> logs deployment/<DEPLOYMENT_NAME>
kubectl -n <NAMESPACE> logs -l clickhouse.altinity.com/chi=<RELEASE_NAME>

Desinstalação

Desinstalação

Terminal input

helm -n <NAMESPACE> uninstall <RELEASE_NAME>

Cleanup pré-delete

Quando tdp-clickhouse.cleanup.enabled: true, o chart habilita um Job de cleanup executado antes da remoção do release. Esse Job remove o ClickHouseInstallation e executa limpeza de órfãos para StatefulSets, Pods e Services relacionados ao CHI.

Os PVCs são preservados por padrão. O cleanup também não remove diretamente o Deployment do Altinity Operator.