Configurer une instance W&B Weave autogérée - Weights & Biases Documentation

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 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.

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

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)
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 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

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 :

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

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

# 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 :

# 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 :

# Dans ch-server.yaml, définir :
<use_environment_credentials>true</use_environment_credentials>

Stratégie IAM requise (jointe au rôle IAM de votre nœud) :

{
  "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 :

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 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 :

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

kubectl apply -f ch-keeper.yaml

3.3 Vérifier le déploiement de Keeper

# 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 :

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: <hash> à 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: |
        <clickhouse>
            <listen_host>0.0.0.0</listen_host>
            <listen_host>::</listen_host>
        </clickhouse>

      config.d/logger.xml: |
        <clickhouse>
            <logger>
                <level>information</level>
            </logger>
        </clickhouse>

      config.d/storage_configuration.xml: |
        <clickhouse>
            <storage_configuration>
                <disks>
                    <s3_disk>
                        <type>s3</type>
                        <!-- Mettez à jour avec l'endpoint et la région de votre bucket S3 -->
                        <endpoint>https://YOUR-BUCKET-NAME.s3.YOUR-REGION.amazonaws.com/s3_disk/{replica}</endpoint>
                        <metadata_path>/var/lib/clickhouse/disks/s3_disk/</metadata_path>
                        <use_environment_credentials>true</use_environment_credentials>
                        <region>YOUR-REGION</region>
                    </s3_disk>
                    <s3_disk_cache>
                        <type>cache</type>
                        <disk>s3_disk</disk>
                        <path>/var/lib/clickhouse/s3_disk_cache/cache/</path>
                        <!-- La taille du cache DOIT être inférieure à celle du volume persistant -->
                        <max_size>40Gi</max_size>
                        <cache_on_write_operations>true</cache_on_write_operations>
                    </s3_disk_cache>
                </disks>
                <policies>
                    <s3_main>
                        <volumes>
                            <main>
                                <disk>s3_disk_cache</disk>
                            </main>
                        </volumes>
                    </s3_main>
                </policies>
            </storage_configuration>
            <merge_tree>
                <storage_policy>s3_main</storage_policy>
            </merge_tree>
        </clickhouse>

Mises à jour critiques de configuration requises :

StorageClass : Mettez à jour storageClassName: gp3 pour qu’il corresponde à la StorageClass de votre cluster
Endpoint S3 : Remplacez YOUR-BUCKET-NAME et YOUR-REGION par vos valeurs réelles
Taille du cache : La valeur <max_size>40Gi</max_size> doit être inférieure à la taille du volume persistant (50Gi)
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
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
Règles d’anti-affinité : Personnalisez-les ou supprimez-les selon la topologie de votre cluster et vos besoins en haute disponibilité
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)
Nommage du cluster : Le nom du cluster weavecluster peut être modifié, mais il doit correspondre à la valeur WF_CLICKHOUSE_REPLICATED_CLUSTER à l’étape 5
Identifiants :
- Pour IRSA : Conservez <use_environment_credentials>true</use_environment_credentials> 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 :

<endpoint>https://my-wandb-clickhouse.s3.eu-central-1.amazonaws.com/s3_disk/{replica}</endpoint>
<region>eu-central-1</region>

Exemple avec MinIO :

<endpoint>https://minio.example.com:9000/my-bucket/s3_disk/{replica}</endpoint>
<region>us-east-1</region>

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 :

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 :

# 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

kubectl apply -f ch-server.yaml

4.6 Vérifier le déploiement de ClickHouse

# 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 :

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

kubectl apply -f wandb-cr.yaml

5.4 Vérifier le déploiement de Weave Trace

# 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 <weave-trace-pod-name> --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

# Surveiller les journaux weave-trace au démarrage
kubectl logs -n wandb <weave-trace-pod-name> -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

# 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 :

Accédez à Top Right Menu → Organization Dashboard
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 :

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 :

Problèmes de PVC et de StorageClass :

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.

Anti-affinité et disponibilité des nœuds :

# Vérifier si les règles d'anti-affinité empêchent la planification
kubectl describe pod -n clickhouse <pod-name> | 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 :

kubectl logs -n clickhouse <keeper-pod-name>

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 :

# 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 <clickhouse-pod-name> | 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 :

# 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 :

# 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 <weave-trace-pod-name>

# 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 :

Vérifiez que la licence inclut Weave :

kubectl get secret license-key -n wandb -o jsonpath='{.data.value}' | base64 -d | jq

Assurez-vous que weave-trace.enabled: true et clickhouse.replicated: true sont définis dans wandb-cr.yaml

Vérifiez les journaux de l’opérateur W&B :

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 :

# 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 :

