Pular para o conteúdo principal
Este documento fornece uma referência detalhada da API dos recursos personalizados do ClickHouse Operator.

ClickHouseCluster

ClickHouseCluster é o schema da API clickhouseclusters.

Versão da API e Kind

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
CampoTipoDescriçãoObrigatórioPadrão
specClickHouseClusterSpectrue
statusClickHouseClusterStatustrue
Aparece em:

ClickHouseClusterList

ClickHouseClusterList contém uma lista de ClickHouseCluster.

Versão da API e Kind

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseClusterList
CampoTipoDescriçãoObrigatórioPadrão
itemsarray de ClickHouseClustertrue

ClickHouseClusterSpec

ClickHouseClusterSpec define o estado desejado do ClickHouseCluster.
CampoTipoDescriçãoObrigatórioPadrão
replicasintegerNúmero de réplicas no shard único.false3
shardsintegerNúmero de shards no cluster.false1
keeperClusterRefKeeperClusterReferenceReferência ao KeeperCluster usado para a coordenação do ClickHouse.
Quando o espaço de nomes é omitido, o espaço de nomes do ClickHouseCluster é usado.
true
podTemplatePodTemplateSpecParâmetros passados para a especificação do pod do Kubernetes do ClickHouse.false
containerTemplateContainerTemplateSpecParâmetros passados para a especificação do contêiner do ClickHouse.false
dataVolumeClaimSpecPersistentVolumeClaimSpecEspecificação do armazenamento persistente para os dados do ClickHouse.false
labelsobject (keys:string, values:string)Rótulos adicionais adicionados aos recursos.false
annotationsobject (keys:string, values:string)Anotações adicionais adicionadas aos recursos.false
podDisruptionBudgetPodDisruptionBudgetSpecPodDisruptionBudget configura o PDB criado para cada shard.
Quando não definido, o operador usa por padrão maxUnavailable=1 para
shards com uma única réplica e minAvailable=1 para shards com múltiplas réplicas.
false
settingsClickHouseSettingsParâmetros de configuração do servidor ClickHouse.false
clusterDomainstringClusterDomain é o sufixo de domínio do cluster do Kubernetes usado para resolução de DNS.falsecluster.local
upgradeChannelstringUpgradeChannel especifica o canal de lançamento para verificações de upgrade de versão principal.
Quando vazio, apenas atualizações menores serão propostas. Os valores permitidos são: stable, lts ou uma versão major.minor específica (por exemplo, 25.8).
false
versionProbeTemplateVersionProbeTemplateSobrescritas de VersionProbeTemplate para o Job de detecção de versão.false
externalSecretExternalSecretExternalSecret é uma referência opcional a um Secret gerenciado externamente que contém segredos do cluster.
O Secret deve estar no mesmo espaço de nomes que o cluster.
false
Aparece em:

ClickHouseClusterStatus

ClickHouseClusterStatus define o estado observado de ClickHouseCluster.
CampoTipoDescriçãoObrigatórioPadrão
conditionsCondition arrayfalse
readyReplicasintegerReadyReplicas Número total de réplicas prontas para atender requisições.false
configurationRevisionstringConfigurationRevision indica a revisão de configuração de destino para cada réplica.true
statefulSetRevisionstringStatefulSetRevision indica a revisão de StatefulSet de destino para cada réplica.true
currentRevisionstringCurrentRevision indica a revisão mais recente da especificação do ClickHouseCluster aplicada.true
updateRevisionstringUpdateRevision indica a revisão mais recente da especificação do ClickHouseCluster solicitada.true
observedGenerationintegerObservedGeneration indica a geração mais recente observada pelo controlador.true
versionstringVersion indica a versão informada pela imagem do contêiner.false
versionProbeRevisionstringVersionProbeRevision é o hash da imagem da última verificação de versão bem-sucedida.
Quando ele corresponder ao hash da imagem atual, a Version em cache será usada diretamente.
false
Aparece em:

ClickHouseSettings

