Armazenamento e volumes

Este guia explica como o operador provisiona armazenamento persistente para um ClickHouseCluster: o volume de dados principal, a adição de discos extras em uma configuração com vários discos (JBOD), a expansão de capacidade e as regras que determinam o que você pode e não pode alterar depois que um cluster já existe.

Para a referência campo a campo, consulte Configuração → Configuração de armazenamento e a Referência da API.

spec.dataVolumeClaimSpec é um PersistentVolumeClaimSpec padrão do Kubernetes. O operador o converte em um volumeClaimTemplate do StatefulSet, para que o controlador do StatefulSet crie e mantenha um PersistentVolumeClaim por réplica e o monte no caminho de dados do ClickHouse /var/lib/clickhouse.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd   # optional; depends on the installed CSI driver
    resources:
      requests:
        storage: 100Gi

• Quando accessModes é omitido, o operador usa ReadWriteOnce por padrão.
• O PVC por réplica é mantido quando o cluster é excluído, então os dados sobrevivem à exclusão e recriação do recurso personalizado. Para dados em uma política criptografada, isso também exige preservar a chave de criptografia — veja a observação nessa seção.
• O mesmo campo existe em KeeperCluster e se comporta da mesma forma.

dataVolumeClaimSpec é opcional. Se você o omitir e não montar seu próprio volume no caminho dos dados, o ClickHouse gravará no filesystem efêmero do contêiner, e o webhook de admissão retornará um aviso de que os dados poderão ser perdidos se o cluster for reiniciado.

Isso se destina apenas a clusters descartáveis ou de teste. Para fornecer seu próprio armazenamento em vez de dataVolumeClaimSpec — por exemplo, um emptyDir ou um volume pré-provisionado — defina-o por meio de spec.podTemplate.volumes e monte-o em /var/lib/clickhouse com spec.containerTemplate.volumeMounts.

Para aumentar um volume, aumente resources.requests.storage e aplique a alteração. O operador atualiza os PVCs existentes no local.

spec:
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 200Gi   # was 100Gi

spec.additionalVolumeClaimTemplates adiciona discos extras a cada réplica do ClickHouse, além do dataVolumeClaimSpec principal. Cada entrada é um template de PVC com nome — um metadata.name mais uma spec de PVC — reconciliado exatamente como o disco de dados principal, para que o controlador do StatefulSet crie e retenha um PVC por réplica com o nome <name>-<statefulset>-0.

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 100Gi
  additionalVolumeClaimTemplates:
    - metadata:
        name: disk1
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi
    - metadata:
        name: disk2
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi

O operador monta cada volume adicional em /var/lib/clickhouse/disks/<name> e gera a storage_configuration do ClickHouse para você — você não precisa escrevê-la manualmente. Ele registra cada disco adicional e o adiciona à storage policy default integrada.

O disco de dados primary (default) e cada disco adicional compartilham um único volume da policy default, portanto o ClickHouse distribui novas partes de dados entre todos eles em esquema round-robin. A capacidade utilizável é a soma de todos os discos, e toda tabela que não define sua própria storage_policy — incluindo as tabelas system.* — usa o conjunto combinado.

Você não precisa de extraConfig para o layout JBOD acima — o operador gera a política default automaticamente. Use spec.settings.extraConfig apenas quando quiser políticas de armazenamento além da padrão gerada, por exemplo, uma política em camadas hot/cold com move_factor e prefer_not_to_merge, ou um disco baseado em S3. A configuração adicionada ali é mesclada à storage_configuration gerada.

Consulte a documentação de armazenamento do ClickHouse para ver os campos da política.

A configuração spec.settings.encryption habilita a criptografia em repouso dos dados da tabela. O operador gera uma chave AES de 16 bytes — armazenada no Secret do cluster gerenciado ou fornecida por meio de externalSecret — e uma política de armazenamento dedicada que reveste cada disco de dados com o tipo de disco encrypted do ClickHouse.

spec:
  settings:
    encryption: {}   # enables the feature; the policy defaults to "encrypted"

A criptografia é opcional por tabela; a política de armazenamento padrão continua sem criptografia. Selecione a política criptografada ao criar uma tabela:

CREATE TABLE secret_data (id UInt64) ENGINE = MergeTree ORDER BY id
SETTINGS storage_policy = 'encrypted';

Defina encryption.policyName para usar um nome de política diferente.

O layout de armazenamento fica praticamente definido depois que um cluster é criado. Atualizações que deixariam dados órfãos ou reatribuiriam PersistentVolumeClaims são rejeitadas na etapa de admissão:

• A presença de dataVolumeClaimSpec é imutável — você não pode adicionar um volume de dados a um cluster criado sem ele, nem removê-lo de um cluster criado com ele.
• O conjunto de additionalVolumeClaimTemplates é fixo — você não pode adicionar, remover ou renomear entradas após a criação.
• Expandir resources.requests.storage em uma entrada existente é permitido (sujeito ao suporte da StorageClass; veja Expansão do armazenamento).
• A criptografia não pode ser desabilitada depois de habilitada, e encryption.policyName não pode ser renomeado — tabelas que já usam a política criptografada ficariam inacessíveis.

• Configuração — a referência completa dos campos, incluindo extraConfig.
• Escalonamento de clusters — como réplicas e shards são adicionados e removidos.