Mise à l’échelle verticale : augmente les ressources par pod (approche la plus simple)
```
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.
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 :

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 :

# 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.

Considérations de sécurité

Identifiants : stockez les mots de passe ClickHouse dans des secrets Kubernetes, et non en texte brut
Politiques réseau : envisagez de mettre en place des NetworkPolicies pour restreindre l’accès à ClickHouse
RBAC : assurez-vous que les comptes de service disposent des autorisations minimales requises
Bucket S3 : activez le chiffrement au repos et limitez l’accès au bucket aux rôles IAM nécessaires
TLS (Facultatif) : en production, activez TLS pour les connexions clientes à ClickHouse

Mise à niveau

Mise à niveau de l’opérateur ClickHouse

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 :

# 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 :

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

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 :

Noms des ClickHouse Keeper → Doivent correspondre aux noms d’hôte des nœuds Keeper dans la section zookeeper.nodes de ch-server.yaml
Nom du cluster ClickHouse (weavecluster) → Doit correspondre à WF_CLICKHOUSE_REPLICATED_CLUSTER dans wandb-cr.yaml
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é.

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

​Notes importantes sur la configuration

​Architecture

​Prérequis

​Outils requis

​Exigences réseau

​Déployez votre instance autogérée de Weave

​Étape 1 : Déployer l’Altinity ClickHouse Operator

​1.1 Ajouter le dépôt Helm d’Altinity

​1.2 Créez la configuration de l’opérateur

​1.3 Installez l’opérateur

​1.4 Vérifier l’installation de l’opérateur

​Étape 2 : Préparer le stockage S3

​2.1 Créer un bucket S3

​2.2 Configurer les identifiants d’accès à S3

Option A : utiliser des rôles IAM AWS (IRSA - recommandé pour AWS)

Option B : Utiliser des clés d’accès

​Étape 3 : Déployer ClickHouse Keeper

​3.1 Créez la configuration de Keeper

​3.2 Déployer ClickHouse Keeper

​3.3 Vérifier le déploiement de Keeper

​Étape 4 : Déployer le cluster ClickHouse

​4.1 Créer la configuration du serveur ClickHouse

​4.2 Mettre à jour la configuration S3

​4.3 Configurez les identifiants d’accès (option B uniquement)

​4.4 Comprendre la convention de nommage de Keeper

​4.5 Déployer le cluster ClickHouse

​4.6 Vérifier le déploiement de ClickHouse

​Étape 5 : Activer Weave dans la plateforme W&B

​5.1 Rassemblez les informations de connexion à ClickHouse

​5.2 Mettre à jour la ressource personnalisée W&B

​5.3 Appliquez la configuration mise à jour

​5.4 Vérifier le déploiement de Weave Trace

​Étape 6 : Initialiser la base de données Weave

​6.1 Surveiller la migration de la base de données

​6.2 Vérifier la création de la base de données

​Étape 7 : Vérifier que Weave est activé

​7.1 Accéder à la console W&B

​7.2 Vérifier le statut de la licence Weave

​7.3 Tester le bon fonctionnement de Weave

​Dépannage

​Problèmes liés à ClickHouse Keeper

​Problèmes du serveur ClickHouse

​Problèmes Weave Trace

​Exigences de ressources

​Configuration minimale pour la production

​Configuration de production recommandée

​Configuration avancée

​Mise à l’échelle de ClickHouse

​Utiliser différentes versions de ClickHouse

​Surveillance de ClickHouse

​Sauvegarde et récupération

​Considérations de sécurité

​Mise à niveau

​Mise à niveau de l’opérateur ClickHouse

​Mise à niveau du serveur ClickHouse

​Mise à niveau de Weave Trace

​Ressources supplémentaires

​Support

​FAQ

Notes importantes sur la configuration

Architecture

Prérequis

Outils requis

Exigences réseau

Déployez votre instance autogérée de Weave

Étape 1 : Déployer l’Altinity ClickHouse Operator

1.1 Ajouter le dépôt Helm d’Altinity

1.2 Créez la configuration de l’opérateur

1.3 Installez l’opérateur

1.4 Vérifier l’installation de l’opérateur

Étape 2 : Préparer le stockage S3

2.1 Créer un bucket S3

2.2 Configurer les identifiants d’accès à S3

Étape 3 : Déployer ClickHouse Keeper

3.1 Créez la configuration de Keeper

3.2 Déployer ClickHouse Keeper

3.3 Vérifier le déploiement de Keeper

Étape 4 : Déployer le cluster ClickHouse

4.1 Créer la configuration du serveur ClickHouse

4.2 Mettre à jour la configuration S3

4.3 Configurez les identifiants d’accès (option B uniquement)

4.4 Comprendre la convention de nommage de Keeper

4.5 Déployer le cluster ClickHouse

4.6 Vérifier le déploiement de ClickHouse

Étape 5 : Activer Weave dans la plateforme W&B

5.1 Rassemblez les informations de connexion à ClickHouse

5.2 Mettre à jour la ressource personnalisée W&B

5.3 Appliquez la configuration mise à jour

5.4 Vérifier le déploiement de Weave Trace

Étape 6 : Initialiser la base de données Weave

6.1 Surveiller la migration de la base de données

6.2 Vérifier la création de la base de données

Étape 7 : Vérifier que Weave est activé

7.1 Accéder à la console W&B

7.2 Vérifier le statut de la licence Weave

7.3 Tester le bon fonctionnement de Weave

Dépannage

Problèmes liés à ClickHouse Keeper

Problèmes du serveur ClickHouse

Problèmes Weave Trace

Exigences de ressources

Configuration minimale pour la production

Configuration de production recommandée

Configuration avancée

Mise à l’échelle de ClickHouse

Utiliser différentes versions de ClickHouse

Surveillance de ClickHouse

Sauvegarde et récupération

Considérations de sécurité

Mise à niveau

Mise à niveau de l’opérateur ClickHouse

Mise à niveau du serveur ClickHouse

Mise à niveau de Weave Trace

Ressources supplémentaires

Support

FAQ