ClickHouseSettings define as opções de configuração do servidor ClickHouse.
CampoTipoDescriçãoObrigatórioPadrão
defaultUserPasswordDefaultPasswordSelectorEspecifica a origem e o tipo da senha do usuário default do ClickHouse.false
loggerLoggerConfigConfiguração de logging do servidor ClickHouse.false
tlsClusterTLSSpecConfigurações de TLS; permite configurar endpoints seguros e a verificação de certificados para o servidor ClickHouse.false
enableDatabaseSyncbooleanHabilita a sincronização dos bancos de dados do ClickHouse com as réplicas recém-criadas e a limpeza de réplicas obsoletas
após a redução de escala.
Compatível apenas com bancos de dados Replicated e de integração.
falsetrue
extraConfigRawExtensionConfiguração adicional do ClickHouse que será mesclada à configuração padrão.false
extraUsersConfigRawExtensionConfiguração adicional de usuários do ClickHouse que será mesclada à configuração padrão.false
Aparece em:

ClusterTLSSpec

ClusterTLSSpec define a configuração de TLS do cluster.
CampoTipoDescriçãoObrigatórioPadrão
enabledbooleanEnabled indica se o TLS está habilitado, determinando se portas seguras devem ser abertas.falsefalse
requiredbooleanRequired especifica se o TLS deve ser exigido para todas as conexões. Desabilita portas não seguras.falsefalse
serverCertSecretLocalObjectReferenceServerCertSecretRef é uma referência a um Secret de TLS que contém o certificado do servidor.
Espera-se que o Secret tenha a mesma estrutura dos certificados gerados pelo cert-manager,
com o certificado e a chave privada armazenados, respectivamente, nas chaves “tls.crt” e “tls.key”.
false
caBundleSecretKeySelectorCABundle é uma referência a um Secret de TLS que contém o bundle da CA.
Se estiver vazio e ServerCertSecret for especificado, o bundle da CA do certificado será usado.
Caso contrário, o bundle de CAs confiáveis do sistema será usado.
A chave assumirá o valor padrão “ca.crt” se não for especificada.
false
Aparece em:

ConfigMapKeySelector

ConfigMapKeySelector seleciona uma chave de um ConfigMap.
CampoTipoDescriçãoObrigatórioPadrão
namestringO nome do ConfigMap no espaço de nomes do cluster a partir do qual selecionar.true
keystringA chave do ConfigMap a partir da qual selecionar. Deve ser uma chave válida.true
Aparece em:

ContainerImage

ContainerImage define uma imagem de contêiner com repositório, tag ou hash.
CampoTipoDescriçãoObrigatórioPadrão
repositorystringNome do registro da imagem de contêiner
Exemplo: docker.io/clickhouse/clickhouse
false
tagstringTag da imagem de contêiner, mutuamente exclusiva com ‘hash’.
Exemplo: 25.3
false
hashstringHash da imagem de contêiner, mutuamente exclusiva com ‘tag’.false
Aparece em:

ContainerTemplateSpec

ContainerTemplateSpec descreve as sobrescritas de configuração dos contêineres do cluster.
CampoTipoDescriçãoObrigatórioPadrão
imageContainerImageImage é a imagem de contêiner a ser implantada.true
imagePullPolicyPullPolicyImagePullPolicy da imagem, cujo padrão é IfNotPresent.false
resourcesResourceRequirementsResources define os requisitos de recursos do contêiner do servidor.
Mesclados recursivamente com os padrões do operador via SMP. Limites e solicitações individuais sobrescrevem apenas as
chaves correspondentes; campos não definidos preservam os padrões do operador.
false
volumeMountsVolumeMount arrayVolumeMounts é a lista de montagens de volume do contêiner.
Concatenada com as montagens geradas pelo operador. Entradas que compartilham um mountPath com uma montagem do operador
são mescladas em um volume projetado.
false
envEnvVar arrayEnv é a lista de variáveis de ambiente a serem definidas no contêiner.
Mesclada com os padrões do operador por nome.
false
securityContextSecurityContextSecurityContext define as opções de segurança com que o contêiner deve ser executado.
Um SecurityContext não nulo substitui integralmente os padrões do operador; o usuário passa a ser responsável por toda a
estrutura. Quando nulo, os padrões do operador são preservados.
Mais informações: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
false
livenessProbeProbeLivenessProbe sobrescreve a sonda de liveness padrão do operador.false
readinessProbeProbeReadinessProbe sobrescreve a sonda de prontidão padrão do operador.false
Aparece em:

DefaultPasswordSelector

DefaultPasswordSelector seleciona a origem da senha padrão do usuário.
CampoTipoDescriçãoObrigatórioPadrão
passwordTypestringTipo da senha fornecida. Consulte a documentação para conhecer os valores possíveis https://clickhouse.com/docs/operations/settings/settings-users#user-namepasswordtruepassword
secretSecretKeySelectorSeleciona o valor da senha a partir de uma chave de Secretfalse
configMapConfigMapKeySelectorSeleciona o valor da senha a partir de uma chave de ConfigMapfalse
Aparece em:

ExternalSecret

ExternalSecret é uma referência a um Secret no mesmo espaço de nomes.
CampoTipoDescriçãoObrigatórioPadrão
namestringNome do Secret.true
policyExternalSecretPolicyA política controla como o operador trata o conteúdo do Secret.
Observe (padrão): bloqueia a reconciliação se alguma chave obrigatória estiver ausente.
Manage: gera as chaves obrigatórias ausentes no Secret existente.
falseObserve
Aparece em:

ExternalSecretPolicy

ExternalSecretPolicy controla como o operador trata o conteúdo do Secret externo.
CampoDescrição
ObserveExternalSecretPolicyObserve é a política padrão: o operador lê e valida o Secret;
a reconciliação é bloqueada se alguma chave obrigatória estiver ausente.
As chaves obrigatórias ausentes e os formatos esperados para elas são informados por meio da condição de status ExternalSecretValid em tempo de execução.
ManageExternalSecretPolicyManage é a política em que o operador preenche quaisquer chaves obrigatórias ausentes, gerando
valores para elas. O Secret é atualizado, mas nunca fica sob posse do operador nem é excluído por ele.
Aparece em:

KeeperCluster

KeeperCluster é o schema da API keeperclusters.

Versão da API e Kind

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
CampoTipoDescriçãoObrigatórioPadrão
specKeeperClusterSpectrue
statusKeeperClusterStatustrue
Aparece em:

KeeperClusterList

KeeperClusterList contém uma lista de KeeperCluster.

Versão da API e Kind

apiVersion: clickhouse.com/v1alpha1
kind: KeeperClusterList
CampoTipoDescriçãoObrigatórioPadrão
itemsKeeperCluster arraytrue

KeeperClusterReference

KeeperClusterReference identifica o KeeperCluster utilizado por um ClickHouseCluster.
CampoTipoDescriçãoObrigatórioPadrão
namestringNome do recurso KeeperCluster.true
namespacestringEspaço de nomes do recurso KeeperCluster.
Quando omitido, é usado o espaço de nomes do ClickHouseCluster.
false
Aparece em:

KeeperClusterSpec

KeeperClusterSpec define o estado desejado do KeeperCluster.
CampoTipoDescriçãoObrigatórioPadrão
replicasintegerNúmero de réplicas no clusterfalse3
podTemplatePodTemplateSpecParâmetros passados para a especificação do pod do Kubernetes do Keeper.false
containerTemplateContainerTemplateSpecParâmetros passados para a especificação do contêiner do Keeper.false
dataVolumeClaimSpecPersistentVolumeClaimSpecEspecificação do armazenamento persistente para os dados do ClickHouse Keeper.false
labelsobject (keys:string, values:string)Rótulos adicionais adicionados aos recursos.false
annotationsobject (keys:string, values:string)Anotações adicionais adicionadas aos recursos.false
podDisruptionBudgetPodDisruptionBudgetSpecPodDisruptionBudget configura o PDB criado para o cluster do Keeper.
Quando não definido, o operador usa por padrão maxUnavailable=replicas/2
(preservando o quórum em um cluster 2F+1).
false
settingsKeeperSettingsParâmetros de configuração do servidor ClickHouse Keeper.false
clusterDomainstringClusterDomain é o sufixo de domínio do cluster Kubernetes usado para a resolução de DNS.falsecluster.local
upgradeChannelstringUpgradeChannel especifica o canal de lançamento para verificações de upgrade de versão principal.
Quando vazio, apenas atualizações secundárias serão propostas. Os valores permitidos são: stable, lts ou uma versão major.minor específica (por exemplo, 25.8).
false
versionProbeTemplateVersionProbeTemplateSobrescritas de VersionProbeTemplate para o Job de detecção de versão.false
Aparece em:

KeeperClusterStatus

KeeperClusterStatus define o estado observado de KeeperCluster.
CampoTipoDescriçãoObrigatórioPadrão
conditionsCondition arrayfalse
readyReplicasintegerReadyReplicas Número total de réplicas prontas para atender a solicitações.false
configurationRevisionstringConfigurationRevision indica a revisão de configuração de destino para cada réplica.true
statefulSetRevisionstringStatefulSetRevision indica a revisão de StatefulSet de destino para cada réplica.true
currentRevisionstringCurrentRevision indica a revisão de spec do KeeperCluster aplicada mais recentemente.true
updateRevisionstringCurrentRevision indica a revisão de spec do KeeperCluster solicitada mais recentemente.true
observedGenerationintegerObservedGeneration indica a geração mais recente observada pelo controlador.true
versionstringVersion indica a versão informada pela imagem do contêiner.false
versionProbeRevisionstringVersionProbeRevision é o hash da imagem da última verificação de versão bem-sucedida.
Quando isso corresponde ao hash da imagem atual, a Version em cache é usada diretamente.
false
Aparece em:

KeeperSettings

KeeperSettings define as configurações do servidor ClickHouse Keeper.
CampoTipoDescriçãoObrigatórioPadrão
loggerLoggerConfigConfiguração de logging do servidor ClickHouse Keeper.false
tlsClusterTLSSpecConfigurações de TLS que permitem configurar endpoints seguros e a verificação de certificados para o servidor ClickHouse Keeper.false
extraConfigRawExtensionConfiguração adicional do ClickHouse Keeper que será mesclada à configuração padrão.false
Aparece em:

LoggerConfig

LoggerConfig define a configuração de logging do servidor.
CampoTipoDescriçãoObrigatórioPadrão
logToFilebooleanSe for false, desativa todo o logging em arquivo.falsetrue
jsonLogsbooleanSe for true, registra em formato JSON.falsefalse
levelstringNível de verbosidade do logger do servidor.falsetrace
sizestringTamanho máximo do arquivo de log.false1000M
countintegerNúmero máximo de arquivos de log a serem mantidos.false50
Aparece em:

PDBPolicy

PDBPolicy controla se os PodDisruptionBudgets serão criados.
CampoDescrição
EnabledPDBPolicyEnabled habilita a criação de PodDisruptionBudgets pelo operador.
DisabledPDBPolicyDisabled desabilita os PodDisruptionBudgets; o operador excluirá o recurso com os rótulos correspondentes.
IgnoredPDBPolicyIgnored ignora os PodDisruptionBudgets; o operador não criará nem excluirá nenhum PDB, e os PDBs existentes permanecerão inalterados.
Aparece em:

PodDisruptionBudgetSpec

PodDisruptionBudgetSpec configura o PDB criado para o cluster. Exatamente um entre MinAvailable ou MaxUnavailable pode ser definido. Quando nenhum deles é definido, o operador escolhe um padrão seguro com base na contagem de réplicas.
CampoTipoDescriçãoObrigatórioPadrão
policyPDBPolicyA política controla se o operador cria PodDisruptionBudgets.
O padrão é “Enabled” quando não está definido. Defina-o como “Disabled” para pular a criação do PDB (por exemplo, em ambientes de desenvolvimento).
falseEnabled
minAvailableIntOrStringMinAvailable é o número mínimo de pods que devem permanecer disponíveis durante uma interrupção.false
maxUnavailableIntOrStringMaxUnavailable é o número máximo de pods que podem ficar indisponíveis durante uma interrupção.false
unhealthyPodEvictionPolicyUnhealthyPodEvictionPolicyTypeUnhealthyPodEvictionPolicy define os critérios para quando pods não saudáveis
devem ser considerados para evicção.
Os valores válidos são “IfReady” e “AlwaysAllow”.
false
Aparece em:

PodTemplateSpec

PodTemplateSpec descreve as substituições da configuração de pod para os pods do cluster.
CampoTipoDescriçãoObrigatórioPadrão
terminationGracePeriodSecondsinteiroDuração opcional, em segundos, de que o pod do Kubernetes precisa para ser encerrado de forma graciosa. Pode ser reduzida na solicitação de exclusão.
O valor deve ser um inteiro não negativo. O valor zero indica interrupção imediata por meio
do sinal kill (sem oportunidade de desligamento).
Se esse valor for nil, o período de carência padrão será usado.
O período de carência é a duração, em segundos, entre o momento em que os processos em execução no pod do Kubernetes recebem
um sinal de encerramento e o momento em que os processos são interrompidos à força com um sinal kill.
Defina esse valor como maior que o tempo de limpeza esperado para o seu processo.
O padrão é 30 segundos.
false
topologySpreadConstraintsTopologySpreadConstraint arrayTopologySpreadConstraints descreve como um grupo de pods deve se distribuir entre domínios de topologia
. O agendador distribuirá os pods de forma a respeitar as restrições.
Todos os topologySpreadConstraints são combinados com AND.
Mesclado com os padrões do operador por topologyKey.
false
imagePullSecretsLocalObjectReference arrayImagePullSecrets é uma lista opcional de referências a Secrets no mesmo espaço de nomes, usada para baixar qualquer uma das imagens usadas por este PodSpec.
Se especificados, esses Secrets serão passados para os componentes individuais responsáveis por baixar as imagens, para que possam usá-los.
Mais informações: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod
Mesclado com os padrões do operador por nome.
false
nodeSelectorobjeto (chaves:string, valores:string)NodeSelector é um seletor que deve ser satisfeito para que o pod do Kubernetes possa ser executado em um nó.
Seletor que deve corresponder aos labels de um nó para que o pod do Kubernetes seja agendado nesse nó.
Mais informações: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
false
affinityAfinidadeSe especificado, as restrições de agendamento do pod do Kubernetes.
Adicionado aos padrões do operador: as listas de termos de agendamento são concatenadas.
false
tolerationsToleration arraySe especificadas, as tolerâncias do pod do Kubernetes.false
schedulerNamestringSe especificado, o pod do Kubernetes será agendado pelo agendador especificado.
Se não for especificado, o pod do Kubernetes será agendado pelo agendador padrão.
false
serviceAccountNamestringServiceAccountName é o nome da ServiceAccount usada para executar este pod do Kubernetes.
Mais informações: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/
false
priorityClassNamestringPriorityClassName é o nome da PriorityClass a ser usada para o pod do Kubernetes.false
runtimeClassNamestringRuntimeClassName é o nome da RuntimeClass a ser usada para o pod do Kubernetes.false
volumesVolume arrayVolumes define a lista de volumes que podem ser montados por contêineres pertencentes ao pod do Kubernetes.
Mais informações: https://kubernetes.io/docs/concepts/storage/volumes
Mesclados aos valores padrão do operador por nome; um volume do usuário substitui qualquer volume do operador com o mesmo nome.
false
securityContextPodSecurityContextSecurityContext contém atributos de segurança em nível de pod do Kubernetes e configurações comuns de contêiner.
Um SecurityContext não nulo substitui completamente os padrões do operador; o usuário é responsável por toda a
estrutura. Quando nulo, os padrões do operador são preservados.
false
topologyZoneKeystringTopologyZoneKey é a chave dos rótulos dos nós.
Nós que têm um rótulo com essa chave e valores idênticos são considerados como pertencentes à mesma zona de topologia.
Defina-a para habilitar as regras padrão de TopologySpreadConstraints e Affinity, distribuindo os pods entre as zonas.
Recomenda-se defini-la como “topology.kubernetes.io/zone”
false
nodeHostnameKeystringNodeHostnameKey é a chave dos rótulos do nó.
Nós que têm um rótulo com essa chave e valores idênticos são considerados como estando no mesmo nó.
Defina-o para habilitar as regras padrão de AntiAffinity e distribuir réplicas de shards diferentes entre os nós.
Recomenda-se defini-lo como “kubernetes.io/hostname”
false
initContainersContainer arrayInitContainers é a lista de contêineres de inicialização executados antes de o contêiner principal do servidor ser iniciado.
Mesclado com os padrões do operador por nome.
com o mesmo nome.
false
Aparece em:

SecretKeySelector

SecretKeySelector seleciona uma chave de um Secret.
CampoTipoDescriçãoObrigatórioPadrão
namestringO nome do Secret no espaço de nomes do cluster de onde selecionar.true
keystringA chave do Secret de onde selecionar. Deve ser uma chave de Secret válida.true
Aparece em:

TemplateMeta

TemplateMeta define as configurações de metadados compatíveis para objetos de template.
CampoTipoDescriçãoObrigatórioPadrão
labelsobjeto (keys:string, values:string)labels são rótulos aplicados aos objetos de template.false
annotationsobjeto (keys:string, values:string)As anotações são aplicadas aos objetos de template.false
Aparece em:

VersionProbeContainer

VersionProbeContainer define substituições no nível do contêiner para a sonda de versão. Os nomes dos campos e as tags JSON correspondem a corev1.Container para que as mesclagens SMP sejam feitas por nome.
CampoTipoDescriçãoObrigatórioPadrão
namestringNome do contêiner. Se estiver vazio, o operador o define como o nome do contêiner da sonda de versão.trueversion-probe
resourcesResourceRequirementsResources são os requisitos de recursos computacionais para o contêiner da sonda de versão.
Mesclados em profundidade com os padrões do operador via SMP.
false
securityContextSecurityContextSecurityContext define as opções de segurança para o contêiner da sonda de versão.
Mesclado em profundidade com os padrões do operador via SMP.
false
Aparece em:

VersionProbeJobSpec

VersionProbeJobSpec define substituições no nível do Job para a sonda de versão.
CampoTipoDescriçãoObrigatórioPadrão
ttlSecondsAfterFinishedintegerTTLSecondsAfterFinished limita o tempo de vida de um Job concluído.false
templateVersionProbePodTemplateTemplate descreve o pod do Kubernetes que será criado para o Job de sonda de versão.false
Aparece em:

VersionProbePodSpec

VersionProbePodSpec define substituições no nível de pod para a sonda de versão. Os nomes dos campos e as tags JSON correspondem a corev1.PodSpec para compatibilidade com strategic merge patch.
CampoTipoDescriçãoObrigatórioPadrão
nodeSelectorobject (keys:string, values:string)NodeSelector restringe o pod da sonda de versão aos nós com rótulos correspondentes.false
tolerationsToleration arrayTolerations do pod da sonda de versão.false
securityContextPodSecurityContextSecurityContext contém atributos de segurança no nível do pod para o pod da sonda de versão.false
containersVersionProbeContainer arraySubstituições dos containers do pod da sonda de versão.
O campo name é opcional — o operador o preenche com o container padrão.
Também é possível especificar um container adicional com um nome diferente.
false
Aparece em:

VersionProbePodTemplate

VersionProbePodTemplate descreve substituições para o pod do Kubernetes de sonda de versão.
CampoTipoDescriçãoObrigatórioPadrão
metadataTemplateMetaConsulte a documentação da API do Kubernetes para conhecer os campos de metadata.false
specVersionProbePodSpecEspecificação do comportamento desejado do pod do Kubernetes de sonda de versão.false
Aparece em:

VersionProbeTemplate

VersionProbeTemplate define substituições para o Job de detecção de versão. A estrutura corresponde a batchv1.JobTemplateSpec, expondo apenas os campos compatíveis.
CampoTipoDescriçãoObrigatórioPadrão
metadataTemplateMetaConsulte a documentação da API do Kubernetes para ver os campos de metadata.false
specVersionProbeJobSpecEspecificação do comportamento desejado do Job de detecção de versão.false
Aparece em:
Última modificação em 10 de junho de 2026