ClickHouseCluster

Geltungsbereich: namespaced · Backend: der offizielle ClickHouse-Operator (type: clickhouse)

ClickHouse für die analytischen Speicher der Plattform — Langfuse-Traces und die Analysedaten des Wäg-Gateways. Folgt derselben type × mode-Form wie die anderen Datenspeicher und beherbergt wie PostgresCluster logische Datenbanken je Konsument in einem Cluster.

Spec

Feld	Typ	Beschreibung
type	enum clickhouse (Standard)	Backend: der offizielle ClickHouse-Operator. altinity wird für bestehende Objekte weiterhin akzeptiert und verhält sich gleich; es bedeutete nie den Altinity-Operator
mode	enum managed | adopt | external (erforderlich)	Provenance-Modus
managed	object	Speicher, Ressourcen, Replikate bei mode: managed
adopt	object	Referenz auf eine bestehende clusterinterne ClickHouse-CR
external	object	Verbindungs-Secret für ein externes ClickHouse
databases[]	list	Datenbanken, die im Cluster sichergestellt werden (eine je konsumierendem Workload) — siehe databases[]

adopt

Feld	Beschreibung
installationRef	Die bestehende ClickHouse-Installation. namespace ist optional und darf auf einen anderen Namespace zeigen — der Service-Host wird daraus gebildet
credentialsSecretRef	Praktisch erforderlich: das Secret mit username / password. namespace ist standardmäßig der Namespace der Installation; ein Secret außerhalb des Namespace dieser CR wird hierher als <name>-adopted-credentials gespiegelt

databases[]

Logische Datenbanken, die im Cluster sichergestellt werden — eine je konsumierendem Workload, nach derselben Idee, die PostgresCluster.spec.databases für Postgres bereits abdeckt.

Feld	Beschreibung
name	Name der Datenbank. Muster ^[A-Za-z_][A-Za-z0-9_]*$, maximal 63 Zeichen. ClickHouse-Bezeichner unterscheiden Groß- und Kleinschreibung

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

Der Operator stellt jeden Eintrag mit CREATE DATABASE IF NOT EXISTS über die HTTP-Schnittstelle von ClickHouse sicher und meldet das Ergebnis unter status.databases als { name, ready }.

Warum es das gibt

Weder Langfuse noch Wäg legt seine eigene ClickHouse-Datenbank an — beide legen nur ihre Tabellen an. Langfuse kommt damit durch, weil es in ClickHouses eingebauter Datenbank default landet, die immer existiert. Wäg zielt auf eine Datenbank namens waeg und beendet sich beim Start mit:

Database waeg does not exist

Ein Wäg-Gateway auf einem frischen, verwalteten ClickHouse konnte also überhaupt nicht starten, ohne dass jemand von Hand ein CREATE DATABASE ausführte. Die Deklaration hier macht den Cluster ohne diesen Schritt nutzbar.

Für welche Modi es gilt

Modus	Angewendet?	Warum
managed	ja	Der Operator besitzt den Cluster
adopt	ja	CREATE DATABASE IF NOT EXISTS ist rein additiv — es rührt eine bestehende Datenbank und deren Daten nie an — und ein adoptierter Cluster könnte sonst kein Wäg-Gateway beherbergen
external	nein	Der Operator hat eine Verbindungszeichenfolge erhalten, keine Eigentümerschaft. Er führt kein DDL gegen Infrastruktur aus, die er nicht verwaltet — legen Sie die Datenbank selbst an

Datenbanken werden nie gelöscht

Einen Eintrag aus spec.databases zu entfernen, den konsumierenden Workload zu löschen oder die ClickHouseCluster-CR selbst zu löschen, löscht niemals eine Datenbank — auf keinem Pfad. Analyse- und Trace-Historie soll ein versehentliches Löschen überdauern. Löschen Sie eine Datenbank von Hand, wenn Sie es wirklich so meinen.

Workloads, die diesen Cluster referenzieren

Mit der auto-wiring-Lizenz werden Datenbanken, die referenzierende Workloads nutzen (das langfuse.clickhouse.databaseName einer Observability, die Datenbank eines Wäg-Gateways), ohne Deklaration angelegt, und status.databases[].claimedBy zeigt, wer welche nutzt. Siehe Datenbanken für Workloads, die einen Datenspeicher referenzieren.

Ein Stack deklariert waeg für Sie

Ein Stack mit einem type: waeg-Gateway im Standard-Speichermodus split fügt waeg automatisch zu seinem verwalteten ClickHouse hinzu — Sie schreiben nichts. Mit gateway.waeg.storageMode: single gibt es gar kein ClickHouse, also wird auch nichts deklariert.

