ClickHouseCluster

Ambito: namespaced · Backend: l'operatore ufficiale di ClickHouse (type: clickhouse)

ClickHouse per gli store analitici della piattaforma — le trace di Langfuse e le analisi del gateway Wäg. Segue la stessa struttura type × mode degli altri datastore e, come PostgresCluster, ospita database logici per consumer all'interno di un unico cluster.

Spec

Campo	Tipo	Descrizione
type	enum clickhouse (predefinito)	Backend: l'operatore ufficiale di ClickHouse. altinity è ancora accettato per gli oggetti esistenti e si comporta allo stesso modo; non ha mai indicato l'operatore di Altinity
mode	enum managed | adopt | external (obbligatorio)	Modalità di provenienza
managed	object	Storage, risorse e repliche quando mode: managed
adopt	object	Riferimento a una CR ClickHouse esistente nel cluster
external	object	Secret di connessione per un ClickHouse esterno
databases[]	list	Database da garantire all'interno del cluster (uno per ogni workload consumer) — vedi databases[]

adopt

Campo	Descrizione
installationRef	L'installazione ClickHouse esistente. namespace è facoltativo e può indicare un altro namespace — l'host del servizio viene costruito a partire da esso
credentialsSecretRef	Di fatto obbligatorio: il Secret che contiene username / password. namespace assume per default il namespace dell'installazione; un Secret al di fuori del namespace di questa CR viene replicato qui come <name>-adopted-credentials

databases[]

Database logici da garantire all'interno del cluster — uno per ogni workload consumer, lo stesso principio che PostgresCluster.spec.databases copre già per Postgres.

Campo	Descrizione
name	Nome del database. Pattern ^[A-Za-z_][A-Za-z0-9_]*$, massimo 63 caratteri. Gli identificatori ClickHouse distinguono maiuscole e minuscole

spec:
  type: clickhouse
  mode: managed
  databases:
    - name: waeg

L'operatore garantisce ogni voce con CREATE DATABASE IF NOT EXISTS tramite l'interfaccia HTTP di ClickHouse e riporta il risultato in status.databases come { name, ready }.

Perché esiste

Né Langfuse né Wäg creano il proprio database ClickHouse — entrambi creano solo le proprie tabelle. Langfuse se la cava perché finisce nel database integrato default di ClickHouse, che esiste sempre. Wäg punta a un database chiamato waeg e termina all'avvio con:

Database waeg does not exist

Un gateway Wäg su un ClickHouse managed appena creato non potrebbe quindi affatto avviarsi senza che qualcuno esegua CREATE DATABASE a mano. È dichiarare il database qui che rende il cluster utilizzabile senza quel passaggio.

A quali modalità si applica

Modalità	Applicato?	Perché
managed	sì	L'operatore possiede il cluster
adopt	sì	CREATE DATABASE IF NOT EXISTS è puramente additivo — non tocca mai un database esistente né i suoi dati — e altrimenti un cluster adottato non potrebbe ospitare un gateway Wäg
external	no	All'operatore è stata consegnata una stringa di connessione, non la proprietà. Non esegue DDL su un'infrastruttura che non gestisce — crea il database tu stesso

I database non vengono mai eliminati

Rimuovere una voce da spec.databases, eliminare il workload consumer o eliminare la CR ClickHouseCluster stessa non elimina mai un database — in nessun caso. Le analisi e lo storico delle trace devono sopravvivere a un'eliminazione per errore. Eliminane uno a mano quando è davvero ciò che vuoi.

Workload che fanno riferimento a questo cluster

