セルフマネージドの W&B Weave インスタンスを設定する

W&B Weave をセルフホストすると、環境や設定をより細かく制御できます。これにより、より分離された環境を構築し、追加のセキュリティ要件やコンプライアンス要件に対応しやすくなります。このドキュメントでは、Altinity ClickHouse Operator を使用して、セルフマネージド環境で W&B Weave を実行するために必要なすべてのコンポーネントをデプロイする方法を説明します。セルフマネージドの Weave デプロイでは、バックエンドの管理に ClickHouseDB を使用します。このデプロイでは、次を使用します。

Altinity ClickHouse Operator: Kubernetes 向けのエンタープライズグレードの ClickHouse 管理
ClickHouse Keeper: 分散コーディネーションサービス (ZooKeeper の代替)
ClickHouse Cluster: トレース保存用の高可用性データベースクラスター
S3-Compatible Storage: ClickHouse データを永続化するためのオブジェクトストレージ

詳細なリファレンスアーキテクチャについては、W&B Self-Managed Reference Architectureを参照してください。

重要なセットアップ上の注意

このガイドの設定例は、あくまで参考用です。各組織の Kubernetes 環境はそれぞれ異なるため、セルフホスト環境では以下の点を調整する必要がある可能性が高くなります。

Security & Compliance: 組織のセキュリティポリシーおよび Kubernetes/OpenShift の要件に合わせて、セキュリティコンテキスト、runAsUser/fsGroup の値、その他のセキュリティ設定を調整してください。
Resource Sizing: ここに示すリソース割り当ては出発点にすぎません。想定されるトレース量とパフォーマンス要件に基づく適切なサイジングについては、W&B Solutions Architect チームに相談してください。
Infrastructure Specifics: ストレージクラス、ノードセレクター、その他のインフラストラクチャー固有の設定を、使用する環境に合わせて更新してください。

このガイドの設定は、規定のソリューションではなく、テンプレートとして扱ってください。

アーキテクチャ

前提条件

セルフマネージドのWeaveインスタンスには、以下のリソースが必要です。

Kubernetes クラスター: バージョン 1.29 以上
Kubernetes ノード: マルチノードクラスター (高可用性のため、少なくとも 3 ノードを推奨)
ストレージクラス: 永続ボリューム用の有効な StorageClass (例: gp3, standard, nfs-csi)
S3 バケット: 適切なアクセス権限が設定された、事前構成済みの S3 または S3 互換バケット
W&B Platform: すでにインストールおよび稼働していること (W&B Self-Managed デプロイガイドを参照)
W&B ライセンス: W&B サポートが提供する Weave 対応ライセンス

この前提条件の一覧だけを基にサイジングを判断しないでください。必要なリソースは、トレース量や使用パターンによって大きく異なります。クラスターのサイジングに関する具体的なガイダンスについては、詳細なリソース要件セクションを参照してください。

必須ツール

インスタンスを設定するには、次のツールが必要です。

クラスターにアクセスできるよう設定されたkubectl
helm v3.0+
AWS認証情報 (S3を使用する場合) 、またはS3互換ストレージへのアクセス

ネットワーク要件

Kubernetes クラスターでは、以下のネットワーク設定が必要です。

clickhouse namespace 内の Pod は、wandb namespace 内の Pod と通信できる必要があります
ClickHouse ノード同士は、ポート 8123、9000、9009、2181 を介して通信できる必要があります

セルフマネージドWeaveインスタンスをデプロイする

Step 1: Altinity ClickHouse Operator をデプロイする

Altinity ClickHouse Operator は、Kubernetes 上の ClickHouse インストールを管理します。

1.1 Altinity Helmリポジトリを追加する

helm repo add altinity https://helm.altinity.com
helm repo update

1.2 Operator の設定を作成

ch-operator.yaml という名前のファイルを作成します。

operator:
  image:
    repository: altinity/clickhouse-operator

  # セキュリティコンテキスト - クラスターの要件に応じて調整してください
  containerSecurityContext:
    runAsGroup: 0
    runAsNonRoot: true
    runAsUser: 10001 # OpenShift/Kubernetes のセキュリティポリシーに合わせて更新してください
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL
    privileged: false
    readOnlyRootFilesystem: false

metrics:
  enabled: false

# 名前のオーバーライド - 必要に応じてカスタマイズしてください
nameOverride: "wandb"

ここで示している containerSecurityContext の値は、ほとんどの Kubernetes ディストリビューションで使用できます。OpenShift では、プロジェクトに割り当てられている UID 範囲に合わせて runAsUser と fsGroup を調整する必要がある場合があります。

1.3 operatorをインストールする

helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  --create-namespace \
  -f ch-operator.yaml

1.4 operator がインストールされていることを確認する

# operator の pod が実行中であることを確認する
kubectl get pods -n clickhouse

# 期待される出力:
# NAME                                 READY   STATUS    RESTARTS   AGE
# ch-operator-wandb-xxxxx              1/1     Running   0          30s

# operator のイメージバージョンを確認する
kubectl get pods -n clickhouse -o jsonpath="{.items[*].spec.containers[*].image}" | \
  tr ' ' '\n' | grep -v 'metrics-exporter' | sort -u

# 期待される出力:
# altinity/clickhouse-operator:0.25.4

Step 2: S3ストレージを準備する

ClickHouse では、データの永続化に S3 または S3 互換ストレージが必要です。

2.1 S3バケットを作成する

AWS アカウントまたは S3 互換のストレージプロバイダーで S3バケットを作成します。

# AWSの例
aws s3 mb s3://my-wandb-clickhouse-bucket --region eu-central-1

2.2 S3認証情報を設定する

S3へのアクセス認証情報を指定する方法は2つあります。

オプション A: AWS IAM ロールを使用する (IRSA - AWS では推奨)

Kubernetes ノードに S3 へのアクセス権を持つ IAM ロールがある場合、ClickHouse は EC2 インスタンスメタデータを使用できます。

# ch-server.yaml で以下を設定:
<use_environment_credentials>true</use_environment_credentials>

必須の IAM ポリシー (ノードの IAM ロールにアタッチ) :

{
  "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/*"
      ]
    }
  ]
}

オプション B: アクセスキーを使用する

静的な認証情報を使用する場合は、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

次に、ClickHouse がそのシークレットを使用するように設定します (以下の ch-server.yaml の設定を参照) 。

Step 3: ClickHouse Keeper をデプロイする

ClickHouse Keeper は、データレプリケーションと分散 DDL クエリの実行を調整するためのシステムです。

3.1 Keeper の設定を作成する

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:
          # Podセキュリティコンテキスト - 環境に合わせて調整してください
          securityContext:
            fsGroup: 10001 # クラスターのセキュリティ要件に合わせて更新してください
            fsGroupChangePolicy: Always
            runAsGroup: 0
            runAsNonRoot: true
            runAsUser: 10001 # OpenShiftの場合は、プロジェクトに割り当てられたUID範囲を使用してください
            seccompProfile:
              type: RuntimeDefault

          # ノード間にKeeperを分散させるためのアンチアフィニティ（HA構成に推奨）
          # クラスターのサイズと可用性要件に応じてカスタマイズまたは削除してください
          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"
              # リソースリクエスト - 参考値です。ワークロードに応じて調整してください
              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 # 使用するStorageClassに変更してください
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 10Gi

  configuration:
    clusters:
      - name: keeper # KeeperクラスターのName - サービスDNS命名に使用されます
        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"

重要な設定の更新事項:

StorageClass: クラスターで使用可能な StorageClass に合わせて、storageClassName: gp3 を更新します
セキュリティコンテキスト: 組織のセキュリティポリシーに準拠するよう、runAsUser と fsGroup の値を調整します
Anti-Affinity: クラスターのトポロジーと HA 要件に応じて、affinity セクションをカスタマイズするか削除します
リソース: CPU/メモリの値はあくまで例です。適切なサイジングについては、W&B Solutions Architects に相談してください
命名: metadata.name または configuration.clusters[0].name を変更する場合は、それに合わせて ch-server.yaml (Step 4) 内の Keeper ホスト名を必ず更新してください

3.2 ClickHouse Keeperをデプロイする

kubectl apply -f ch-keeper.yaml

3.3 Keeper のデプロイを確認する

# Keeper podを確認する
kubectl get pods -n clickhouse -l app=clickhouse-keeper

# 期待される出力:
# 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

# Keeperサービスを確認する
kubectl get svc -n clickhouse | grep keeper

# ポート2181でKeeperサービスが表示されることを確認する

Step 4: ClickHouse Cluster をデプロイする

次に、Weave Trace Data を保存する ClickHouse サーバークラスタをデプロイします。

