Guia de configuração do ClickHouse Operator

Este guia explica como configurar clusters do ClickHouse e do Keeper usando o operador.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # Número de réplicas por shard
  shards: 2             # Número de shards
  keeperClusterRef:
    name: my-keeper     # Referência ao KeeperCluster
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

• Réplicas: Número de instâncias do ClickHouse em cada shard (para alta disponibilidade)
• Shards: Número de partições horizontais (para escalabilidade)

spec:
  replicas: 3  # Padrão: 3
  shards: 2    # Padrão: 1

Um cluster com replicas: 3 e shards: 2 criará 6 pods do ClickHouse ao todo.

Todo cluster do ClickHouse deve fazer referência a um KeeperCluster para coordenação:

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # Opcional, o padrão é o espaço de nomes do ClickHouseCluster

Quando keeperClusterRef.namespace estiver definido, o operador deverá monitorar ambos os espaços de nomes. Se WATCH_NAMESPACE estiver configurado, inclua os espaços de nomes do ClickHouse e do Keeper nessa lista.

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # Deve ser ímpar: 1, 3, 5, 7, 9, 11, 13 ou 15
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 5Gi

Configure o armazenamento persistente com dataVolumeClaimSpec, um PersistentVolumeClaimSpec padrão do Kubernetes. O operador o transforma em um PersistentVolumeClaim por réplica, montado no caminho de dados /var/lib/clickhouse:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    resources:
      requests:
        storage: 100Gi

A anexação de discos extras em um layout com vários discos (JBOD), a execução sem um volume persistente, a expansão de capacidade, políticas de armazenamento personalizadas, criptografia em repouso e as regras sobre o que não pode ser alterado após a criação são abordadas no guia dedicado de armazenamento e volumes.

spec.clusterDomain define o sufixo DNS do Kubernetes que o operador usa ao construir os nomes de host totalmente qualificados dos pods do Kubernetes que ele grava na configuração do servidor ClickHouse. O padrão é cluster.local e esse campo existe tanto em ClickHouseCluster quanto em KeeperCluster.

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

Para as réplicas do ClickHouse, o operador cria um headless Service de controle, <cluster-name>-clickhouse-headless, que atende ao tráfego de clientes. Além disso, cria serviços por réplica, <cluster-name>-clickhouse-internal-<shard>-<index>, que publicam pods não prontos para tráfego interno e solicitações de gerenciamento do operador. Isso pode ser usado para a recuperação de réplicas caso elas não consigam ficar prontas por conta própria.

Os nós do Keeper usam nomes de pod por meio de seu headless Service: <pod>.<headless-service>.<namespace>.svc.<clusterDomain>.

Distribua os pods entre zonas de disponibilidade:

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname

É possível especificar regras arbitrárias de afinidade/anti-afinidade entre pods do Kubernetes e restrições de distribuição de topologia.

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

O operador cria um PodDisruptionBudget (PDB) para cada cluster, para que interrupções voluntárias — drenagens de nós, atualizações graduais e evicções do autoscaler — não possam derrubar pods suficientes a ponto de causar perda de quórum ou comprometer a disponibilidade.

Para clusters do ClickHouse com mais de um shard, é criado um PDB por shard para que uma interrupção em um shard não seja contabilizada contra outro.

O operador escolhe valores padrão seguros com base no tamanho do cluster para que um novo apply já proteja contra perda acidental de quórum.

Para um ClickHouseCluster com 3 shards e replicas: 3, o operador cria três PDBs, um por shard, cada um com minAvailable: 1.

Use spec.podDisruptionBudget para substituir minAvailable ou maxUnavailable (exatamente um):

spec:
  replicas: 3
  shards: 2
  podDisruptionBudget:
    minAvailable: 2   # mantém pelo menos 2 das 3 réplicas em cada shard ativas durante uma interrupção

Ou no formato maxUnavailable, com uma porcentagem:

spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%

Você também pode passar o campo unhealthyPodEvictionPolicy para o PDB gerado — útil quando precisar permitir a evicção de pods que ainda estão em NotReady:

spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow

spec.podDisruptionBudget.policy permite escolher com que nível de rigor o operador gerencia os PDBs:

Exemplo — desative completamente o gerenciamento de PDBs em um cluster de desenvolvimento:

spec:
  podDisruptionBudget:
    policy: Disabled

Exemplo — mantenha seu PDB criado manualmente junto ao cluster e impeça que o operador interfira nele:

spec:
  podDisruptionBudget:
    policy: Ignored

