> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurer une instance W&B Weave autogérée
> Déployer et gérer Weave sur votre propre infrastructure
L’auto-hébergement de W\&B Weave vous permet de mieux contrôler son environnement et sa configuration. Cela peut vous aider à créer un environnement plus isolé et à répondre à des exigences supplémentaires en matière de sécurité et de conformité. Ce document vous guide dans le déploiement de tous les composants requis pour exécuter W\&B Weave dans un environnement autogéré à l’aide de l’Altinity ClickHouse Operator.
Les déploiements Weave autogérés s’appuient sur [ClickHouseDB](https://clickhouse.com/) pour gérer leur backend. Ce déploiement utilise :
* **Altinity ClickHouse Operator**: Gestion de ClickHouse de niveau entreprise pour Kubernetes
* **ClickHouse Keeper**: Service de coordination distribué (remplace ZooKeeper)
* **cluster ClickHouse**: Cluster de base de données haute disponibilité pour le stockage des traces
* **S3-Compatible Storage**: Stockage d’objets pour la persistance des données ClickHouse
Pour une architecture de référence détaillée, voir [W\&B Self-Managed Reference Architecture](https://docs.wandb.ai/guides/hosting/self-managed/ref-arch/#models-and-weave).
## Notes importantes sur la configuration
Les exemples de configuration de ce guide sont fournis à titre de référence uniquement. Comme l'environnement Kubernetes de chaque organisation est unique, votre instance auto-hébergée vous obligera probablement à ajuster les éléments suivants :
* **Sécurité et conformité** : les contextes de sécurité, les valeurs `runAsUser`/`fsGroup` et les autres paramètres de sécurité, conformément aux politiques de sécurité de votre organisation et aux exigences de Kubernetes/OpenShift.
* **Dimensionnement des ressources** : les allocations de ressources indiquées sont des points de départ. **Consultez votre équipe W\&B Solutions Architect** pour dimensionner correctement votre déploiement en fonction du volume de traces attendu et des exigences de performances.
* **Spécificités de l'infrastructure** : mettez à jour les classes de stockage, les sélecteurs de nœud et les autres paramètres propres à l'infrastructure afin qu'ils correspondent à votre environnement.
Les configurations de ce guide doivent être considérées comme des modèles, et non comme des solutions prescriptives.
## Architecture
```mermaid theme={null}
graph TD
A["plateforme W&B (wandb)
weave-trace · app/API · console/parquet"] --> B["cluster ClickHouse"]
B --> C["ch-server-0"]
B --> D["ch-server-1"]
B --> E["ch-server-2"]
C --> F["ClickHouse Keeper Cluster
keeper-0
keeper-1
keeper-2"]
D --> F
E --> F
C --> G["S3 Storage
(AWS/MinIO)"]
D --> G
E --> G
```
## Prérequis
Les instances Weave autogérées nécessitent les ressources suivantes :
* **Cluster Kubernetes** : version 1.29+
* **Nœuds Kubernetes** : cluster multinœud (minimum 3 nœuds recommandés pour une haute disponibilité)
* **Classe de stockage** : une StorageClass fonctionnelle pour les volumes persistants (par ex. : `gp3`, `standard`, `nfs-csi`)
* **Bucket S3** : bucket S3 ou compatible S3 préconfiguré avec les autorisations d'accès appropriées
* **Plateforme W\&B** : déjà installée et en fonctionnement (voir le [W\&B Self-Managed Deployment Guide](https://docs.wandb.ai/guides/hosting/hosting-options/self-managed/))
* **Licence W\&B** : licence compatible avec Weave fournie par l'assistance W\&B
Ne prenez pas de décisions de dimensionnement en vous basant uniquement sur cette liste de prérequis. Les besoins en ressources varient considérablement selon le volume de traces et les modes d'utilisation. Voir la section détaillée [Exigences en ressources](#resource-requirements) pour des recommandations explicites sur le dimensionnement du cluster.
### Outils requis
Pour configurer votre instance, vous avez besoin des outils suivants :
* `kubectl` configuré avec un accès au cluster
* `helm` v3.0+
* Identifiants AWS (si vous utilisez S3) ou un accès à un stockage compatible S3
### Exigences réseau
Votre cluster Kubernetes nécessite la configuration réseau suivante :
* Les pods de l’espace de noms `clickhouse` doivent pouvoir communiquer avec les pods de l’espace de noms `wandb`
* Les nœuds ClickHouse doivent pouvoir communiquer entre eux sur les ports 8123, 9000, 9009 et 2181
## Déployez votre instance autogérée de Weave
### Étape 1 : Déployer l’Altinity ClickHouse Operator
L’Altinity ClickHouse Operator gère les installations ClickHouse dans Kubernetes.
#### 1.1 Ajouter le dépôt Helm d’Altinity
```bash theme={null}
helm repo add altinity https://helm.altinity.com
helm repo update
```
#### 1.2 Créez la configuration de l’opérateur
Créez un fichier nommé `ch-operator.yaml` :
```yaml theme={null}
operator:
image:
repository: altinity/clickhouse-operator
# Contexte de sécurité - à ajuster selon les exigences de votre cluster
containerSecurityContext:
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # À mettre à jour selon les politiques de sécurité OpenShift/Kubernetes de votre environnement
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
metrics:
enabled: false
# Remplacement du nom - à personnaliser si nécessaire
nameOverride: "wandb"
```
Les valeurs `containerSecurityContext` indiquées ici conviennent à la plupart des distributions Kubernetes. Pour **OpenShift**, vous devrez peut-être ajuster `runAsUser` et `fsGroup` pour qu’ils correspondent à la plage d’UID attribuée à votre projet.
#### 1.3 Installez l’opérateur
```bash theme={null}
helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
--namespace clickhouse \
--create-namespace \
-f ch-operator.yaml
```
#### 1.4 Vérifier l’installation de l’opérateur
```bash theme={null}
# Vérifier que le pod de l'opérateur est en cours d'exécution
kubectl get pods -n clickhouse
# Sortie attendue :
# NAME READY STATUS RESTARTS AGE
# ch-operator-wandb-xxxxx 1/1 Running 0 30s
# Vérifier la version de l'image de l'opérateur
kubectl get pods -n clickhouse -o jsonpath="{.items[*].spec.containers[*].image}" | \
tr ' ' '\n' | grep -v 'metrics-exporter' | sort -u
# Sortie attendue :
# altinity/clickhouse-operator:0.25.4
```
### Étape 2 : Préparer le stockage S3
ClickHouse nécessite un stockage S3 ou compatible avec S3 pour assurer la persistance des données.
#### 2.1 Créer un bucket S3
Créez un bucket S3 dans votre compte AWS ou chez un fournisseur de stockage compatible S3 :
```bash theme={null}
# Exemple pour AWS
aws s3 mb s3://my-wandb-clickhouse-bucket --region eu-central-1
```
#### 2.2 Configurer les identifiants d’accès à S3
Vous avez deux options pour fournir des identifiants d’accès à S3 :
##### Option A : utiliser des rôles IAM AWS (IRSA - recommandé pour AWS)
Si vos nœuds Kubernetes disposent d’un rôle IAM donnant accès à S3, ClickHouse peut utiliser les métadonnées de l’instance EC2 :
```yaml theme={null}
# Dans ch-server.yaml, définir :
true
```
**Stratégie IAM requise** (jointe au rôle IAM de votre nœud) :
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::my-wandb-clickhouse-bucket",
"arn:aws:s3:::my-wandb-clickhouse-bucket/*"
]
}
]
}
```
##### Option B : Utiliser des clés d’accès
Si vous préférez utiliser des identifiants statiques, créez un secret Kubernetes :
```bash theme={null}
kubectl create secret generic aws-creds \
--namespace clickhouse \
--from-literal aws_access_key=YOUR_ACCESS_KEY \
--from-literal aws_secret_key=YOUR_SECRET_KEY
```
Ensuite, configurez ClickHouse pour utiliser le secret (voir la configuration ch-server.yaml ci-dessous).
### Étape 3 : Déployer ClickHouse Keeper
[ClickHouse Keeper](https://clickhouse.com/docs/guides/sre/keeper/clickhouse-keeper) sert de système de coordination pour la réplication des données et l’exécution des requêtes DDL distribuées.
#### 3.1 Créez la configuration de Keeper
Créez un fichier nommé `ch-keeper.yaml` :
```yaml theme={null}
apiVersion: "clickhouse-keeper.altinity.com/v1"
kind: "ClickHouseKeeperInstallation"
metadata:
name: wandb
namespace: clickhouse
annotations: {}
spec:
defaults:
templates:
podTemplate: default
dataVolumeClaimTemplate: default
templates:
podTemplates:
- name: keeper
metadata:
labels:
app: clickhouse-keeper
spec:
# Contexte de sécurité du pod - à ajuster selon votre environnement
securityContext:
fsGroup: 10001 # À mettre à jour selon les exigences de sécurité de votre cluster
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # Pour OpenShift, utilisez la plage UID assignée à votre projet
seccompProfile:
type: RuntimeDefault
# Anti-affinité pour répartir les keepers sur les nœuds (recommandé pour la HA)
# À personnaliser ou supprimer selon la taille de votre cluster et vos exigences de disponibilité
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: "app"
operator: In
values:
- clickhouse-keeper
topologyKey: "kubernetes.io/hostname"
containers:
- name: clickhouse-keeper
imagePullPolicy: IfNotPresent
image: "clickhouse/clickhouse-keeper:25.10"
# Demandes de ressources - valeurs d'exemple, à ajuster selon la charge de travail
resources:
requests:
memory: "256Mi"
cpu: "0.5"
limits:
memory: "2Gi"
cpu: "1"
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
volumeClaimTemplates:
- name: data
metadata:
labels:
app: clickhouse-keeper
spec:
storageClassName: gp3 # À remplacer par votre StorageClass
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
configuration:
clusters:
- name: keeper # Nom du cluster Keeper - utilisé dans la résolution DNS du service
layout:
replicasCount: 3
templates:
podTemplate: keeper
dataVolumeClaimTemplate: data
settings:
logger/level: "information"
logger/console: "true"
listen_host: "0.0.0.0"
keeper_server/four_letter_word_white_list: "*"
keeper_server/coordination_settings/raft_logs_level: "information"
keeper_server/enable_ipv6: "false"
keeper_server/coordination_settings/async_replication: "true"
```
**Mises à jour importantes de la configuration** :
* **StorageClass** : Mettez à jour `storageClassName: gp3` afin qu’il corresponde à une StorageClass disponible sur votre cluster
* **Contexte de sécurité** : Ajustez les valeurs `runAsUser` et `fsGroup` pour respecter les politiques de sécurité de votre organisation
* **Anti-affinité** : Personnalisez ou supprimez la section `affinity` en fonction de la topologie de votre cluster et de vos exigences de haute disponibilité
* **Ressources** : Les valeurs de CPU et de mémoire sont données à titre d’exemple - consultez les architectes solutions W\&B pour dimensionner correctement
* **Nommage** : Si vous modifiez `metadata.name` ou `configuration.clusters[0].name`, vous **devez mettre à jour** les noms d’hôte Keeper dans ch-server.yaml (Étape 4) en conséquence
#### 3.2 Déployer ClickHouse Keeper
```bash theme={null}
kubectl apply -f ch-keeper.yaml
```
#### 3.3 Vérifier le déploiement de Keeper
```bash theme={null}
# Vérifier les pods Keeper
kubectl get pods -n clickhouse -l app=clickhouse-keeper
# Sortie attendue :
# NAME READY STATUS RESTARTS AGE
# chk-wandb-keeper-0-0-0 1/1 Running 0 2m
# chk-wandb-keeper-0-1-0 1/1 Running 0 2m
# chk-wandb-keeper-0-2-0 1/1 Running 0 2m
# Vérifier les services Keeper
kubectl get svc -n clickhouse | grep keeper
# Les services Keeper doivent apparaître sur le port 2181
```
### Étape 4 : Déployer le cluster ClickHouse
Déployez maintenant le cluster de serveurs ClickHouse qui stockera les données de trace de Weave.
#### 4.1 Créer la configuration du serveur ClickHouse
Créez un fichier nommé `ch-server.yaml` :
```yaml theme={null}
apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
name: wandb
namespace: clickhouse
annotations: {}
spec:
defaults:
templates:
podTemplate: default
dataVolumeClaimTemplate: default
templates:
podTemplates:
- name: clickhouse
metadata:
labels:
app: clickhouse-server
spec:
# Contexte de sécurité du pod - personnalisez selon votre environnement
securityContext:
fsGroup: 10001 # À ajuster selon vos politiques de sécurité
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # Pour OpenShift, utilisez la plage UID attribuée
seccompProfile:
type: RuntimeDefault
# Règle d'anti-affinité - garantit que les serveurs s'exécutent sur des nœuds différents (facultatif mais recommandé)
# À ajuster ou supprimer selon la taille de votre cluster et vos besoins
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: "app"
operator: In
values:
- clickhouse-server
topologyKey: "kubernetes.io/hostname"
containers:
- name: clickhouse
image: clickhouse/clickhouse-server:25.10
# Exemple d'allocation de ressources - à ajuster selon la charge de travail
resources:
requests:
memory: 1Gi
cpu: 1
limits:
memory: 16Gi
cpu: 4
# Identifiants AWS (supprimez cette section si vous utilisez IRSA)
env:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_access_key
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_secret_key
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
volumeClaimTemplates:
- name: data
metadata:
labels:
app: clickhouse-server
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Gi
storageClassName: gp3 # Remplacez par votre StorageClass
configuration:
# Configuration de Keeper (ZooKeeper)
# IMPORTANT : Ces noms d'hôtes DOIVENT correspondre à votre déploiement Keeper de l'étape 3
zookeeper:
nodes:
- host: chk-wandb-keeper-0-0.clickhouse.svc.cluster.local
port: 2181
- host: chk-wandb-keeper-0-1.clickhouse.svc.cluster.local
port: 2181
- host: chk-wandb-keeper-0-2.clickhouse.svc.cluster.local
port: 2181
# Facultatif : décommentez pour ajuster les délais d'expiration si nécessaire
# session_timeout_ms: 30000
# operation_timeout_ms: 10000
# Configuration des Users : https://clickhouse.com/docs/operations/configuration-files#user-settings
# En production, utilisez un mot de passe haché SHA-256 plutôt qu'en texte clair :
# printf "your-password" | sha256sum
# Puis utilisez : weave/password_sha256_hex: à la place de weave/password
users:
weave/password: weave123 # Remplacez par un mot de passe fort avant le déploiement
weave/access_management: 1
weave/profile: default
weave/networks/ip:
- "0.0.0.0/0"
- "::"
# Paramètres du serveur
settings:
disable_internal_dns_cache: 1
# Configuration du cluster
clusters:
- name: weavecluster # Nom du cluster - personnalisable, mais doit correspondre à wandb-cr.yaml
layout:
shardsCount: 1
replicasCount: 3 # Nombre de réplicas - à ajuster selon les exigences de haute disponibilité
templates:
podTemplate: clickhouse
dataVolumeClaimTemplate: data
# Fichiers de configuration
files:
config.d/network_configuration.xml: |
0.0.0.0
::
config.d/logger.xml: |
information
config.d/storage_configuration.xml: |
s3
https://YOUR-BUCKET-NAME.s3.YOUR-REGION.amazonaws.com/s3_disk/{replica}
/var/lib/clickhouse/disks/s3_disk/
true
YOUR-REGION
cache
s3_disk
/var/lib/clickhouse/s3_disk_cache/cache/
40Gi
true
s3_disk_cache
s3_main
```
**Mises à jour critiques de configuration requises** :
1. **StorageClass** : Mettez à jour `storageClassName: gp3` pour qu’il corresponde à la StorageClass de votre cluster
2. **Endpoint S3** : Remplacez `YOUR-BUCKET-NAME` et `YOUR-REGION` par vos valeurs réelles
3. **Taille du cache** : La valeur `40Gi` doit être **inférieure** à la taille du volume persistant (50Gi)
4. **Contexte de sécurité** : Ajustez `runAsUser`, `fsGroup` et les autres paramètres de sécurité pour qu’ils soient conformes aux politiques de votre organisation
5. **Allocation des ressources** : Les valeurs de CPU et de mémoire sont fournies à titre d’exemple uniquement - **consultez votre Solutions Architect W\&B** pour dimensionner correctement en fonction du volume de traces attendu
6. **Règles d’anti-affinité** : Personnalisez-les ou supprimez-les selon la topologie de votre cluster et vos besoins en haute disponibilité
7. **Noms d’hôte Keeper** : Les noms d’hôte des nœuds Keeper **doivent correspondre** à la convention de nommage de votre déploiement Keeper à l’étape 3 (voir « Comprendre le nommage de Keeper » ci-dessous)
8. **Nommage du cluster** : Le nom du cluster `weavecluster` peut être modifié, mais il doit correspondre à la valeur `WF_CLICKHOUSE_REPLICATED_CLUSTER` à l’étape 5
9. **Identifiants** :
* Pour IRSA : Conservez `true` ou utilisez vos clés secrètes mappées sur des variables d’environnement.
#### 4.2 Mettre à jour la configuration S3
Modifiez la section `storage_configuration.xml` de `ch-server.yaml` :
**Exemple avec AWS S3** :
```xml theme={null}
https://my-wandb-clickhouse.s3.eu-central-1.amazonaws.com/s3_disk/{replica}
eu-central-1
```
**Exemple avec MinIO** :
```xml theme={null}
https://minio.example.com:9000/my-bucket/s3_disk/{replica}
us-east-1
```
**Ne supprimez pas `{replica}`.** Cela garantit que chaque réplique ClickHouse écrit dans son propre dossier du bucket.
#### 4.3 Configurez les identifiants d’accès (option B uniquement)
Si vous utilisez **l’option B (clés d’accès)** de l’étape 2, assurez-vous que la section `env` de `ch-server.yaml` fait référence au secret :
```yaml theme={null}
env:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_access_key
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_secret_key
```
Si vous utilisez **l’option A (IRSA)**, supprimez toute la section `env`.
#### 4.4 Comprendre la convention de nommage de Keeper
Les noms d’hôte des nœuds Keeper dans la section `zookeeper.nodes` suivent un format précis en fonction de votre déploiement Keeper à l’étape 3 :
**Format du nom d’hôte** : `chk-{installation-name}-{cluster-name}-{cluster-index}-{replica-index}.{namespace}.svc.cluster.local`
Où :
* `chk` = préfixe ClickHouseKeeperInstallation (fixe)
* `{installation-name}` = le `metadata.name` de ch-keeper.yaml (par ex., `wandb`)
* `{cluster-name}` = le `configuration.clusters[0].name` de ch-keeper.yaml (par ex., `keeper`)
* `{cluster-index}` = index du cluster, généralement `0` pour un cluster unique
* `{replica-index}` = numéro de réplique : `0`, `1`, `2` pour 3 répliques
* `{namespace}` = espace de noms Kubernetes (par ex., `clickhouse`)
**Exemple avec les noms par défaut** :
```
chk-wandb-keeper-0-0.clickhouse.svc.cluster.local
chk-wandb-keeper-0-1.clickhouse.svc.cluster.local
chk-wandb-keeper-0-2.clickhouse.svc.cluster.local
```
**Si vous personnalisez le nom de l’installation Keeper** (par ex., `metadata.name: myweave`) :
```
chk-myweave-keeper-0-0.clickhouse.svc.cluster.local
chk-myweave-keeper-0-1.clickhouse.svc.cluster.local
chk-myweave-keeper-0-2.clickhouse.svc.cluster.local
```
**Si vous personnalisez le nom du cluster Keeper** (par exemple, `clusters[0].name: coordination`) :
```
chk-wandb-coordination-0-0.clickhouse.svc.cluster.local
chk-wandb-coordination-0-1.clickhouse.svc.cluster.local
chk-wandb-coordination-0-2.clickhouse.svc.cluster.local
```
**Pour vérifier vos noms d’hôte Keeper effectifs** :
```bash theme={null}
# Lister les services Keeper pour voir les noms réels
kubectl get svc -n clickhouse | grep keeper
# Lister les pods Keeper pour confirmer le modèle de nommage
kubectl get pods -n clickhouse -l app=clickhouse-keeper
```
Les noms d’hôte Keeper dans `ch-server.yaml` **doivent correspondre exactement** aux noms de service effectivement créés lors du déploiement de Keeper, faute de quoi les serveurs ClickHouse ne pourront pas se connecter au service de coordination.
#### 4.5 Déployer le cluster ClickHouse
```bash theme={null}
kubectl apply -f ch-server.yaml
```
#### 4.6 Vérifier le déploiement de ClickHouse
```bash theme={null}
# Vérifier les pods ClickHouse
kubectl get pods -n clickhouse -l app=clickhouse-server
# Sortie attendue :
# NAME READY STATUS RESTARTS AGE
# chi-wandb-weavecluster-0-0-0 1/1 Running 0 3m
# chi-wandb-weavecluster-0-1-0 1/1 Running 0 3m
# chi-wandb-weavecluster-0-2-0 1/1 Running 0 3m
# Tester la connectivité ClickHouse
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query "SELECT version()"
# Vérifier le statut du cluster
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT cluster, host_name, port FROM system.clusters WHERE cluster='weavecluster'"
```
### Étape 5 : Activer Weave dans la plateforme W\&B
Configurez maintenant la plateforme W\&B afin d’utiliser le cluster ClickHouse pour les traces Weave.
#### 5.1 Rassemblez les informations de connexion à ClickHouse
Vous aurez besoin des éléments suivants :
* **Hôte** : `clickhouse-wandb.clickhouse.svc.cluster.local`
* **Port** : `8123`
* **Utilisateur** : `weave` (tel que configuré dans ch-server.yaml)
* **Mot de passe** : `weave123` (tel que configuré dans ch-server.yaml)
* **Base de données** : `weave` (sera créée automatiquement)
* **Nom du cluster** : `weavecluster` (tel que configuré dans ch-server.yaml)
Le nom d’hôte suit le modèle suivant : `clickhouse-{installation-name}.{namespace}.svc.cluster.local`
#### 5.2 Mettre à jour la ressource personnalisée W\&B
Modifiez la ressource personnalisée (CR) de votre plateforme W\&B pour y ajouter la configuration Weave :
```yaml theme={null}
apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
name: wandb
namespace: wandb
spec:
values:
global:
# ... configuration existante ...
# Ajouter la configuration ClickHouse
clickhouse:
install: false # Déployé séparément
host: clickhouse-wandb.clickhouse.svc.cluster.local
port: 8123
user: weave
password: weave123
database: weave
replicated: true # REQUIS pour une configuration multi-réplica
# Activer Weave Trace
weave-trace:
enabled: true
# Configuration de Weave Trace
weave-trace:
install: true
extraEnv:
WF_CLICKHOUSE_REPLICATED: "true"
WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster"
image:
repository: wandb/weave-trace
tag: 0.74.1
replicaCount: 1
size: "default"
sizing:
default:
autoscaling:
horizontal:
enabled: false
# Exemple d'allocation de ressources - à ajuster en fonction de la charge de travail
resources:
limits:
cpu: 4
memory: "8Gi"
requests:
cpu: 1
memory: "4Gi"
# Contexte de sécurité du pod - à personnaliser selon votre environnement
podSecurityContext:
fsGroup: 10001 # À ajuster selon vos exigences de sécurité
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # Pour OpenShift, utiliser la plage d'UID attribuée
seccompProfile:
type: RuntimeDefault
# Contexte de sécurité du conteneur
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
```
**Paramètres critiques** :
* `clickhouse.replicated: true` - **Requis** lors de l’utilisation de 3 réplicas
* `WF_CLICKHOUSE_REPLICATED: "true"` - **Requis** pour une configuration répliquée
* `WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster"` - **Doit correspondre** au nom du cluster dans ch-server.yaml
Les contextes de sécurité, les allocations de ressources et les autres configurations spécifiques à Kubernetes présentés ci-dessus sont fournis à titre d’exemple. Personnalisez-les en fonction des besoins de votre organisation et consultez votre équipe d’architectes solutions W\&B pour dimensionner correctement les ressources.
#### 5.3 Appliquez la configuration mise à jour
```bash theme={null}
kubectl apply -f wandb-cr.yaml
```
#### 5.4 Vérifier le déploiement de Weave Trace
```bash theme={null}
# Vérifier le statut du pod weave-trace
kubectl get pods -n wandb | grep weave-trace
# Sortie attendue :
# wandb-weave-trace-bc-xxxxx 1/1 Running 0 2m
# Vérifier les journaux weave-trace pour la connexion ClickHouse
kubectl logs -n wandb --tail=50
# Rechercher les messages indiquant une connexion ClickHouse réussie
```
### Étape 6 : Initialiser la base de données Weave
Le service weave-trace créera automatiquement le schéma de la base de données requis lors du premier démarrage.
#### 6.1 Surveiller la migration de la base de données
```bash theme={null}
# Surveiller les journaux weave-trace au démarrage
kubectl logs -n wandb -f
# Rechercher les messages de migration indiquant une initialisation réussie de la base de données
```
#### 6.2 Vérifier la création de la base de données
```bash theme={null}
# Se connecter à ClickHouse et vérifier la base de données
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SHOW DATABASES"
# La base de données 'weave' doit apparaître dans la liste
# Vérifier les tables dans la base de données weave
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SHOW TABLES FROM weave"
```
### Étape 7 : Vérifier que Weave est activé
#### 7.1 Accéder à la console W\&B
Accédez à l’URL de votre instance W\&B depuis un navigateur web.
#### 7.2 Vérifier le statut de la licence Weave
Dans la console W\&B :
1. Accédez à **Top Right Menu** → **Organization Dashboard**
2. Vérifiez que **l’accès à Weave** est activé
#### 7.3 Tester le bon fonctionnement de Weave
Créez un test Python simple pour vérifier que Weave fonctionne :
```python theme={null}
import os
import weave
# Pointer Weave vers votre instance W&B autogérée
os.environ["WANDB_BASE_URL"] = "https://your-wandb-host" # Remplacer par votre URL W&B
weave.init('test-project')
# Créer une fonction tracée simple
@weave.op()
def hello_weave(name: str) -> str:
return f"Hello, {name}!"
# Appeler la fonction
result = hello_weave("World")
print(result)
```
Après avoir exécuté ceci, vérifiez les traces dans l'UI W\&B, sur la page Traces de votre organisation.
## Dépannage
### Problèmes liés à ClickHouse Keeper
**Problème** : les pods Keeper restent bloqués à l’état `Pending`
**Solution** : vérifiez les différentes causes possibles :
1. **Problèmes de PVC et de StorageClass** :
```bash theme={null}
kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse
```
Assurez-vous que votre StorageClass est correctement configurée et qu’elle dispose de capacité disponible.
2. **Anti-affinité et disponibilité des nœuds** :
```bash theme={null}
# Vérifier si les règles d'anti-affinité empêchent la planification
kubectl describe pod -n clickhouse | grep -A 10 "Events:"
# Vérifier les nœuds disponibles et leurs ressources
kubectl get nodes
kubectl describe nodes | grep -A 5 "Allocated resources"
```
Problèmes courants :
* L’anti-affinité nécessite 3 nœuds distincts, mais le cluster en compte moins
* Les nœuds n’ont pas suffisamment de CPU/mémoire pour satisfaire les requêtes des pods
* Les taints des nœuds empêchent la planification des pods
**Solutions** :
* Supprimez ou ajustez les règles d’anti-affinité si vous avez moins de 3 nœuds
* Utilisez `preferredDuringSchedulingIgnoredDuringExecution` au lieu de `requiredDuringSchedulingIgnoredDuringExecution` pour une anti-affinité moins stricte
* Réduisez les requêtes de ressources si les nœuds sont limités
* Ajoutez davantage de nœuds à votre cluster
***
**Problème** : les pods Keeper sont en `CrashLoopBackOff`
**Solution** : consultez les journaux et vérifiez la configuration :
```bash theme={null}
kubectl logs -n clickhouse
```
Problèmes courants :
* Contexte de sécurité incorrect (vérifiez runAsUser, fsGroup)
* Problèmes d’autorisation sur les volumes
* Conflits de ports
* Erreurs de configuration dans ch-keeper.yaml
### Problèmes du serveur ClickHouse
**Problème** : ClickHouse ne parvient pas à se connecter à S3
**Solution** : Vérifiez les identifiants et les autorisations S3 :
```bash theme={null}
# Vérifier si le secret existe (si vous utilisez des clés d'accès)
kubectl get secret aws-creds -n clickhouse
# Vérifier les journaux ClickHouse pour les erreurs S3
kubectl logs -n clickhouse | grep -i s3
# Vérifier l'endpoint S3 dans la configuration du stockage
kubectl get chi wandb -n clickhouse -o yaml | grep -A 10 storage_configuration
```
***
**Problème** : ClickHouse ne parvient pas à se connecter à Keeper
**Solution** : Vérifiez les endpoints et le naming de Keeper :
```bash theme={null}
# Vérifier les services Keeper et leurs noms réels
kubectl get svc -n clickhouse | grep keeper
# Vérifier les pods Keeper pour confirmer le schéma de nommage
kubectl get pods -n clickhouse -l app=clickhouse-keeper
# Comparer avec la configuration zookeeper.nodes dans ch-server.yaml
# Les noms d'hôtes DOIVENT correspondre aux noms de services réels
# Vérifier les journaux ClickHouse pour les erreurs de connexion
kubectl logs -n clickhouse chi-wandb-weavecluster-0-0-0 | grep -i keeper
```
Si la connexion échoue, les noms d’hôte Keeper dans ch-server.yaml ne correspondent probablement pas à votre déploiement Keeper effectif. Voir « Comprendre le nommage de Keeper » à l’étape 4 pour connaître la convention de nommage.
### Problèmes Weave Trace
**Problème** : le pod `weave-trace` ne parvient pas à démarrer
**Solution** : vérifiez la connectivité à ClickHouse :
```bash theme={null}
# Obtenir le nom du pod weave-trace
kubectl get pods -n wandb | grep weave-trace
# Vérifier les journaux weave-trace
kubectl logs -n wandb
# Erreur courante : "connection refused" ou "authentication failed"
# Vérifier que les identifiants ClickHouse dans wandb-cr.yaml correspondent à ch-server.yaml
```
***
**Problème** : Weave n’apparaît pas comme activé dans Console
**Solution** : Vérifiez la configuration :
1. Vérifiez que la licence inclut Weave :
```bash theme={null}
kubectl get secret license-key -n wandb -o jsonpath='{.data.value}' | base64 -d | jq
```
2. Assurez-vous que `weave-trace.enabled: true` et `clickhouse.replicated: true` sont définis dans wandb-cr.yaml
3. Vérifiez les journaux de l’opérateur W\&B :
```bash theme={null}
kubectl logs -n wandb deployment/wandb-controller-manager
```
***
**Problème** : La migration de la base de données échoue
**Solution** : Vérifiez que le nom du cluster correspond :
La variable d’environnement `WF_CLICKHOUSE_REPLICATED_CLUSTER` **doit correspondre** au nom du cluster dans ch-server.yaml :
```yaml theme={null}
# Dans ch-server.yaml :
clusters:
- name: weavecluster # <-- Ce nom
# Doit correspondre dans wandb-cr.yaml :
weave-trace:
extraEnv:
WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" # <-- Cette valeur
```
## Exigences de ressources
Les allocations de ressources ci-dessous sont **donnés uniquement à titre indicatif comme points de départ**. Les besoins réels varient considérablement en fonction des éléments suivants :
* Volume d’ingestion des traces (traces par seconde)
* Schémas de requêtes et niveau de concurrence
* Période de rétention des données
* Nombre d’utilisateurs simultanés
**Consultez toujours votre équipe d’architectes solutions W\&B** afin de déterminer le dimensionnement adapté à votre cas d’usage. Des ressources sous-dimensionnées peuvent entraîner des problèmes de performances, tandis qu’un surdimensionnement engendre des coûts d’infrastructure inutiles.
### Configuration minimale pour la production
| Composant | Réplicas | Requête / limite CPU | Requête / limite mémoire | Stockage |
| ----------------- | ---------- | -------------------- | ------------------------ | ----------- |
| ClickHouse Keeper | 3 | 0.5 / 1 | 256Mi / 2Gi | 10Gi chacun |
| ClickHouse Server | 3 | 1 / 4 | 1Gi / 16Gi | 50Gi chacun |
| Weave Trace | 1 | 1 / 4 | 4Gi / 8Gi | - |
| **Total** | **7 pods** | **\~4.5 / 15 CPU** | **\~7.8Gi / 58Gi** | **180Gi** |
*Convient pour : le développement, les tests ou les environnements de production à faible volume*
### Configuration de production recommandée
Pour les charges de travail de production avec un volume de traces élevé :
| Composant | Réplicas | Requête / limite CPU | Requête / limite mémoire | Stockage |
| ----------------- | ------------ | --------------------- | ------------------------- | ------------ |
| ClickHouse Keeper | 3 | 1 / 2 | 1Gi / 4Gi | 20Gi chacun |
| ClickHouse Server | 3 | 1 / 16 | 8Gi / 64Gi | 200Gi chacun |
| Weave Trace | 2-3 | 1 / 4 | 4Gi / 8Gi | - |
| **Total** | **8-9 pods** | **\~6-9 / 52-64 CPU** | **\~27-33Gi / 204-216Gi** | **660Gi** |
*Convient pour : les environnements de production à fort volume*
Pour les déploiements à très haut volume, contactez votre équipe d’architectes solutions W\&B pour obtenir des recommandations de dimensionnement personnalisées en fonction de votre volume de traces et de vos exigences de performances.
## Configuration avancée
Cette section présente les options de personnalisation des déploiements Weave autogérés, notamment l’augmentation de la capacité de ClickHouse par mise à l’échelle verticale ou mise à l’échelle horizontale, la mise à jour des versions de ClickHouse en modifiant les tags d’image dans les configurations keeper et server, ainsi que la surveillance de l’état de ClickHouse.
Nous vous recommandons de consulter l’équipe d’architectes solutions W\&B lorsque vous apportez des modifications avancées à votre instance, afin de vous assurer qu’elles répondent à vos exigences en matière de performances et de fiabilité.
### Mise à l’échelle de ClickHouse
Pour augmenter la capacité de ClickHouse, vous pouvez :
1. **Mise à l’échelle verticale** : augmente les ressources par pod (approche la plus simple)
```yaml theme={null}
resources:
requests:
memory: 8Gi
cpu: 1
limits:
memory: 64Gi
cpu: 16
```
**Recommandation** : surveillez l’utilisation réelle des ressources et ajustez la mise à l’échelle en conséquence. Pour les déploiements à très grand volume, contactez votre équipe W\&B Solutions Architect.
2. **Mise à l’échelle horizontale** : ajoute plus de réplicas (nécessite une planification rigoureuse)
* L’augmentation du nombre de réplicas nécessite un rééquilibrage des données
* Consultez la documentation de ClickHouse pour la gestion des shards
* **Contactez un W\&B Solutions Architect** avant de mettre en place une mise à l’échelle horizontale en production
### Utiliser différentes versions de ClickHouse
Pour utiliser une autre version de ClickHouse, mettez à jour le tag de l’image dans les deux fichiers `ch-keeper.yaml` et `ch-server.yaml` :
```yaml theme={null}
image: clickhouse/clickhouse-keeper:25.10 # Version du Keeper
image: clickhouse/clickhouse-server:25.10 # Version du serveur
```
Les versions de Keeper et du serveur doivent correspondre, ou la version de Keeper doit être >= à la version du serveur pour garantir la compatibilité.
### Surveillance de ClickHouse
Accédez aux tables système de ClickHouse à des fins de surveillance :
```bash theme={null}
# Vérifier l'utilisation du disque
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT name, path, formatReadableSize(free_space) as free, formatReadableSize(total_space) as total FROM system.disks"
# Vérifier le statut de réplication
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT database, table, is_leader, total_replicas, active_replicas FROM system.replicas WHERE database='weave'"
# Vérifier le statut du serveur ClickHouse
kubectl get pods -n clickhouse -l app=clickhouse-server
```
### Sauvegarde et récupération
Les données ClickHouse sont stockées dans S3, ce qui offre des capacités de sauvegarde natives grâce à la gestion des versions de S3 et aux fonctionnalités de réplication de bucket. Pour les stratégies de sauvegarde propres à votre déploiement, consultez votre équipe W\&B Solutions Architect et référez-vous à la [documentation de sauvegarde ClickHouse](https://clickhouse.com/docs/en/operations/backup).
## Considérations de sécurité
1. **Identifiants** : stockez les mots de passe ClickHouse dans des secrets Kubernetes, et non en texte brut
2. **Politiques réseau** : envisagez de mettre en place des NetworkPolicies pour restreindre l’accès à ClickHouse
3. **RBAC** : assurez-vous que les comptes de service disposent des autorisations minimales requises
4. **Bucket S3** : activez le chiffrement au repos et limitez l’accès au bucket aux rôles IAM nécessaires
5. **TLS** (Facultatif) : en production, activez TLS pour les connexions clientes à ClickHouse
## Mise à niveau
### Mise à niveau de l’opérateur ClickHouse
```bash theme={null}
helm upgrade ch-operator altinity/altinity-clickhouse-operator \
--namespace clickhouse \
-f ch-operator.yaml
```
### Mise à niveau du serveur ClickHouse
Mettez à jour la version de l’image dans `ch-server.yaml`, puis appliquez la modification :
```bash theme={null}
# Modifier ch-server.yaml, changer le tag de l'image
kubectl apply -f ch-server.yaml
# Surveiller les pods
kubectl get pods -n clickhouse
```
### Mise à niveau de Weave Trace
Mettez à jour le tag d’image dans `wandb-cr.yaml`, puis appliquez :
```bash theme={null}
kubectl apply -f wandb-cr.yaml
# Surveiller le redémarrage du pod weave-trace
kubectl get pods -n wandb | grep weave-trace
```
## Ressources supplémentaires
* [Documentation de l’opérateur Altinity ClickHouse](https://docs.altinity.com/altinitykubernetesoperator/)
* [Documentation de ClickHouse](https://clickhouse.com/docs)
* [Documentation de Weave de W\&B](https://docs.wandb.ai/weave)
* [Configuration du stockage S3 de ClickHouse](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#s3-virtual-hosted-style)
## Support
Pour les déploiements en Production ou en cas de problème :
* **Support W\&B** : `support@wandb.com`
* **Architectes solutions** : pour les déploiements à très gros volume, le dimensionnement personnalisé et la planification du déploiement
* **Incluez dans les demandes d'assistance** :
* Journaux de weave-trace, des pods ClickHouse et de l'opérateur
* Version de W\&B, version de ClickHouse, version de Kubernetes
* Informations sur le cluster et volume de traces
## FAQ
**Q : Puis-je utiliser une seule réplique ClickHouse au lieu de 3 ?**
R : Oui, mais ce n’est pas recommandé en Production. Mettez à jour `replicasCount: 1` dans ch-server.yaml et définissez `clickhouse.replicated: false` dans wandb-cr.yaml.
**Q : Puis-je utiliser une autre base de données à la place de ClickHouse ?**
R : Non, Weave Trace nécessite ClickHouse pour ses capacités de stockage colonnaire haute performance.
**Q : De combien de stockage S3 aurai-je besoin ?**
R : Les besoins en stockage S3 dépendent de votre volume de traces, de la durée de rétention et de la compression des données. Surveillez votre utilisation réelle après le déploiement et ajustez en conséquence. Le format colonnaire de ClickHouse offre une excellente compression pour les données de trace.
**Q : Dois-je configurer le nom de `database` dans ClickHouse ?**
R : Non, la base de données `weave` sera créée automatiquement par le service weave-trace lors du démarrage initial.
**Q : Que faire si le nom de mon cluster n’est pas `weavecluster` ?**
R : Vous devez définir la variable d’environnement `WF_CLICKHOUSE_REPLICATED_CLUSTER` pour qu’elle corresponde au nom de votre cluster, sinon les migrations de base de données échoueront.
**Q : Dois-je utiliser exactement les contextes de sécurité indiqués dans les exemples ?**
R : Non. Les contextes de sécurité (runAsUser, fsGroup, etc.) fournis dans ce guide sont des exemples de référence. Vous devez les adapter pour respecter les politiques de sécurité de votre organisation, en particulier pour les clusters OpenShift, qui imposent des plages UID/GID spécifiques.
**Q : Comment savoir si mon cluster ClickHouse est correctement dimensionné ?**
R : Contactez votre équipe d’architectes solutions W\&B en indiquant votre volume de traces prévu et vos modèles d’utilisation. Elle vous fournira des recommandations de dimensionnement spécifiques. Surveillez l’utilisation des ressources de votre déploiement et ajustez si nécessaire.
**Q : Puis-je personnaliser les conventions de nommage utilisées dans les exemples ?**
R : Oui, mais vous devez rester cohérent dans tous les composants :
1. **Noms des ClickHouse Keeper** → Doivent correspondre aux noms d’hôte des nœuds Keeper dans la section `zookeeper.nodes` de ch-server.yaml
2. **Nom du cluster ClickHouse** (`weavecluster`) → Doit correspondre à `WF_CLICKHOUSE_REPLICATED_CLUSTER` dans wandb-cr.yaml
3. **Nom de l’installation ClickHouse** → Affecte le nom d’hôte du service utilisé par weave-trace
Voir la section « Understanding Keeper Naming » à l’étape 4 pour plus de détails sur le schéma de nommage et sur la façon de vérifier vos noms réels.
**Q : Que faire si mon cluster utilise des exigences d’anti-affinité différentes ?**
R : Les règles d’anti-affinité présentées sont des recommandations pour assurer une haute disponibilité. Ajustez-les ou supprimez-les en fonction de la taille de votre cluster, de sa topologie et de vos exigences de disponibilité. Pour les petits clusters ou les environnements de développement, vous n’aurez peut-être pas besoin de règles d’anti-affinité.