ClickHouseCluster

Portée : namespaced · Backend : l'opérateur ClickHouse officiel (type: clickhouse)

ClickHouse pour les stores analytiques de la plateforme — les traces de Langfuse et les analyses de la passerelle Wäg. Suit la même forme type × mode que les autres datastores et, comme PostgresCluster, héberge des bases logiques par consommateur dans un même cluster.

Spec

Champ	Type	Description
type	enum clickhouse (par défaut)	Backend : l'opérateur ClickHouse officiel. altinity reste accepté pour les objets existants et se comporte de la même façon ; il n'a jamais désigné l'opérateur Altinity
mode	enum managed | adopt | external (requis)	Mode de Provenance
managed	object	Stockage, ressources, réplicas lorsque mode: managed
adopt	object	Référence à une CR ClickHouse in-cluster existante
external	object	Secret de connexion pour un ClickHouse externe
databases[]	list	Bases à garantir dans le cluster (une par workload consommateur) — voir databases[]

adopt

Champ	Description
installationRef	L'installation ClickHouse existante. namespace est optionnel et peut désigner un autre namespace — l'hôte du service en est déduit
credentialsSecretRef	Requis en pratique : le Secret contenant username / password. namespace vaut par défaut celui de l'installation ; un Secret hors du namespace de cette CR est recopié ici sous le nom <name>-adopted-credentials

databases[]

Bases logiques à garantir à l'intérieur du cluster — une par workload consommateur, sur le même principe que PostgresCluster.spec.databases pour Postgres.

Champ	Description
name	Nom de la base. Motif ^[A-Za-z_][A-Za-z0-9_]*$, 63 caractères au plus. Les identifiants ClickHouse sont sensibles à la casse

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

L'opérateur garantit chaque entrée par un CREATE DATABASE IF NOT EXISTS via l'interface HTTP de ClickHouse et rapporte le résultat sur status.databases sous la forme { name, ready }.

Pourquoi ce champ existe

Ni Langfuse ni Wäg ne crée sa propre base ClickHouse — tous deux ne créent que leurs tables. Langfuse s'en tire parce qu'il atterrit dans la base default intégrée à ClickHouse, qui existe toujours. Wäg vise une base nommée waeg et s'arrête au démarrage avec :

Database waeg does not exist

Une passerelle Wäg sur un ClickHouse managé tout neuf ne pouvait donc pas démarrer du tout sans un CREATE DATABASE lancé à la main. C'est la déclaration faite ici qui rend le cluster utilisable sans cette étape.

Modes concernés

Mode	Appliqué ?	Pourquoi
managed	oui	L'opérateur possède le cluster
adopt	oui	CREATE DATABASE IF NOT EXISTS est purement additif — il ne touche jamais une base existante ni ses données — et un cluster adopté ne pourrait sinon pas héberger une passerelle Wäg
external	non	L'opérateur a reçu une chaîne de connexion, pas la propriété. Il n'émet pas de DDL contre une infrastructure qu'il ne gère pas — créez la base vous-même

Les bases ne sont jamais supprimées

Retirer une entrée de spec.databases, supprimer le workload consommateur ou supprimer la CR ClickHouseCluster elle-même ne supprime jamais une base — sur aucun chemin. L'historique analytique et de traces doit survivre à une suppression malencontreuse. Supprimez une base à la main lorsque c'est réellement l'intention.

Workloads qui référencent ce cluster

Avec la licence auto-wiring, les bases qu'utilisent les workloads qui le référencent (le langfuse.clickhouse.databaseName d'une Observability, la base d'une passerelle Wäg) sont créées sans être déclarées, et status.databases[].claimedBy indique qui utilise chacune. Voir Bases de données pour les workloads qui référencent un datastore.

Un Stack déclare waeg pour vous

Un Stack doté d'une passerelle type: waeg dans le mode de stockage split par défaut ajoute automatiquement waeg à son ClickHouse managé — vous n'écrivez rien. Avec gateway.waeg.storageMode: single, il n'y a aucun ClickHouse, donc rien n'est déclaré.

La base de Langfuse

Une nouvelle Stack donne à Langfuse sa propre base langfuse : elle est déclarée ici, et le clickhouse.databaseName de l'Observability y dirige Langfuse (CLICKHOUSE_DB, à partir de langfuse-operator 0.10.1). Langfuse attend que ce cluster signale la base comme présente.

Un Langfuse qui tourne déjà sur la base intégrée default de ClickHouse — toute Stack créée avant cette option — y reste. Le déplacer démarrerait Langfuse sur une base vide, et ses traces existantes disparaîtraient de l'interface. Pour le déplacer volontairement, définissez clickhouse.databaseName sur une Observability autonome en acceptant qu'elle démarre vide (les traces antérieures restent dans default).

Sélectionner une base à la main

Vous câblez un consommateur vous-même ? La base se sélectionne avec le paramètre de requête ?database= sur l'URL HTTP de ClickHouse — pas avec un chemin :

http://forge-ch:8123/?database=waeg     # correct
http://forge-ch:8123/waeg               # faux, en silence

L'interface HTTP de ClickHouse ignore un chemin inconnu et sert sa page d'accueil lisible par un humain : la seconde forme renvoie donc du texte d'aide au lieu d'une erreur — ce que le consommateur signale ensuite comme une réponse illisible, sans que rien ne désigne l'URL.

Comportement par mode

• managed — garantit la présence de l'opérateur ClickHouse et crée sa custom resource. Un ClickHouseCluster requiert un KeeperCluster associé, que le contrôleur émet également.
• adopt — référence une CR ClickHouse in-cluster existante — éventuellement dans un autre namespace (adoption inter-namespaces) — et publie ses identifiants pour les consommateurs. Sans adopt.credentialsSecretRef rien ne peut se connecter : la ressource reste alors Ready=False en nommant ce champ plutôt que de passer Ready sans identifiants. Le cycle de vie n'est pas géré.
• external — câble un secret de connexion ; aucun opérateur n'est installé. databases n'y est pas appliqué.

spec.databases est garanti sur les clusters managed et adopt à chaque réconciliation, et jamais supprimé — voir databases[].

Langfuse peut gérer ClickHouse à votre place

Le langfuse-operator peut gérer ClickHouse et Redis en interne. À moins de référencer un datastore external, le contrôleur Observability opte par défaut pour un ClickHouse/Redis géré par l'opérateur — pour Langfuse seul, un ClickHouseCluster dédié est donc optionnel. Utilisez cette ressource lorsque vous souhaitez gérer ou partager ClickHouse explicitement — ce dont a aussi besoin une Gateway type: waeg en mode de stockage split.

Exemple — managed

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

Exemple — external

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

Sauvegardes et restauration

Définissez managed.backup (mode managé uniquement) pour planifier des sauvegardes vers un stockage objet — le même bloc neutre que Postgres/Mongo (provider: s3 | azure | gcs, destination, identifiants, schedule, retentionPolicy).

L'opérateur émet un CronJob <name>-backup managé qui exécute clickhouse-backup en mode embarqué (BACKUP SQL côté serveur) — il fonctionne donc sur le réseau avec l'opérateur ClickHouse officiel, sans sidecar ni accès au volume de données. backup.enabled: false supprime le 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"

La restauration est une procédure manuelle (depuis un pod avec les mêmes variables d'environnement de sauvegarde) :

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

Status

Champ	Description
host / port	Coordonnées de connexion pour les consommateurs
credentialsSecret	Le Secret portant username / password dans ce namespace
databases[]	Une entrée { name, ready } par base demandée
phase, conditions, observedGeneration	La surface de statut standard