O gerenciamento de PDB também pode ser desativado em nível de cluster por meio da variável de ambiente ENABLE_PDB do operator. Com ENABLE_PDB=false, o operator ignora a etapa de reconciliação de PDB para todos os ClickHouseCluster e KeeperCluster, independentemente de spec.podDisruptionBudget.policy, e não monitora recursos PodDisruptionBudget de forma alguma. Portanto, o ServiceAccount do operator não precisa de permissões de RBAC em poddisruptionbudgets.policy/v1, o que é útil ao executar o operator com um ServiceAccount restrito que omite essas permissões intencionalmente.

# na spec de Implantação do operador
env:
- name: ENABLE_PDB
  value: "false"

Isto se destina a ambientes que implementam suas próprias políticas de interrupção (por exemplo, por meio do Gatekeeper / Kyverno) e querem deixar o operator totalmente fora desse processo.

Use uma imagem específica do ClickHouse:

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

Configure CPU e memória para os contêineres do ClickHouse:

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

Adicione variáveis de ambiente personalizadas:

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

Adicione montagens adicionais de volumes:

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml

Passe uma referência a um Secret do Kubernetes que contenha certificados TLS para ativar endpoints seguros

spec:
  settings:
    tls:
      enabled: true
      required: true # Portas inseguras são desativadas se definido
      serverCertSecret:
        name: <certificate-secret-name>

Espera-se que o Secret contenha o par de chaves do servidor:

• tls.crt - certificado do servidor codificado em PEM
• tls.key - chave privada codificada em PEM

Se o KeeperCluster tiver TLS habilitado, o ClickHouseCluster usará automaticamente uma conexão segura com os nós do Keeper.

O ClickHouseCluster verifica os certificados dos nós do Keeper usando o repositório de confiança do sistema, além de qualquer caBundle que você configurar.

Para confiar em uma CA privada (por exemplo, uma CA autoassinada ou interna), forneça uma referência para um bundle de CA personalizado:

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

Por padrão, o operador cria e controla um Secret que contém as credenciais internas do cluster (senha entre servidores, senha de gerenciamento, identidade do Keeper, Secret do cluster, chave de named-collections). O Secret recebe o nome do cluster e fica no espaço de nomes do cluster.

Se você quiser gerenciar essas credenciais por conta própria — por exemplo, obtendo-as do HashiCorp Vault, AWS Secrets Manager ou External Secrets Operator — aponte o operador para um Secret pré-existente usando spec.externalSecret:

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
  externalSecret:
    name: my-clickhouse-credentials
    policy: Observe

O Secret deve conter as seguintes chaves:

Um Secret completo fica assim:

apiVersion: v1
kind: Secret
metadata:
  name: my-clickhouse-credentials
  namespace: sample
type: Opaque
stringData:
  interserver-password: "a-strong-random-password"
  management-password: "another-strong-password"
  keeper-identity: "clickhouse:keeper-auth-password"
  cluster-secret: "cluster-internal-secret"
  named-collections-key: "0123456789abcdef0123456789abcdef"   # 32 hex chars = 16 bytes
  disk-encryption-key: "00112233445566778899aabbccddeeff"     # only when settings.encryption is set

spec.externalSecret.policy controla como o operador lida com chaves obrigatórias ausentes:

Escolha Observe quando um sistema externo (Vault, ESO, sealed-secrets, GitOps) for a fonte de verdade e você quiser que o operador falhe claramente em caso de configuração incorreta. Escolha Manage quando quiser um bootstrap autossuficiente, mas ainda quiser manter a propriedade do próprio objeto Secret (por exemplo, para fazer backup dele).

O operador expõe a condição ExternalSecretValid em ClickHouseCluster.status.conditions. Verifique-a quando a reconciliação parecer travada:

# Plain kubectl — works out of the box
kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p'

# Same data as YAML
kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

# Pretty-printed JSON (requires jq)
kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq

Possíveis motivos:

O operador coloca a reconciliação de volta na fila enquanto o Secret é inválido, então, assim que você adicionar as chaves ausentes, a próxima reconciliação as detectará automaticamente — não é necessário reiniciar os pods.

O operador expõe um conjunto fixo de portas em cada pod do Kubernetes do ClickHouse e em seu Service headless público: 8123 HTTP, 9000 nativo, 9009 interserver, 9001/9002 gerenciamento, 9363 métricas do Prometheus e as variantes TLS 8443/9440 quando o TLS estiver habilitado. As portas interserver e de gerenciamento também são expostas por meio dos Services internos de cada réplica para que as réplicas e o operador possam se comunicar antes que uma réplica fique pronta. Para fazer o ClickHouse aceitar conexões em protocolos adicionais — MySQL, PostgreSQL, gRPC ou qualquer porta personalizada — declare-as em spec.additionalPorts:

spec:
  additionalPorts:
    - name: mysql
      port: 9004
    - name: postgres
      port: 9005
    - name: grpc
      port: 9100

