Introdução ao ClickHouse Operator

Este documento apresenta uma visão geral dos principais conceitos e padrões de uso do ClickHouse Operator.

O que é o ClickHouse Operator

O ClickHouse Operator é um operador do Kubernetes que automatiza a implantação e o gerenciamento de clusters do ClickHouse no Kubernetes. Desenvolvido com base no padrão de operador, ele estende a API do Kubernetes com recursos personalizados que representam clusters do ClickHouse e suas dependências. O operador é responsável por:

Gerenciamento do ciclo de vida do cluster (criação, atualizações, escalonamento, exclusão)
Coordenação do cluster ClickHouse Keeper
Geração automática de configuração
Sincronização do esquema do banco de dados
Atualizações progressivas e de versão
Provisionamento de armazenamento

Recursos personalizados

O operador fornece duas definições principais de recursos personalizados (CRDs):

ClickHouseCluster

Representa um cluster de banco de dados do ClickHouse com réplicas e shards configuráveis.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

KeeperCluster

Representa um cluster do ClickHouse Keeper para coordenação distribuída (substituto do ZooKeeper).

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

Coordenação

O ClickHouse Keeper é obrigatório

Cada ClickHouseCluster exige um cluster do ClickHouse Keeper para coordenação distribuída. O cluster Keeper deve ser referenciado na especificação do ClickHouseCluster usando keeperClusterRef. Por padrão, o operador procura no espaço de nomes do ClickHouseCluster, mas você também pode definir keeperClusterRef.namespace para apontar para um KeeperCluster em outro espaço de nomes monitorado.

Relação um para um com o Keeper

Cada ClickHouseCluster deve ter seu próprio KeeperCluster dedicado. Não é possível compartilhar um único KeeperCluster entre vários ClickHouseClusters. Por quê? O operador gera automaticamente uma chave de authentication exclusiva para cada ClickHouseCluster acessar seu Keeper. Essa chave é armazenada em um Secret e não pode ser compartilhada. Consequências:

Vários ClickHouseClusters não podem apontar para o mesmo KeeperCluster
Recriar um ClickHouseCluster exige recriar também seu KeeperCluster

Volumes persistentes não são excluídos automaticamente quando os recursos ClickHouseCluster ou KeeperCluster são excluídos.

Ao recriar um cluster:

Exclua o recurso ClickHouseCluster
Exclua o recurso KeeperCluster
Aguarde até que todos os pods sejam encerrados
Opcionalmente, exclua os PersistentVolumeClaims se quiser começar do zero
Recrie o KeeperCluster e o ClickHouseCluster juntos

Para evitar erros de authentication, exclua manualmente os volumes persistentes ou recrie ambos os clusters juntos com armazenamento novo.

Replicação do esquema

O ClickHouse Operator replica automaticamente as definições do banco de dados em todas as réplicas de um cluster.

O que é replicado

O operador sincroniza:

definições de bancos de dados Replicated
motores de banco de dados de integração (PostgreSQL, MySQL etc.)

O operador não sincroniza:

bancos de dados não replicados (Atomic, Ordinary etc.)
tabelas locais em bancos de dados não replicados
dados das tabelas (tratados pela replicação do ClickHouse)

Recomendado: use o motor de banco de dados Replicated

Prática recomendadaSempre use o motor de banco de dados Replicated em implantações de produção.

Benefícios:

Replicação automática do esquema em todos os nós
Gerenciamento simplificado de tabelas
O operador pode se sincronizar com novas réplicas
Esquema consistente em todo o cluster

Crie bancos de dados com DDL distribuído:

CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

Evite motores que não sejam Replicated

Os motores de banco de dados não replicados (Atomic, Lazy, SQLite, Ordinary) exigem gerenciamento manual do esquema:

As tabelas devem ser criadas individualmente em cada réplica
Pode haver divergência de esquema entre os nós
O operador não consegue sincronizar automaticamente novas réplicas

Desativar a replicação de esquema

Para desativar a replicação automática de esquema, defina spec.settings.enableDatabaseSync como false no recurso do ClickHouseCluster.

Gerenciamento de armazenamento

O operador gerencia o armazenamento usando PersistentVolumeClaims (PVCs) do Kubernetes.

Configuração do volume de dados

Especifique os requisitos de armazenamento em dataVolumeClaimSpec:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi

Ciclo de vida do armazenamento

Criação: PVCs são criados automaticamente com o cluster
Expansão: compatível se a StorageClass permitir a expansão de volume
Retenção: PVCs não são excluídos automaticamente quando o cluster é excluído
Reutilização: PVCs existentes podem ser reutilizados se o cluster for recriado com o mesmo nome

Para remover completamente o armazenamento:

# Delete cluster
kubectl delete clickhousecluster my-cluster

# Wait for pods to terminate
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse

# Delete PVCs
kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse

Destaques da configuração padrão

Cluster pré-configurado: cluster chamado ‘default’ que contém todos os nós do ClickHouse.
Macros padrão: algumas macros úteis são predefinidas:
- {cluster}: nome do cluster (default)
- {shard}: número do shard
- {replica}: número da réplica
Armazenamento replicado para entidades de RBAC
Armazenamento replicado para User Defined Functions (UDF)

Próximas etapas

Guia de configuração - Opções detalhadas de configuração
Referência da API - Documentação completa da API

Instalação

Guias

Referência

O que é o ClickHouse Operator

Recursos personalizados

ClickHouseCluster

KeeperCluster

Coordenação

O ClickHouse Keeper é obrigatório

Relação um para um com o Keeper

Replicação do esquema

O que é replicado

Recomendado: use o motor de banco de dados Replicated

Evite motores que não sejam Replicated

Desativar a replicação de esquema

Gerenciamento de armazenamento

Configuração do volume de dados

Ciclo de vida do armazenamento

Destaques da configuração padrão

Próximas etapas

​O que é o ClickHouse Operator

​Recursos personalizados

​ClickHouseCluster

​KeeperCluster

​Coordenação

​O ClickHouse Keeper é obrigatório

​Relação um para um com o Keeper

​Replicação do esquema

​O que é replicado

​Recomendado: use o motor de banco de dados Replicated

​Evite motores que não sejam Replicated

​Desativar a replicação de esquema

​Gerenciamento de armazenamento

​Configuração do volume de dados

​Ciclo de vida do armazenamento

​Destaques da configuração padrão

​Próximas etapas

O que é o ClickHouse Operator

Recursos personalizados

ClickHouseCluster

KeeperCluster

Coordenação

O ClickHouse Keeper é obrigatório

Relação um para um com o Keeper

Replicação do esquema

O que é replicado

Recomendado: use o motor de banco de dados Replicated

Evite motores que não sejam Replicated

Desativar a replicação de esquema

Gerenciamento de armazenamento

Configuração do volume de dados

Ciclo de vida do armazenamento

Destaques da configuração padrão

Próximas etapas