4.1 ClickHouse サーバーの設定を作成する

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:
          # Podセキュリティコンテキスト - 環境に合わせてカスタマイズしてください
          securityContext:
            fsGroup: 10001 # セキュリティポリシーに合わせて調整してください
            fsGroupChangePolicy: Always
            runAsGroup: 0
            runAsNonRoot: true
            runAsUser: 10001 # OpenShiftの場合は、割り当てられたUID範囲を使用してください
            seccompProfile:
              type: RuntimeDefault

          # アンチアフィニティルール - サーバーを異なるノードで実行するために使用します（任意ですが推奨）
          # クラスターのサイズと要件に応じて調整または削除してください
          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
              # リソース割り当ての例 - ワークロードに応じて調整してください
              resources:
                requests:
                  memory: 1Gi
                  cpu: 1
                limits:
                  memory: 16Gi
                  cpu: 4

              # AWSの認証情報（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 # 使用するStorageClassに変更してください

  configuration:
    # Keeper（ZooKeeper）の設定
    # 重要: これらのホスト名はStep 3のKeeperデプロイと一致している必要があります
    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
      # 任意: 必要に応じてタイムアウトを調整する場合はコメントを解除してください
      # session_timeout_ms: 30000
      # operation_timeout_ms: 10000

    # Usersの設定: https://clickhouse.com/docs/operations/configuration-files#user-settings
    # 本番環境では、平文の代わりにSHA-256ハッシュ化されたパスワードを使用してください:
    # printf "your-password" | sha256sum
    # その場合: weave/password の代わりに weave/password_sha256_hex: <hash> を使用してください
    users:
      weave/password: weave123  # デプロイ前に強力なパスワードに置き換えてください
      weave/access_management: 1
      weave/profile: default
      weave/networks/ip:
        - "0.0.0.0/0"
        - "::"

    # サーバー設定
    settings:
      disable_internal_dns_cache: 1

    # クラスター設定
    clusters:
      - name: weavecluster # クラスター名 - カスタマイズ可能ですが、wandb-cr.yamlと一致している必要があります
        layout:
          shardsCount: 1
          replicasCount: 3 # レプリカ数 - HA要件に応じて調整してください
        templates:
          podTemplate: clickhouse
          dataVolumeClaimTemplate: data

    # 設定ファイル
    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>
                        <!-- 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>
                        <!-- キャッシュサイズは永続ボリュームより小さくする必要があります -->
                        <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>

重要な設定更新が必要です:

StorageClass: storageClassName: gp3 を、クラスターの StorageClass に合うよう更新します
S3 Endpoint: YOUR-BUCKET-NAME と YOUR-REGION を実際の値に置き換えます
Cache Size: <max_size>40Gi</max_size> は永続ボリュームのサイズ (50Gi) より 小さく する必要があります
セキュリティコンテキスト: runAsUser、fsGroup、およびその他のセキュリティ設定を、組織のポリシーに合わせて調整します
Resource Allocation: CPU/メモリの値はあくまで例です。想定されるトレース量に基づく適切なサイジングについては、W&B Solutions Architect に相談してください
Anti-Affinity Rules: クラスターのトポロジーと高可用性の要件に応じて、カスタマイズするか削除します
Keeper Hostnames: Keeper ノードのホスト名は、Step 3 の Keeper デプロイの命名と一致している必要があります (以下の「Understanding Keeper Naming」を参照)
Cluster Naming: クラスター名 weavecluster は変更できますが、Step 5 の WF_CLICKHOUSE_REPLICATED_CLUSTER の値と一致している必要があります
Credentials:
- IRSA の場合: <use_environment_credentials>true</use_environment_credentials> をそのまま使用するか、環境変数にマッピングしたシークレットキーを使用してください。

4.2 S3 の設定を更新する

ch-server.yaml の storage_configuration.xml セクションを編集します。 AWS S3 の設定例:

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

MinIOの例:

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

{replica} は削除しないでください。 これにより、各 ClickHouse レプリカが bucket 内のそれぞれ専用のフォルダに書き込むようになります。

4.3 認証情報を設定する (Option B のみ)

Step 2 の Option B (アクセスキー) を使用する場合は、ch-server.yaml の env セクションでそのシークレットを参照していることを確認してください。

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

**オプション A (IRSA) **を使用する場合は、envセクション全体を削除してください。

4.4 Keeper の命名規則を理解する

zookeeper.nodes セクションの Keeper ノードのホスト名は、Step 3 で行った Keeper のデプロイに応じて、特定のパターンに従います。 ホスト名パターン: chk-{installation-name}-{cluster-name}-{cluster-index}-{replica-index}.{namespace}.svc.cluster.local 各要素:

chk = ClickHouseKeeperInstallation のプレフィックス (固定)
{installation-name} = ch-keeper.yaml の metadata.name (例: wandb)
{cluster-name} = ch-keeper.yaml の configuration.clusters[0].name (例: keeper)
{cluster-index} = クラスターのインデックス。単一クラスターでは通常 0
{replica-index} = レプリカ番号。3 レプリカの場合は 0、1、2
{namespace} = Kubernetes の名前空間 (例: clickhouse)