Con la licenza auto-wiring, i database usati dai workload che fanno riferimento al cluster (il langfuse.clickhouse.databaseName di un'Observability, il database di un gateway Wäg) vengono creati senza essere dichiarati, e status.databases[].claimedBy mostra chi usa ciascuno. Vedi Database per i workload che fanno riferimento a un datastore.

Uno Stack dichiara waeg al posto tuo

Uno Stack con un gateway type: waeg nella modalità di storage predefinita split aggiunge automaticamente waeg al proprio ClickHouse managed — non devi scrivere nulla. Con gateway.waeg.storageMode: single non c'è alcun ClickHouse, quindi non viene dichiarato nulla.

Il database di Langfuse

Uno Stack nuovo assegna a Langfuse un proprio database langfuse: viene dichiarato qui, e il clickhouse.databaseName dell'Observability indirizza Langfuse verso di esso (CLICKHOUSE_DB, tramite langfuse-operator 0.10.1 o successivo). Langfuse attende finché questo cluster non segnala la presenza del database.

Un Langfuse che gira già sul database integrato default di ClickHouse — ogni Stack creato prima che esistesse questa opzione — rimane lì. Spostarlo farebbe partire Langfuse su un database vuoto e le sue trace esistenti sparirebbero dalla UI. Per spostarne uno deliberatamente, imposta clickhouse.databaseName su un'Observability standalone e accetta che parta vuota (le trace precedenti restano in default).

Selezionare un database a mano

Colleghi un consumer da solo? Il database si seleziona con il parametro di query ?database= sull'URL HTTP di ClickHouse — non con un percorso:

http://forge-ch:8123/?database=waeg     # correct
http://forge-ch:8123/waeg               # silently wrong

L'interfaccia HTTP di ClickHouse ignora un percorso sconosciuto e serve la sua pagina iniziale leggibile, quindi la seconda forma restituisce un testo di aiuto invece di un errore — che il consumer segnala poi come risposta non interpretabile, senza alcun indizio che rimandi all'URL.

Comportamento per modalità

• managed — garantisce l'operatore ClickHouse e crea la sua custom resource. Un ClickHouseCluster richiede un KeeperCluster associato, che il controller emette anch'esso.
• adopt — fa riferimento a una CR ClickHouse esistente nel cluster — eventualmente in un altro namespace (adozione tra namespace) — e pubblica le sue credenziali per i consumer; il ciclo di vita non viene gestito. Senza adopt.credentialsSecretRef nessuno può connettersi, quindi la risorsa riporta Ready=False indicando quel campo invece di diventare Ready senza credenziali.
• external — collega un Secret di connessione; nessun operatore viene installato. databases non viene applicato qui.

spec.databases viene garantito sui cluster managed e adopt a ogni riconciliazione e non viene mai eliminato — vedi databases[].

Langfuse può gestire ClickHouse al posto tuo

Il langfuse-operator può gestire ClickHouse e Redis internamente. A meno che tu non faccia riferimento a un datastore external, il controller Observability usa per default ClickHouse/Redis gestiti dall'operatore — quindi un ClickHouseCluster dedicato è facoltativo per il solo Langfuse. Usa questa risorsa quando vuoi gestire o condividere ClickHouse esplicitamente — che è anche ciò di cui ha bisogno un Gateway type: waeg in modalità di storage split.

Esempio — managed

apiVersion: core.navique.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: forge-ch
  namespace: forge-data
spec:
  type: clickhouse
  mode: managed

Esempio — external

spec:
  type: clickhouse
  mode: external
  external:
    connectionSecretRef: { name: clickhouse-conn }

Backup e ripristino

Imposta managed.backup (solo in modalità managed) per pianificare backup su object storage. Il blocco ha la stessa struttura indipendente dal provider di Postgres/Mongo — provider: s3 | azure | gcs, una destinazione, le credenziali, schedule e retentionPolicy.

L'operatore emette un CronJob <name>-backup di sua proprietà che esegue clickhouse-backup in modalità embedded (BACKUP SQL lato server), quindi funziona via rete con l'operatore ufficiale di ClickHouse — senza sidecar né accesso ai volumi dati. Impostare backup.enabled: false (o rimuovere il blocco) elimina il CronJob.

spec:
  type: clickhouse
  mode: managed
  managed:
    storageSize: 50Gi
    backup:
      enabled: true
      provider: s3
      s3:
        destinationPath: s3://my-bucket/clickhouse
        credentialsSecretRef: { name: ch-backup-creds }   # access-key-id / secret-access-key
      schedule: "0 0 3 * * *"     # 6-field cron; the CronJob uses the 5-field form
      retentionPolicy: "30d"      # mapped to BACKUPS_TO_KEEP_REMOTE

Il ripristino è una procedura manuale (da eseguire da un pod con lo stesso ambiente di backup):

clickhouse-backup list remote                       # find the backup name
clickhouse-backup restore_remote <backup-name>      # download + restore via SQL

Vedi la guida al ripristino di Altinity.

Status

Campo	Descrizione
host / port	Coordinate di connessione per i consumer
credentialsSecret	Il Secret che contiene username / password in questo namespace
databases[]	Una voce { name, ready } per ogni database richiesto
phase, conditions, observedGeneration	La superficie di status standard