Die Datenbank von Langfuse

Ein neuer Stack gibt Langfuse eine eigene langfuse-Datenbank: Sie wird hier deklariert, und clickhouse.databaseName der Observability richtet Langfuse darauf aus (CLICKHOUSE_DB, ab langfuse-operator 0.10.1). Langfuse wartet, bis dieser Cluster die Datenbank als vorhanden meldet.

Ein Langfuse, das bereits auf ClickHouses eingebauter default-Datenbank läuft — jeder Stack, der vor dieser Option angelegt wurde — bleibt dort. Ein Umzug würde Langfuse auf einer leeren Datenbank starten, und die vorhandenen Traces verschwänden aus der Oberfläche. Für einen bewussten Umzug setzen Sie clickhouse.databaseName an einer eigenständigen Observability und nehmen in Kauf, dass sie leer beginnt (frühere Traces bleiben in default).

Eine Datenbank von Hand auswählen

Sie verdrahten einen Konsumenten selbst? Die Datenbank wird über den Query-Parameter ?database= der ClickHouse-HTTP-URL ausgewählt — nicht über einen Pfad:

http://forge-ch:8123/?database=waeg     # richtig
http://forge-ch:8123/waeg               # still und leise falsch

Die HTTP-Schnittstelle von ClickHouse ignoriert einen unbekannten Pfad und liefert ihre menschenlesbare Startseite aus. Die zweite Form gibt also Hilfetext statt eines Fehlers zurück — was der Konsument anschließend als unlesbare Antwort meldet, ohne dass irgendetwas auf die URL hinweist.

Verhalten je Modus

• managed — stellt den ClickHouse-Operator sicher und erstellt dessen Custom Resource. Ein ClickHouseCluster erfordert einen begleitenden KeeperCluster, den der Controller ebenfalls emittiert.
• adopt — referenziert eine bestehende clusterinterne ClickHouse-CR — gegebenenfalls in einem anderen Namespace (namespace-übergreifende Adoption) — und veröffentlicht deren Anmeldedaten für Konsumenten; der Lebenszyklus wird nicht verwaltet. Ohne adopt.credentialsSecretRef kann sich nichts verbinden; die Ressource meldet dann Ready=False und nennt dieses Feld, statt ohne Anmeldedaten Ready zu werden.
• external — verdrahtet ein Verbindungs-Secret; es wird kein Operator installiert. databases wird hier nicht angewendet.

spec.databases wird auf managed- und adopt-Clustern bei jeder Reconciliation sichergestellt und nie gelöscht — siehe databases[].

Langfuse kann ClickHouse für Sie verwalten

Der langfuse-operator kann ClickHouse und Redis intern verwalten. Sofern Sie keinen external-Datenspeicher referenzieren, verwendet der Observability-Controller standardmäßig operator-verwaltetes ClickHouse/Redis — allein für Langfuse ist ein dediziertes ClickHouseCluster daher optional. Verwenden Sie diese Ressource, wenn Sie ClickHouse explizit verwalten oder gemeinsam nutzen möchten — was auch ein Gateway mit type: waeg im split-Speichermodus benötigt.

Beispiel — managed

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

Beispiel — external

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

Backups & Wiederherstellung

Setzen Sie managed.backup (nur Managed-Modus), um Backups in Objektspeicher zu planen — dieselbe anbieterneutrale Form wie Postgres/Mongo (provider: s3 | azure | gcs, Ziel, Credentials, schedule, retentionPolicy).

Der Operator erzeugt einen verwalteten <name>-backup CronJob, der clickhouse-backup im embedded-Modus ausführt (serverseitiges SQL BACKUP) — funktioniert über das Netzwerk mit dem offiziellen ClickHouse-Operator, ohne Sidecar oder Zugriff auf das Datenvolume. backup.enabled: false löscht den 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 }
      schedule: "0 0 3 * * *"
      retentionPolicy: "30d"

Wiederherstellung ist ein manueller Ablauf (aus einem Pod mit denselben Backup-Umgebungsvariablen):

clickhouse-backup list remote
clickhouse-backup restore_remote <backup-name>

Status

Feld	Beschreibung
host / port	Verbindungskoordinaten für Konsumenten
credentialsSecret	Das Secret mit username / password in diesem Namespace
databases[]	Ein Eintrag { name, ready } je angeforderter Datenbank
phase, conditions, observedGeneration	Die standardmäßige Status-Oberfläche