O operador adiciona essas portas às containerPorts do pod do Kubernetes e ao Service headless público. O exemplo completo está em examples/custom_protocols.yaml.

Para expor o ClickHouse pelo MySQL wire protocol na porta 9004:

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 1
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 2Gi

  # 1) Open the port on the Pod and the public headless Service.
  additionalPorts:
    - name: mysql
      port: 9004

  # 2) Tell ClickHouse server to actually listen on it.
  settings:
    extraConfig:
      protocols:
        mysql:
          type: mysql
          port: 9004
          description: "MySQL wire protocol"

Depois de aplicar, verifique de dentro do cluster:

kubectl exec sample-clickhouse-0-0-0 -- \
  clickhouse-client --port 9004 --query "SELECT 1"

O webhook de validação rejeita entradas de additionalPorts que entrariam em conflito com portas usadas pelo próprio operator. Todas as portas relacionadas a TLS são reservadas incondicionalmente para que habilitar spec.settings.tls.enabled mais tarde não possa invalidar um cluster que antes era válido.

Os nomes a seguir também são rejeitados — eles são os identificadores internos do operator para tipos de protocolo (não os aliases legíveis por pessoas):

Uma solicitação rejeitada gera um erro como:

spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port
spec.additionalPorts[0].name: "http" is reserved by the operator

O operador faz duas coisas independentes com as versões do cluster:

