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. Referencie um KeeperCluster gerenciado pelo operador 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. Para usar um ensemble do Keeper que não seja gerenciado pelo operador, liste os servidores dele em externalKeeper. Consulte Keeper gerenciado externamente.

Relação um para um com o Keeper

Por padrão, cada ClickHouseCluster precisa de seu próprio KeeperCluster dedicado. Por quê? O operador gera automaticamente uma chave de authentication exclusiva para cada ClickHouseCluster acessar seu Keeper. Essa chave é armazenada em um Secret. Consequências:

Vários ClickHouseClusters não podem apontar para o mesmo KeeperCluster sem a configuração descrita abaixo
Recriar um ClickHouseCluster exige recriar também seu KeeperCluster

Para compartilhar um único cluster do Keeper, defina um zookeeper.root distinto em settings.extraConfig para cada ClickHouseCluster e crie esse znode antes de o ClickHouse iniciar. Consulte Keeper gerenciado externamente.

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

Instalar

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