> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Armazenamento e volumes > Como o operador provisiona armazenamento persistente para clusters ClickHouse, incluindo o volume de dados principal, layouts com vários discos (JBOD), expansão e o que não pode ser alterado após a criação. 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](/docs/pt-BR/products/kubernetes-operator/guides/configuration#storage-configuration) e a [Referência da API](/docs/pt-BR/products/kubernetes-operator/reference/api-reference).
## Volume de dados principal
`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`. ```yaml theme={null} 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](#at-rest-encryption), 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.
## Execução sem um volume de dados persistente
`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`. `dataVolumeClaimSpec` e um volume personalizado no caminho dos dados são mutuamente exclusivos. Se `dataVolumeClaimSpec` estiver definido, a montagem de um volume personalizado em `/var/lib/clickhouse` será rejeitada. Os nomes de volume reservados `clickhouse-storage-volume`, `clickhouse-server-tls-volume` e `clickhouse-server-custom-ca-volume` não podem ser usados em `podTemplate.volumes`.
## Expansão do armazenamento
Para aumentar um volume, aumente `resources.requests.storage` e aplique a alteração. O operador atualiza os PVCs existentes no local. ```yaml theme={null} spec: dataVolumeClaimSpec: resources: requests: storage: 200Gi # was 100Gi ``` A expansão só funciona quando a StorageClass subjacente tem `allowVolumeExpansion: true`. O Kubernetes não oferece suporte à redução de um PVC, então o novo tamanho deve ser maior ou igual ao tamanho atual.
## Armazenamento em múltiplos discos (JBOD)
`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 `--0`. ```yaml theme={null} 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/` 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. O caminho de montagem mantém o nome do template exatamente como está, mas o identificador do disco dentro de `storage_configuration` substitui hífens por sublinhados. Um template chamado `cold-disk` é montado em `/var/lib/clickhouse/disks/cold-disk` e aparece como `cold_disk` na configuração gerada.
## Políticas de armazenamento personalizadas
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](https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-multiple-volumes) para ver os campos da política.
## Criptografia em repouso
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. ```yaml theme={null} 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: ```sql theme={null} 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. Isso criptografa as partes de dados do MergeTree gravadas por meio da política criptografada com AES-128-CTR. Os metadados do servidor ClickHouse e os logs na raiz dos dados não são abrangidos — use criptografia em nível de disco, como LUKS ou um driver CSI, para isso. Habilitar a criptografia em um cluster em execução aciona uma reinicialização gradual única para injetar a chave; as réplicas podem, por um breve período, relatar um erro de recarregamento de configuração até que essa reinicialização seja concluída. A chave é armazenada no Secret do cluster gerenciado pelo operador, que pertence ao recurso personalizado e é excluído com ele. As partes criptografadas ficam ilegíveis sem a chave: se os dados criptografados precisarem continuar acessíveis após a exclusão do CR (os PVCs são mantidos), forneça a chave por meio de `externalSecret` ou faça backup da entrada `disk-encryption-key` antes da exclusão. Não exclua o Secret gerenciado — o operador geraria uma nova chave, e as partes criptografadas existentes se tornariam ilegíveis.
## O que você não pode alterar após a criação
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](#expanding-storage)). * 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.
## Referência de validação
| Condição | Resultado | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Sem `dataVolumeClaimSpec` e sem volume personalizado em `/var/lib/clickhouse` | Aviso — possível perda de dados ao reiniciar | | Volume personalizado montado em `/var/lib/clickhouse` com `dataVolumeClaimSpec` definido | Rejeitado | | `additionalVolumeClaimTemplates` definido, mas `dataVolumeClaimSpec` ausente | Rejeitado | | Disco adicional chamado `default` | Rejeitado — reservado pelo disco padrão do ClickHouse | | Nome de disco adicional terminando em `-encrypted` | Rejeitado — entra em conflito com os nomes de discos criptografados gerados | | Disco adicional chamado `clickhouse-storage-volume` | Rejeitado — entra em conflito com o nome do volume de dados principal | | Nome de disco adicional duplicado | Rejeitado | | Nome que não corresponde a `^[a-z]([-a-z0-9]*[a-z0-9])?$` ou tem mais de 63 caracteres | Rejeitado pelo esquema da CRD | | Adicionar ou remover `dataVolumeClaimSpec` após a criação | Rejeitado | | Adicionar, remover ou renomear `additionalVolumeClaimTemplates` após a criação | Rejeitado | | Nome de volume reservado em `podTemplate.volumes` | Rejeitado | | `encryption.policyName` definido como `default` | Rejeitado pelo esquema da CRD — a política criptografada não deve substituir a política padrão | | Desabilitar `encryption` ou renomear sua política após a criação | Rejeitado pelo esquema da CRD | * [Configuração](/docs/pt-BR/products/kubernetes-operator/guides/configuration) — a referência completa dos campos, incluindo `extraConfig`. * [Escalonamento de clusters](/docs/pt-BR/products/kubernetes-operator/guides/scaling) — como réplicas e shards são adicionados e removidos.