1. Relatório de versão — para ClickHouseCluster, um Job do Kubernetes executa a imagem de contêiner uma vez para detectar a versão do ClickHouse em execução; para KeeperCluster, o operador lê a versão informada pelo servidor a partir das réplicas em execução. A versão detectada é registrada em .status.version e usada por outras etapas de reconciliação (por exemplo, a chave de named-collections do Secret externo só é exigida a partir do ClickHouse 25.12).
2. Canal de upgrade — uma verificação periódica no feed público de lançamentos do ClickHouse (https://clickhouse.com/data/version_date.tsv). O operador informa se há uma versão mais recente disponível por meio da condição de status VersionUpgraded. Ele nunca faz upgrade do cluster por conta própria — o usuário controla a tag da imagem.

spec.upgradeChannel seleciona com qual conjunto de lançamentos upstream o operador faz a comparação. O mesmo campo existe tanto em ClickHouseCluster quanto em KeeperCluster.

spec:
  upgradeChannel: lts   # or "stable", or "25.8", or omitted

Valores permitidos (validados pelo CRD com o padrão ^(lts|stable|\d+\.\d+)?$):

Para produção, em geral é preferível fixar o canal em um <major>.<minor> explícito (por exemplo, 25.8). Isso mantém o cluster na linha de lançamento principal pretendida e permite que o operador exiba um aviso WrongReleaseChannel se alguma réplica, por algum motivo, acabar em uma major diferente — o que é especialmente importante quando a imagem é referenciada por um digest (@sha256:...) em vez de por uma tag legível por humanos. O padrão vazio é adequado para clusters de desenvolvimento em que saltos de versão principal não são uma preocupação.

Duas condições mostram o resultado da sonda e da verificação de atualização:

Inspecione-as com:

kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

Isso se aplica somente a ClickHouseCluster. KeeperCluster não executa mais um Job de sonda de versão — sua versão é lida diretamente das réplicas em execução do Keeper — portanto, spec.versionProbeTemplate está obsoleto e não tem efeito nesse caso.

A sonda é implementada como um Job padrão do Kubernetes. Se o seu cluster tiver políticas de admissão que exijam Tolerations específicas, seletores de nó, contextos de segurança ou se você quiser limitar por quanto tempo os Jobs de sonda concluídos permanecem, sobrescreva o template por meio de spec.versionProbeTemplate:

spec:
  versionProbeTemplate:
    spec:
      ttlSecondsAfterFinished: 600   # delete completed probe Jobs 10 minutes after completion
      template:
        spec:
          nodeSelector:
            kubernetes.io/arch: amd64
          tolerations:
            - key: dedicated
              operator: Equal
              value: clickhouse
              effect: NoSchedule
          containers:
            - name: version-probe
              resources:
                requests:
                  cpu: 50m
                  memory: 64Mi

O nome do contêiner version-probe é o nome padrão usado pelo operador — a entrada em containers: corresponde a ele pelo nome, então o operador faz um merge profundo dos campos fornecidos pelo usuário sobre os valores padrão.

Duas flags no gerenciador do operador controlam globalmente o loop de verificação de upgrade:

Defina --disable-version-update-checks=true em ambientes isolados da internet ou quando a saída para clickhouse.com não for permitida.

spec.settings.defaultUserPassword define a senha do usuário default integrado. Forneça o valor de uma chave em um Secret (recomendado) ou em um ConfigMap que você criar, em vez de inseri-lo diretamente no CR:

spec:
  settings:
    defaultUserPassword:
      passwordType: password   # default; see "Password types" below
      secret:                  # exactly one of secret or configMap
        name: clickhouse-password   # name of the Secret/ConfigMap
        key: password               # the key inside it, not the password value

Forneça exatamente um entre secret e configMap, cada opção com name (o objeto) e key (a entrada que contém a senha).

passwordType informa ao ClickHouse como interpretar o valor. O padrão é password (texto simples); as alternativas são formas com hash, como password_sha256_hex e password_double_sha1_hex. Prefira um tipo com hash para que a senha em texto simples nunca seja armazenada. Consulte as configurações do usuário do ClickHouse para ver a lista completa.

Crie o Secret e, em seguida, faça referência à sua chave:

kubectl create secret generic clickhouse-password \
  --from-literal=password='your-secure-password'

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  settings:
    defaultUserPassword:
      passwordType: password
      secret:
        name: clickhouse-password
        key: password

Para uma senha com hash, armazene o hash em vez da senha em texto simples:

echo -n 'your-secure-password' | sha256sum   # use the hex digest as the value
kubectl create secret generic clickhouse-password \
  --from-literal=password='<sha256-hex-digest>'

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      secret:
        name: clickhouse-password
        key: password

Um ConfigMap funciona da mesma forma, mas seu conteúdo não é protegido como o de um Secret. Use-o apenas para valores não sensíveis ou já hasheados, como um digest password_sha256_hex:

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

Configure usuários adicionais em arquivos de configuração.

Crie um ConfigMap e um Secret para o usuário:

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          query:
            - "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

Adicione uma configuração personalizada ao ClickHouseCluster:

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

Ative a sincronização automática do banco de dados para novas réplicas:

spec:
  settings:
    enableDatabaseSync: true  # Default: true

Quando ativado, o operador sincroniza as tabelas Replicated e de integração para novas réplicas.

Cada pod do Kubernetes de réplica tem a gate de readiness clickhouse.com/ReplicaInitialized; portanto, uma nova réplica é publicada pelo Service headless público somente depois que o operador conclui sua inicialização: o banco de dados default é convertido para o engine Replicated e o schema é sincronizado. Até então, o operador e as outras réplicas a acessam por meio de seu Service interno. Com enableDatabaseSync: false, o operador marca as réplicas como inicializadas imediatamente; portanto, a readiness depende apenas das probes do contêiner.

O operador nunca exclui um banco de dados default não Replicated que contém dados. Essa réplica ainda começa a atender ao tráfego de clientes após a preparação do schema, mas o cluster informa SchemaInSync=False com o motivo DefaultDatabaseNotReplicated até que você resolva esse banco de dados por conta própria.

Antes de remover uma réplica durante a redução de escala, o operador primeiro remove o tráfego de clientes dela, aguarda até que ela deixe de ser publicada, replica os dados restantes para as réplicas sobreviventes e só então a exclui.

Configure o log do servidor ClickHouse por meio de spec.settings.logger. Todos os campos são opcionais e têm um padrão seguro, então mesmo um cluster sem nenhuma alteração já registra em trace tanto no console do contêiner quanto em um arquivo em disco com rotação.

spec:
  settings:
    logger:
      logToFile: true   # Default: true. Set false to log only to the console
      jsonLogs: false   # Default: false. Set true for structured JSON log lines
      level: trace      # Default: trace
      size: 1000M       # Default: 1000M. Rotate a log file once it reaches this size
      count: 50         # Default: 50. Number of rotated files to keep

O operador sempre mantém o log no console ativado para que kubectl logs funcione, e também adiciona o log em arquivo quando logToFile é true. Um cluster com os valores padrão gera este bloco logger:

logger:
  console: true
  level: trace
  log: /var/log/clickhouse-server/clickhouse-server.log
  errorlog: /var/log/clickhouse-server/clickhouse-server.err.log
  size: 1000M
  count: 50

O mesmo bloco spec.settings.logger também se aplica a um KeeperCluster; nesse caso, o operador grava seus arquivos em /var/log/clickhouse-keeper/.

Em vez de montar arquivos de configuração personalizados, você pode especificar diretamente opções adicionais de configuração do ClickHouse.

Adicione uma configuração personalizada do ClickHouse usando extraConfig:

spec:
  settings:
    extraConfig:
      background_pool_size: 20

• Exemplos de configuração em YAML
• Todas as configurações do servidor

Você também pode especificar uma configuração adicional de usuários do ClickHouse usando extraUsersConfig. Isso é útil para definir usuários, perfis, quotas e permissões diretamente na especificação do cluster.

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100

Exemplo completo de configuração:

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # senha-secreta
  password: "..." # sha256 hex da senha
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password