デフォルト名を使用した例:

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

Keeper のインストール名を独自に設定している場合 (例: 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

Keeper クラスター名を変更する場合 (例: 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

実際のKeeperホスト名を確認するには:

# 実際の名前を確認するためにKeeperサービスを一覧表示する
kubectl get svc -n clickhouse | grep keeper

# 命名パターンを確認するためにKeeperポッドを一覧表示する
kubectl get pods -n clickhouse -l app=clickhouse-keeper

ch-server.yaml 内の Keeper ホスト名は、Keeper のデプロイで実際に作成されるサービス名と完全に一致している必要があります。一致していないと、ClickHouse サーバーはコーディネーションサービスに接続できません。

4.5 ClickHouse クラスターをデプロイする

kubectl apply -f ch-server.yaml

4.6 ClickHouse のデプロイを確認する

# ClickHouse ポッドを確認する
kubectl get pods -n clickhouse -l app=clickhouse-server

# 期待される出力:
# 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

# ClickHouse の接続性をテストする
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password weave123 --query "SELECT version()"

# クラスターのステータスを確認する
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'"

Step 5: W&B Platform で Weave を有効にする

次に、Weave のトレースで ClickHouse クラスターを使用するように、W&B Platform を設定します。

5.1 ClickHouse の接続情報を確認する

必要な情報は次のとおりです。

ホスト: clickhouse-wandb.clickhouse.svc.cluster.local
ポート: 8123
ユーザー: weave (ch-server.yaml で設定)
パスワード: weave123 (ch-server.yaml で設定)
データベース: weave (自動的に作成されます)
クラスタ名: weavecluster (ch-server.yaml で設定)

ホスト名は次のパターンに従います: clickhouse-{installation-name}.{namespace}.svc.cluster.local

5.2 W&B Custom Resource を更新する

Weave の設定を追加するには、W&B Platform の Custom Resource (CR) を編集します。

apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
  name: wandb
  namespace: wandb
spec:
  values:
    global:
      # ... 既存の設定 ...

      # ClickHouse 設定を追加
      clickhouse:
        install: false # 別途デプロイ済み
        host: clickhouse-wandb.clickhouse.svc.cluster.local
        port: 8123
        user: weave
        password: weave123
        database: weave
        replicated: true # マルチレプリカ構成では必須

      # Weave Trace を有効化
      weave-trace:
        enabled: true

    # 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
          # リソース割り当ての例 - ワークロードに応じて調整
          resources:
            limits:
              cpu: 4
              memory: "8Gi"
            requests:
              cpu: 1
              memory: "4Gi"
      # Pod セキュリティコンテキスト - 環境に合わせてカスタマイズ
      podSecurityContext:
        fsGroup: 10001 # セキュリティ要件に応じて調整
        fsGroupChangePolicy: Always
        runAsGroup: 0
        runAsNonRoot: true
        runAsUser: 10001 # OpenShift の場合は割り当て済み UID 範囲を使用
        seccompProfile:
          type: RuntimeDefault
      # コンテナーセキュリティコンテキスト
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        privileged: false
        readOnlyRootFilesystem: false

重要な設定:

clickhouse.replicated: true - 3 レプリカを使用する場合は必須
WF_CLICKHOUSE_REPLICATED: "true" - レプリケーション構成では必須
WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" - ch-server.yaml のクラスター名と 一致する必要があります

上記のセキュリティコンテキスト、リソース割り当て、およびその他の Kubernetes 固有の設定は参考例です。組織の要件に合わせて適宜カスタマイズし、適切なリソースサイジングについては W&B Solutions Architect チームに相談してください。

5.3 更新した設定を適用する

kubectl apply -f wandb-cr.yaml

5.4 Weave Trace のデプロイを確認する

# weave-trace podのステータスを確認する
kubectl get pods -n wandb | grep weave-trace

# 期待される出力:
# wandb-weave-trace-bc-xxxxx   1/1     Running   0          2m

# ClickHouse接続に関するweave-traceのログを確認する
kubectl logs -n wandb <weave-trace-pod-name> --tail=50

# ClickHouse接続成功のメッセージを確認する

Step 6: Weave データベースを初期化する

weave-trace サービスは、初回起動時に必要なデータベーススキーマを自動的に作成します。

6.1 データベースの移行を監視する

# 起動中にweave-traceのログを監視する
kubectl logs -n wandb <weave-trace-pod-name> -f

# データベースの初期化が成功したことを示すマイグレーションメッセージを確認する

6.2 データベースが作成されたことを確認する

# ClickHouseに接続してデータベースを確認する
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password weave123 --query \
  "SHOW DATABASES"

# 'weave' データベースが一覧に表示されることを確認する

# weave データベースのテーブルを確認する
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password weave123 --query \
  "SHOW TABLES FROM weave"

Step 7: Weave が有効であることを確認する

7.1 W&B Console にアクセスする

Webブラウザで W&B インスタンスの URL にアクセスします。

7.2 Weave ライセンスの状態を確認する

W&B Console で:

Top Right Menu → Organization Dashboard に移動します
Weave access が有効になっていることを確認します

7.3 Weave の機能をテストする

Weave が正常に動作していることを確認するため、簡単な Python テストを作成します。

import os
import weave

# WeaveをセルフマネージドのW&Bインスタンスに向ける
os.environ["WANDB_BASE_URL"] = "https://your-wandb-host"  # W&BのURLに置き換えてください

weave.init('test-project')

# シンプルなトレース付き関数を作成する
@weave.op()
def hello_weave(name: str) -> str:
    return f"Hello, {name}!"

# 関数を呼び出す
result = hello_weave("World")
print(result)

これを実行した後、組織のトレースページで W&B UI のトレースを確認してください。

トラブルシューティング

ClickHouse Keeper の問題

問題: Keeper pod が Pending 状態のままになっている 解決策: 考えられる複数の原因を確認します。

PVC と StorageClass の問題:

kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse

StorageClass が正しく設定され、十分な空き容量があることを確認してください。

アンチアフィニティとノードの可用性:

# アンチアフィニティルールがスケジューリングを妨げていないか確認する
kubectl describe pod -n clickhouse <pod-name> | grep -A 10 "Events:"

# 利用可能なノードとそのリソースを確認する
kubectl get nodes
kubectl describe nodes | grep -A 5 "Allocated resources"

よくある問題:

アンチアフィニティでは 3 つの別々のノードが必要ですが、クラスター内のノード数が不足している
ノードに、pod の要求を満たすのに十分な CPU / メモリがない
ノードの taint によって pod をスケジュールできない

解決策:

ノード数が 3 未満の場合は、アンチアフィニティルールを削除または調整する
より緩やかなアンチアフィニティにするには、requiredDuringSchedulingIgnoredDuringExecution ではなく preferredDuringSchedulingIgnoredDuringExecution を使用する
ノードのリソースが不足している場合は、リソース要求を減らす
クラスターにノードを追加する

問題: Keeper pod が CrashLoopBackOff になる 解決策: ログを確認し、設定を検証する:

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

よくある問題:

セキュリティコンテキストの誤り (runAsUser、fsGroup を確認)
ボリュームの権限に関する問題
ポートの競合
ch-keeper.yaml の設定エラー

ClickHouse Server の問題

問題: ClickHouse が S3 に接続できない 解決策: S3 の認証情報と権限を確認してください。

# シークレットが存在するか確認する（アクセスキーを使用している場合）
kubectl get secret aws-creds -n clickhouse

# ClickHouseログでS3エラーを確認する
kubectl logs -n clickhouse <clickhouse-pod-name> | grep -i s3

# ストレージ設定のS3エンドポイントを確認する
kubectl get chi wandb -n clickhouse -o yaml | grep -A 10 storage_configuration

問題: ClickHouse が Keeper に接続できない 解決策: Keeper のエンドポイントと命名設定を確認してください。

# Keeperサービスと実際の名前を確認する
kubectl get svc -n clickhouse | grep keeper

# Keeperpodで命名パターンを確認する
kubectl get pods -n clickhouse -l app=clickhouse-keeper

# ch-server.yaml の zookeeper.nodes 設定と比較する
# ホスト名は実際のサービス名と一致している必要がある

# ClickHouseログで接続エラーを確認する
kubectl logs -n clickhouse chi-wandb-weavecluster-0-0-0 | grep -i keeper

接続に失敗する場合は、ch-server.yaml 内の Keeper ホスト名が実際の Keeper デプロイと一致していない可能性があります。命名規則については、Step 4 の「Keeper の命名規則について」を参照してください。

Weave Trace の問題

問題: weave-trace pod が起動しない 解決策: ClickHouse への接続を確認してください:

# weave-trace の pod 名を取得する
kubectl get pods -n wandb | grep weave-trace

# weave-trace のログを確認する
kubectl logs -n wandb <weave-trace-pod-name>

# よくあるエラー: "connection refused" または "authentication failed"
# wandb-cr.yaml の ClickHouse 認証情報が ch-server.yaml と一致しているか確認する

問題: Console で Weave が有効と表示されない 解決策: 設定を確認します。

ライセンスに Weave が含まれていることを確認します。

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

wandb-cr.yaml で weave-trace.enabled: true と clickhouse.replicated: true が設定されていることを確認します

W&B operator のログを確認します。

kubectl logs -n wandb deployment/wandb-controller-manager

問題: データベースの移行に失敗する 解決策: クラスター名が一致していることを確認します。 WF_CLICKHOUSE_REPLICATED_CLUSTER 環境変数は、ch-server.yaml 内のクラスター名と必ず一致している必要があります:

# ch-server.yaml 内:
clusters:
  - name: weavecluster # <-- この名前

# wandb-cr.yaml 内の値と一致している必要があります:
weave-trace:
  extraEnv:
    WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" # <-- この値

リソース要件

以下のリソース割り当ては、あくまで開始時の目安の一例です。実際に必要となる要件は、以下の要因によって大きく異なります。

トレース取り込み量 (1 秒あたりのトレース数)
クエリパターンと同時実行数
データ保持期間
同時接続ユーザー数

ご利用のユースケースに適したサイジングを判断するため、必ず W&B の Solutions Architect チームに相談してください。リソースが不足するとパフォーマンス上の問題につながる可能性があり、逆に過剰に割り当てるとインフラストラクチャーコストの無駄になります。

最小本番構成

コンポーネント	レプリカ数	CPU リクエスト / 上限	メモリリクエスト / 上限	ストレージ
ClickHouse Keeper	3	0.5 / 1	256Mi / 2Gi	各 10Gi
ClickHouse Server	3	1 / 4	1Gi / 16Gi	各 50Gi
Weave Trace	1	1 / 4	4Gi / 8Gi	-
合計	7 pod	約 4.5 / 15 CPU	約 7.8Gi / 58Gi	180Gi

適した用途: 開発、テスト、または低負荷の本番環境

推奨される本番構成

トレース量が多い本番ワークロード向け:

コンポーネント	レプリカ数	CPU リクエスト / 上限	メモリリクエスト / 上限	ストレージ
ClickHouse Keeper	3	1 / 2	1Gi / 4Gi	各20Gi
ClickHouse Server	3	1 / 16	8Gi / 64Gi	各200Gi
Weave Trace	2-3	1 / 4	4Gi / 8Gi	-
合計	8-9 pod	~6-9 / 52-64 CPU	~27-33Gi / 204-216Gi	660Gi

適した環境: 高トレース量の本番環境 超高ボリュームのデプロイについては、トレース量やパフォーマンス要件に応じたカスタムのサイジング推奨事項について、W&B Solutions Architect チームにお問い合わせください。

高度な設定

このセクションでは、セルフマネージドの Weave デプロイ向けのカスタマイズオプションについて説明します。これには、垂直スケーリングまたは水平スケーリングによる ClickHouse 容量の拡張、keeper と server の両方の設定でイメージタグを変更して ClickHouse のバージョンを更新すること、さらに ClickHouse の健全性を監視することが含まれます。インスタンスに高度な変更を加える際は、それらの変更がパフォーマンス要件と信頼性要件に適合していることを確認するため、W&B Solutions Architect チームに相談することをお勧めします。

ClickHouse のスケーリング

ClickHouse の容量を増やすには、次の方法があります。

垂直スケーリング: pod ごとのリソースを増やします (より簡単な方法)
resources: requests: memory: 8Gi cpu: 1 limits: memory: 64Gi cpu: 16
推奨事項: 実際のリソース使用量を監視し、それに応じてスケールしてください。非常に大規模なデプロイを行う場合は、W&B Solutions Architect チームにお問い合わせください。
水平スケーリング: レプリカを追加します (慎重な計画が必要です)
- レプリカを増やすには、データの再分散が必要です
- シャード管理については ClickHouse のドキュメントを参照してください
- 本番環境で水平スケーリングを実施する前に、W&B Solutions Architect にお問い合わせください

異なるバージョンの ClickHouse を使用する

別のバージョンの ClickHouse を使用するには、ch-keeper.yaml と ch-server.yaml の両方でイメージタグを更新します。

image: clickhouse/clickhouse-keeper:25.10   # Keeperバージョン
image: clickhouse/clickhouse-server:25.10   # Serverバージョン

互換性を確保するには、Keeper とサーバーのバージョンを一致させるか、Keeper のバージョンをサーバーのバージョン以上にする必要があります。

ClickHouse の監視

監視のために、ClickHouse のシステムテーブルにアクセスします。

# ディスク使用量を確認する
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"

# レプリケーションのステータスを確認する
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'"

# ClickHouseサーバーのステータスを確認する
kubectl get pods -n clickhouse -l app=clickhouse-server

バックアップとリカバリ

ClickHouse のデータは S3 に保存されており、S3 のバージョン管理とバケットレプリケーション機能により、標準でバックアップ機能を利用できます。ご利用のデプロイに応じたバックアップ戦略については、W&B Solutions Architect チームに相談し、ClickHouse のバックアップドキュメントを参照してください。

セキュリティに関する考慮事項

認証情報: ClickHouse のパスワードはプレーンテキストではなく、Kubernetes シークレットに保存します
ネットワークポリシー: ClickHouse へのアクセスを制限するため、NetworkPolicies の実装を検討してください
RBAC: サービスアカウントには、必要最小限の権限のみを付与してください
S3 Bucket: 保存時の暗号化を有効にし、S3 バケットへのアクセスを必要な IAM ロールのみに制限してください
TLS (オプション): 本番環境では、ClickHouse クライアント接続で TLS を有効にしてください

アップグレード

ClickHouse Operator のアップグレード

helm upgrade ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  -f ch-operator.yaml

ClickHouse Server のアップグレード

ch-server.yaml のイメージのバージョンを更新して、適用します:

# ch-server.yaml を編集してイメージタグを変更する
kubectl apply -f ch-server.yaml

# pod を監視する
kubectl get pods -n clickhouse

Weave Trace のアップグレード

wandb-cr.yaml のイメージタグを更新して、適用します。

kubectl apply -f wandb-cr.yaml

# weave-trace podの再起動を監視する
kubectl get pods -n wandb | grep weave-trace

参考資料

サポート

本番デプロイや問題がある場合:

W&B サポート: support@wandb.com
ソリューションアーキテクト: 超大規模デプロイ、カスタムサイジング、デプロイ計画について
サポートへの問い合わせに含める内容:
- weave-trace、ClickHouse pod、operator のログ
- W&B バージョン、ClickHouse バージョン、Kubernetes バージョン
- クラスター情報とトレースのボリューム

よくある質問

Q: 3つではなく、ClickHouse レプリカを1つだけ使用できますか？ A: はい。ただし、本番環境では推奨されません。ch-server.yaml の replicasCount: 1 に更新し、wandb-cr.yaml で clickhouse.replicated: false を設定してください。 Q: ClickHouse の代わりに別のデータベースを使用できますか？ A: いいえ。Weave Trace では、高パフォーマンスなカラム指向ストレージを実現するために ClickHouse が必要です。 Q: S3 ストレージはどのくらい必要ですか？ A: S3 ストレージの必要量は、トレース量、保持期間、データ圧縮によって異なります。デプロイ後に実際の使用量を監視し、それに応じて調整してください。ClickHouse のカラム指向フォーマットは、Trace Data を高い圧縮率で保存できます。 Q: ClickHouse で database 名を設定する必要がありますか？ A: いいえ。weave データベースは、初回起動時に weave-trace サービスによって自動的に作成されます。 Q: クラスター名が weavecluster ではない場合はどうなりますか？ A: WF_CLICKHOUSE_REPLICATED_CLUSTER 環境変数を、実際のクラスター名に合わせて設定する必要があります。そうしないと、データベース移行が失敗します。 Q: 例に示されているセキュリティコンテキストをそのまま使うべきですか？ A: いいえ。このガイドに記載しているセキュリティコンテキスト (runAsUser、fsGroup など) は参考例です。特に OpenShift クラスターでは UID/GID の範囲に関する固有の要件があるため、組織のセキュリティポリシーに準拠するよう調整する必要があります。 Q: ClickHouse クラスターのサイジングが適切かどうかは、どうすれば判断できますか？ A: 想定しているトレース量と使用パターンを W&B Solutions Architect チームに共有してください。具体的なサイジング推奨を受けられます。デプロイのリソース使用量を監視し、必要に応じて調整してください。 Q: 例で使用されている命名規則はカスタマイズできますか？ A: はい。ただし、すべてのコンポーネントで一貫性を保つ必要があります。

ClickHouse Keeper 名 → ch-server.yaml の zookeeper.nodes セクションにある Keeper ノードのホスト名と一致している必要があります
ClickHouse クラスター名 (weavecluster) → wandb-cr.yaml の WF_CLICKHOUSE_REPLICATED_CLUSTER と一致している必要があります
ClickHouse インストール名 → weave-trace が使用するサービスのホスト名に影響します

命名パターンの詳細と実際の名前を確認する方法については、step 4 の「Keeper Naming を理解する」セクションを参照してください。 Q: クラスターで異なるアンチアフィニティ要件が必要な場合はどうなりますか？ A: ここで示しているアンチアフィニティルールは、高可用性のための推奨事項です。クラスターのサイズ、トポロジー、可用性要件に応じて調整または削除してください。小規模なクラスターや開発環境では、アンチアフィニティルールが不要な場合もあります。

デプロイオプションとセキュリティ機能

Weave プロジェクトを管理する

⌘I

​重要なセットアップ上の注意

​アーキテクチャ

​前提条件

​必須ツール

​ネットワーク要件

​セルフマネージドWeaveインスタンスをデプロイする

​Step 1: Altinity ClickHouse Operator をデプロイする

​1.1 Altinity Helmリポジトリを追加する

​1.2 Operator の設定を作成

​1.3 operatorをインストールする

​1.4 operator がインストールされていることを確認する

​Step 2: S3ストレージを準備する

​2.1 S3バケットを作成する

​2.2 S3認証情報を設定する

オプション A: AWS IAM ロールを使用する (IRSA - AWS では推奨)

オプション B: アクセスキーを使用する

​Step 3: ClickHouse Keeper をデプロイする

​3.1 Keeper の設定を作成する

​3.2 ClickHouse Keeperをデプロイする

​3.3 Keeper のデプロイを確認する

​Step 4: ClickHouse Cluster をデプロイする

​4.1 ClickHouse サーバーの設定を作成する

​4.2 S3 の設定を更新する

​4.3 認証情報を設定する (Option B のみ)

​4.4 Keeper の命名規則を理解する

​4.5 ClickHouse クラスターをデプロイする

​4.6 ClickHouse のデプロイを確認する

​Step 5: W&B Platform で Weave を有効にする

​5.1 ClickHouse の接続情報を確認する

​5.2 W&B Custom Resource を更新する

​5.3 更新した設定を適用する

​5.4 Weave Trace のデプロイを確認する

​Step 6: Weave データベースを初期化する

​6.1 データベースの移行を監視する

​6.2 データベースが作成されたことを確認する

​Step 7: Weave が有効であることを確認する

​7.1 W&B Console にアクセスする

​7.2 Weave ライセンスの状態を確認する

​7.3 Weave の機能をテストする

​トラブルシューティング

​ClickHouse Keeper の問題

​ClickHouse Server の問題

​Weave Trace の問題

​リソース要件

​最小本番構成

​推奨される本番構成

​高度な設定

​ClickHouse のスケーリング

​異なるバージョンの ClickHouse を使用する

​ClickHouse の監視

​バックアップとリカバリ

​セキュリティに関する考慮事項

​アップグレード

​ClickHouse Operator のアップグレード

​ClickHouse Server のアップグレード

​Weave Trace のアップグレード

​参考資料

​サポート

​よくある質問

重要なセットアップ上の注意

アーキテクチャ

前提条件

必須ツール

ネットワーク要件

セルフマネージドWeaveインスタンスをデプロイする

Step 1: Altinity ClickHouse Operator をデプロイする

1.1 Altinity Helmリポジトリを追加する

1.2 Operator の設定を作成

1.3 operatorをインストールする

1.4 operator がインストールされていることを確認する

Step 2: S3ストレージを準備する

2.1 S3バケットを作成する

2.2 S3認証情報を設定する

Step 3: ClickHouse Keeper をデプロイする

3.1 Keeper の設定を作成する

3.2 ClickHouse Keeperをデプロイする

3.3 Keeper のデプロイを確認する

Step 4: ClickHouse Cluster をデプロイする

4.1 ClickHouse サーバーの設定を作成する

4.2 S3 の設定を更新する

4.3 認証情報を設定する (Option B のみ)

4.4 Keeper の命名規則を理解する

4.5 ClickHouse クラスターをデプロイする

4.6 ClickHouse のデプロイを確認する

Step 5: W&B Platform で Weave を有効にする

5.1 ClickHouse の接続情報を確認する

5.2 W&B Custom Resource を更新する

5.3 更新した設定を適用する

5.4 Weave Trace のデプロイを確認する

Step 6: Weave データベースを初期化する

6.1 データベースの移行を監視する

6.2 データベースが作成されたことを確認する

Step 7: Weave が有効であることを確認する

7.1 W&B Console にアクセスする

7.2 Weave ライセンスの状態を確認する

7.3 Weave の機能をテストする

トラブルシューティング

ClickHouse Keeper の問題

ClickHouse Server の問題

Weave Trace の問題

リソース要件

最小本番構成

推奨される本番構成

高度な設定

ClickHouse のスケーリング

異なるバージョンの ClickHouse を使用する

ClickHouse の監視

バックアップとリカバリ

セキュリティに関する考慮事項

アップグレード

ClickHouse Operator のアップグレード

ClickHouse Server のアップグレード

Weave Trace のアップグレード

参考資料

サポート

よくある質問