> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 独自のインフラストラクチャーで Weave をデプロイおよび管理する

W\&B Weave をセルフホストすると、その環境と設定に対するより多くの制御が可能になります。これにより、より分離された環境を作成し、追加のセキュリティコンプライアンスを満たすことができます。

このドキュメントでは、Altinity ClickHouse Operator を使用して [W\&B Self-Managed](/ja/products/wandb/platform/hosting/hosting-options/self-managed) デプロイメントで W\&B Weave を実行するために必要なコンポーネントをデプロイする方法を説明します。最終的に、独自の Kubernetes クラスター上で本番グレードの Weave インスタンスが、レプリケートされた ClickHouse データベースと S3互換オブジェクトストレージによって支えられて実行されるようになります。このガイドは、組織内で W\&B のデプロイと運用を担当する Kubernetes 管理者およびプラットフォームエンジニア向けです。

セルフマネージド Weave デプロイメントは、バックエンドを管理するために [ClickHouseDB](https://clickhouse.com/) に依存します。このデプロイメントでは以下を使用します:

* **Altinity ClickHouse Operator**: Kubernetes 向けのエンタープライズグレードの ClickHouse 管理ツール。
* **ClickHouse Keeper**: 分散型コーディネーションサービス (ZooKeeper の代替)。
* **ClickHouse Cluster**: トレースストレージ用の高可用性データベースクラスター。
* **S3互換ストレージ**: ClickHouse データ永続化のためのオブジェクトストレージ。

<Tip>
  詳細なリファレンスアーキテクチャについては、[W\&B Self-Managed Reference Architecture](/ja/products/wandb/platform/hosting/self-managed/ref-arch#models-and-weave) を参照してください。
</Tip>

<h2 id="important-setup-notes">
  セットアップに関する重要なメモ
</h2>

このガイドの設定例は参考用です。Kubernetes 環境は組織ごとに異なるため、セルフホストのインスタンスでは、通常、次の項目を調整する必要があります。

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

これらの設定は、そのまま適用するソリューションではなく、テンプレートとして扱ってください。

<h2 id="architecture">
  アーキテクチャ
</h2>

次の図は、セルフマネージドの Weave デプロイメントにおいて、W\&B Platform、ClickHouse クラスター、ClickHouse Keeper コーディネーションサービス、S3 ストレージがどのように連携するかを示しています。

```mermaid theme={"system"}
graph TD
    A["W&B プラットフォーム (wandb)<br/>weave-trace · app/API · console/parquet"] --> B["ClickHouse クラスター"]
    B --> C["ch-server-0"]
    B --> D["ch-server-1"]
    B --> E["ch-server-2"]
    C --> F["ClickHouse Keeper クラスター<br/>keeper-0 <br/>keeper-1 <br/>keeper-2"]
    D --> F
    E --> F
    C --> G["S3 ストレージ<br/>(AWS/MinIO)"]
    D --> G
    E --> G
```

<h2 id="prerequisites">
  前提条件
</h2>

開始する前に、環境が以下の要件を満たしていることを確認してください。セルフマネージドの Weave インスタンスには以下のリソースが必要です：

* **Kubernetes cluster**: バージョン 1.29 以降。
* **Kubernetes nodes**: マルチノードクラスター (高可用性のために最低 3 ノードを推奨) 。
* **Storage class**: 永続ボリューム用の動作する StorageClass (例: `gp3`、`standard`、`nfs-csi`) 。
* **S3 bucket**: 適切なアクセス権限を持つ事前設定済みの S3 または S3互換バケット。
* **W\&B Platform**: すでにインストールされ実行中。[W\&B Self-Managed Deployment Guide](/ja/products/wandb/platform/hosting/hosting-options/self-managed) を参照してください。
* **W\&B license**: W\&B Support から提供される Weave 有効化ライセンス。

<Warning>
  この前提条件リストのみに基づいてサイジングの決定を行わないでください。リソース要件はトレース量と使用パターンによって異なります。詳細については、[Resource requirements](#resource-requirements) を参照してください。
</Warning>

<h3 id="required-tools">
  必須ツール
</h3>

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

* クラスターアクセスが設定された `kubectl`。
* `helm` バージョン 3.0 以降。
* AWS 認証情報 (S3 を使用する場合) または S3互換ストレージへのアクセス。

<h3 id="network-requirements">
  ネットワーク要件
</h3>

Kubernetes クラスターには、次のネットワーク構成が必要です。

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

<h2 id="deploy-your-self-managed-weave-instance">
  セルフマネージド Weave インスタンスをデプロイする
</h2>

以下のステップでは、オペレーターのデプロイ、ストレージの準備、ClickHouse Keeper と ClickHouse クラスターのデプロイ、および W\&B プラットフォームでの Weave の有効化について説明します。各ステップは前のステップで作成したリソースに基づいているため、順番に完了してください。

<h3 id="deploy-the-altinity-clickhouse-operator">
  Altinity ClickHouse Operator のデプロイ
</h3>

Altinity ClickHouse Operator は Kubernetes 内の ClickHouse インストールを管理します。オペレーターを最初にインストールすることで、後続のステップで ClickHouse Keeper と ClickHouse クラスターのリソースを宣言でき、オペレーターがそれらをリコンサイルします。

<h4 id="add-the-altinity-helm-repository">
  Altinity Helm リポジトリを追加
</h4>

```bash theme={"system"}
helm repo add altinity https://helm.altinity.com
helm repo update
```

<h4 id="create-the-operator-configuration">
  オペレーターの設定を作成する
</h4>

`ch-operator.yaml` という名前のファイルを作成します。このファイルは、オペレーターのデプロイメントのセキュリティコンテキストとメタデータを定義します：

```yaml theme={"system"}
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` を調整する必要があります。

<h4 id="install-the-operator">
  オペレーターをインストールする
</h4>

```bash theme={"system"}
helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  --create-namespace \
  -f ch-operator.yaml
```

<h4 id="verify-the-operator-installation">
  オペレーターのインストールを確認する
</h4>

```bash theme={"system"}
# オペレーターPodが実行中であることを確認
kubectl get pods -n clickhouse

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

# オペレーターイメージのバージョンを確認
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
```

オペレーターが稼働したので、ClickHouse クラスターが依存する永続ストレージとコーディネーションサービスをプロビジョニングできます。

<h3 id="prepare-s3-storage">
  S3 ストレージを準備する
</h3>

ClickHouse では、データの永続化に S3 または S3互換ストレージが必要です。このステップでは、バケットを作成し、ClickHouse がそれに認証する方法を設定します。

<h4 id="create-an-s3-bucket">
  S3 バケットを作成する
</h4>

AWS アカウントまたは S3互換のストレージプロバイダーで S3 バケットを作成します。`[BUCKET-NAME]` をバケット名に、 `[REGION]` を AWS リージョンに置き換えてください：

```bash theme={"system"}
# AWS の例
aws s3 mb s3://[BUCKET-NAME] --region [REGION]
```

<h4 id="configure-s3-credentials">
  S3 認証情報を設定する
</h4>

ClickHouse はバケットからの読み取りと書き込みに認証情報を必要とします。S3 アクセスの認証情報を提供する方法は 2 つあります。W\&B は、クラスターに長期的なシークレットを保存しないため、AWS 上のオプション A (IRSA) を推奨します。

<h5 id="option-a-use-aws-iam-roles-irsa-recommended-for-aws">
  オプション A: AWS IAM ロールを使用する (IRSA、AWS 推奨)
</h5>

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

```yaml theme={"system"}
# ch-server.yaml で設定します:
<use_environment_credentials>true</use_environment_credentials>
```

必須の IAM ポリシー (ノードの IAM ロールに関連付ける) :

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::[BUCKET-NAME]",
        "arn:aws:s3:::[BUCKET-NAME]/*"
      ]
    }
  ]
}
```

<h5 id="option-b-use-access-keys">
  Option B: アクセスキーを使用する
</h5>

静的な認証情報を好む場合は、Kubernetes シークレットを作成します：

`[ACCESS-KEY]` を AWS アクセスキーに、 `[SECRET-KEY]` を AWS シークレットキーに置き換えてください：

```bash theme={"system"}
kubectl create secret generic aws-creds \
  --namespace clickhouse \
  --from-literal aws_access_key=[ACCESS-KEY] \
  --from-literal aws_secret_key=[SECRET-KEY]
```

次に、そのシークレットを使用するように ClickHouse を設定します (ステップ 4 の ch-server.yaml の設定を参照してください) 。

<h3 id="deploy-clickhouse-keeper">
  ClickHouse Keeper のデプロイ
</h3>

[ClickHouse Keeper](https://clickhouse.com/docs/guides/sre/keeper/clickhouse-keeper) は、データレプリケーションと分散 DDL クエリの実行のためのコーディネーションシステムを提供します。ClickHouse クラスターをデプロイする前に Keeper をデプロイする必要があります。ステップ 4 の ClickHouse サーバーは起動時に Keeper に接続するためです。

<h4 id="create-the-keeper-configuration">
  Keeper の設定を作成する
</h4>

`ch-keeper.yaml` という名前のファイルを作成します。このマニフェストでは、3 レプリカの Keeper クラスターをアンチアフィニティ、永続ストレージ、および Altinity オペレーターが Keeper Pod をプロビジョニングするために使用する設定とともに定義します。

```yaml theme={"system"}
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 クラスター名 - サービス 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**: `storageClassName: gp3` を、クラスターで使用可能な StorageClass に合わせて変更してください。
* **セキュリティコンテキスト**: `runAsUser` と `fsGroup` の値を、組織のセキュリティポリシーに準拠するように調整してください。
* **アンチアフィニティ**: クラスターのトポロジと HA 要件に応じて、`affinity` セクションをカスタマイズするか削除してください。
* **リソース**: CPU とメモリの値は一例です。適切なサイジングについては、W\&B Solutions Architect にご相談ください。
* **命名**: `metadata.name` または `configuration.clusters[0].name` を変更する場合は、`ch-server.yaml` (ステップ 4) 内の Keeper のホスト名もそれに合わせて更新する必要があります。

<h4 id="deploy-clickhouse-keeper-resources">
  ClickHouse Keeper リソースをデプロイする
</h4>

```bash theme={"system"}
kubectl apply -f ch-keeper.yaml
```

<h4 id="verify-the-keeper-deployment">
  Keeper デプロイメントを検証
</h4>

```bash theme={"system"}
# 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 の Service を確認します
kubectl get svc -n clickhouse | grep keeper

# ポート 2181 で keeper の Service が表示されれば正常です
```

Keeper が実行中なので、それを使用して調整を行う ClickHouse クラスターをデプロイできます。

<h3 id="deploy-the-clickhouse-cluster">
  ClickHouse クラスターをデプロイする
</h3>

Weave トレース データを保存する ClickHouse サーバー クラスターをデプロイします。これはガイドの中で最大のステップです。クラスターはステップ 3 の Keeper サービスとステップ 2 の S3 Bucket の両方に接続するためです。

<h4 id="create-the-clickhouse-server-configuration">
  ClickHouse Server 設定の作成
</h4>

`ch-server.yaml` という名前のファイルを作成します。このマニフェストは、ClickHouse クラスター、Keeper への接続、Weave のユーザー アカウント、およびトレースデータに使用される S3 storage ポリシーを宣言します：

```yaml theme={"system"}
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 security context - customize for your environment
          securityContext:
            fsGroup: 10001 # Adjust based on your security policies
            fsGroupChangePolicy: Always
            runAsGroup: 0
            runAsNonRoot: true
            runAsUser: 10001 # For OpenShift, use assigned UID range
            seccompProfile:
              type: RuntimeDefault

          # Anti-affinity rule - ensures servers run on different nodes (optional but recommended)
          # Adjust or remove based on your cluster size and requirements
          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
              # Example resource allocation - adjust based on workload
              resources:
                requests:
                  memory: 1Gi
                  cpu: 1
                limits:
                  memory: 16Gi
                  cpu: 4

              # AWS credentials (remove this section if using 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 # Change to your StorageClass

  configuration:
    # Keeper (ZooKeeper) configuration
    # IMPORTANT: These hostnames MUST match your Keeper deployment from Step 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
      # Optional: Uncomment to adjust timeouts if needed
      # session_timeout_ms: 30000
      # operation_timeout_ms: 10000

    # Users configuration: https://clickhouse.com/docs/operations/configuration-files#user-settings
    # For production, use a SHA-256 hashed password instead of plain text:
    # printf "your-password" | sha256sum
    # Then use: weave/password_sha256_hex: <hash> instead of weave/password
    users:
      weave/password: [WEAVE-PASSWORD]  # Replace with a strong password before deploying
      weave/access_management: 1
      weave/profile: default
      weave/networks/ip:
        - "0.0.0.0/0"
        - "::"

    # Server settings
    settings:
      disable_internal_dns_cache: 1

    # Cluster configuration
    clusters:
      - name: weavecluster # Cluster name - can be customized but must match wandb-cr.yaml
        layout:
          shardsCount: 1
          replicasCount: 3 # Number of replicas - adjust based on HA requirements
        templates:
          podTemplate: clickhouse
          dataVolumeClaimTemplate: data

    # Configuration files
    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>
                        <!-- Update with your S3 bucket endpoint and region -->
                        <endpoint>https://[BUCKET-NAME].s3.[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>[REGION]</region>
                    </s3_disk>
                    <s3_disk_cache>
                        <type>cache</type>
                        <disk>s3_disk</disk>
                        <path>/var/lib/clickhouse/s3_disk_cache/cache/</path>
                        <!-- Cache size MUST be smaller than persistent volume -->
                        <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>
```

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

1. **StorageClass**: `storageClassName: gp3` をクラスターの StorageClass に合わせて更新してください。
2. **S3 endpoint**: `[BUCKET-NAME]` と `[REGION]` を実際の値に置き換えてください。
3. **Cache size**: `<max_size>40Gi</max_size>` は永続ボリュームのサイズ (50Gi) より小さくする必要があります。
4. **Security context**: `runAsUser`、`fsGroup`、およびその他のセキュリティ設定を組織のポリシーに合わせて調整してください。
5. **Resource allocation**: CPU とメモリの値は例です。予想されるトレース量に基づく適切なサイジングについては、W\&B Solutions Architect にご相談ください。
6. **Anti-affinity rules**: クラスターのトポロジと高可用性のニーズに基づいてカスタマイズまたは削除してください。
7. **Keeper hostnames**: Keeper ノードのホスト名は、ステップ 3 の Keeper デプロイメントの命名に一致する必要があります (「Keeper の命名規則」を参照) 。
8. **Cluster naming**: クラスター名 `weavecluster` は変更可能ですが、ステップ 5 の `WF_CLICKHOUSE_REPLICATED_CLUSTER` の値と一致する必要があります。
9. **Credentials**:
   * IRSA の場合: `<use_environment_credentials>true</use_environment_credentials>` を保持するか、環境変数にマッピングされたシークレットキーにアクセスしてください。

<h4 id="update-the-s3-configuration">
  S3 設定の更新
</h4>

`ch-server.yaml` の `storage_configuration.xml` セクションを編集します。

AWS S3 の例:

```xml theme={"system"}
<endpoint>https://my-wandb-clickhouse.s3.eu-central-1.amazonaws.com/s3_disk/{replica}</endpoint>
<region>eu-central-1</region>
```

MinIO の例：

```xml theme={"system"}
<endpoint>https://minio.example.com:9000/my-bucket/s3_disk/{replica}</endpoint>
<region>us-east-1</region>
```

<Warning>
  `{replica}` は削除しないでください。これにより、各 ClickHouse レプリカがバケット内の個別のフォルダーに書き込むようになります。
</Warning>

<h4 id="configure-credentials-option-b-only">
  認証情報を設定する (オプション B のみ)
</h4>

オプション B (アクセスキー) を使用する場合、ステップ 2 から、`ch-server.yaml` の `env` セクションがシークレットを参照していることを確認してください：

```yaml theme={"system"}
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
```

Option A (IRSA) を使用する場合は、`env` セクション全体を削除します。

<h4 id="keeper-naming">
  Keeper の命名規則
</h4>

Keeper のホスト名を正しく設定することは非常に重要です。ステップ 3 で作成したサービスと一致しない場合、ClickHouse は起動しません。`zookeeper.nodes` セクションに指定する Keeper ノードのホスト名は、ステップ 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 の namespace です (例: `clickhouse`)。

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

```text theme={"system"}
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`) は、次のようにします。

```text theme={"system"}
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`):

```text theme={"system"}
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 ホスト名を確認するには、次の手順を実行します。

```bash theme={"system"}
# Keeper のサービスを一覧表示して実際の名前を確認します
kubectl get svc -n clickhouse | grep keeper

# Keeper の Pod を一覧表示して命名パターンを確認します
kubectl get pods -n clickhouse -l app=clickhouse-keeper
```

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

<h4 id="deploy-the-clickhouse-cluster-resources">
  ClickHouse クラスターのリソースをデプロイする
</h4>

```bash theme={"system"}
kubectl apply -f ch-server.yaml
```

<h4 id="verify-the-clickhouse-deployment">
  ClickHouse のデプロイメントを確認する
</h4>

```bash theme={"system"}
# ClickHouse の Pod を確認します
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 [WEAVE-PASSWORD] --query "SELECT version()"

# クラスターのステータスを確認します
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SELECT cluster, host_name, port FROM system.clusters WHERE cluster='weavecluster'"
```

これで、Keeper と S3 をバックエンドとする ClickHouse クラスターが稼働しました。残りのステップでは、W\&B Platform をこのクラスターに接続し、Weave トレースがエンドツーエンドで流れることを確認します。

<h3 id="enable-weave-in-the-wb-platform">
  W\&B プラットフォームで Weave を有効にする
</h3>

次に、Weave トレースの保存先として ClickHouse クラスターを使用するよう、W\&B プラットフォームを設定します。このステップでは、外部で管理している ClickHouse の接続先を W\&B Operator に指定し、`weave-trace` サービスを有効にします。

<h4 id="gather-clickhouse-connection-information">
  ClickHouse の接続情報を確認する
</h4>

以下の情報が必要です。

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

ホスト名は次の形式になります: `clickhouse-[INSTALLATION-NAME].[NAMESPACE].svc.cluster.local`

<h4 id="update-the-wb-custom-resource">
  W\&B カスタムリソースを更新する
</h4>

W\&B Platform のカスタムリソース (CR) を編集して、Weave の設定を追加します。

```yaml theme={"system"}
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: [WEAVE-PASSWORD]
        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` のクラスター名と一致させる必要があります。

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

<h4 id="apply-the-updated-configuration">
  更新した設定を適用する
</h4>

```bash theme={"system"}
kubectl apply -f wandb-cr.yaml
```

<h4 id="verify-the-weave-trace-deployment">
  Weave Trace のデプロイメントを検証する
</h4>

```bash theme={"system"}
# weave-trace Pod のステータスを確認します
kubectl get pods -n wandb | grep weave-trace

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

# weave-trace のログで ClickHouse への接続状況を確認します
kubectl logs -n wandb [WEAVE-TRACE-POD-NAME] --tail=50

# ClickHouse への接続成功を示すメッセージがあることを確認します
```

<h3 id="initialize-the-weave-database">
  Weave データベースを初期化する
</h3>

weave-trace サービスは、初回起動時に必要なデータベーススキーマを自動的に作成します。この手順では、エンドユーザーに Weave を公開する前に、移行が正常に完了したことを確認します。

<h4 id="monitor-the-database-migration">
  データベースの移行を監視する
</h4>

```bash theme={"system"}
# 起動中に weave-trace のログを監視
kubectl logs -n wandb [WEAVE-TRACE-POD-NAME] -f

# データベースの初期化が成功したことを示す移行メッセージを確認
```

<h4 id="verify-database-creation">
  データベースの作成を確認する
</h4>

```bash theme={"system"}
# ClickHouse に接続してデータベースを確認します
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SHOW DATABASES"

# 一覧に 'weave' データベースが表示されるはずです

# weave データベース内の表を確認します
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SHOW TABLES FROM weave"
```

<h3 id="verify-that-weave-is-enabled">
  Weave が有効になっていることを確認する
</h3>

最後のこのステップでは、Weave のライセンスが有効であること、W\&B Console からアクセスできること、およびクライアント SDK からトレースを記録できることを確認します。

<h4 id="access-the-wb-console">
  W\&B Console にアクセスする
</h4>

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

<h4 id="check-the-weave-license-status">
  Weave のライセンスステータスを確認する
</h4>

W\&B Console で次の操作を行います。

1. **Top Right Menu** > **Organization Dashboard** に移動します。
2. **Weave access** が有効になっていることを確認します。

<h4 id="test-weave-functionality">
  Weave の機能をテストする
</h4>

Weave が動作していることを確認するため、Python のテストを作成します。

```python theme={"system"}
import os
import weave

# Weaveの接続先をセルフマネージドのW&Bインスタンスに設定
os.environ["WANDB_BASE_URL"] = "https://[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)
```

これを実行した後、Weights & Biases UI で組織のトレース ページを開き、トレースを確認してください。トレースが表示されれば、セルフマネージドの Weave デプロイメントは正常に稼働しています。

<h2 id="troubleshooting">
  トラブルシューティング
</h2>

以下のセクションでは、デプロイメントでよく発生する問題とその解決方法を、症状が最初に現れるコンポーネントごとに説明します。

<h3 id="clickhouse-keeper-issues">
  ClickHouse Keeper の問題
</h3>

**問題**: Keeper の Pod が `Pending` 状態のまま進まない

**解決策**: 考えられる複数の原因を確認します。

1. **PVC と StorageClass の問題**:

```bash theme={"system"}
kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse
```

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

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

```bash theme={"system"}
# アンチアフィニティルールによってスケジューリングが妨げられていないか確認します
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` の状態になる

**解決策**: ログを確認し、設定を検証します。

```bash theme={"system"}
kubectl logs -n clickhouse [KEEPER-POD-NAME]
```

よくある問題:

* セキュリティコンテキストが正しくない (`runAsUser` と `fsGroup` を確認してください) 。
* ボリュームの権限に関する問題。
* ポートの競合。
* `ch-keeper.yaml` の設定エラー。

<h3 id="clickhouse-server-issues">
  ClickHouse サーバーの問題
</h3>

**問題**: ClickHouse が S3 に接続できない

**解決策**: S3 の認証情報と権限を確認します。

```bash theme={"system"}
# シークレットが存在するか確認します（アクセスキーを使用している場合）
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 のエンドポイントと命名規則を確認します。

```bash theme={"system"}
# Keeper のサービスと実際のサービス名を確認します
kubectl get svc -n clickhouse | grep keeper

# Keeper の Pod を確認し、命名パターンを確かめます
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 デプロイメントと一致していない可能性があります。命名パターンについては、ステップ 4 の「Keeper の命名規則」を参照してください。

<h3 id="weave-trace-issues">
  Weave Trace の問題
</h3>

**問題**: `weave-trace` Pod が起動しない

**解決策**: ClickHouse の接続性を確認します。

```bash theme={"system"}
# 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 が有効と表示されない

**解決策**: 設定を確認します。

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

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

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

3. W\&B オペレーターのログを確認します。
   ```bash theme={"system"}
   kubectl logs -n wandb deployment/wandb-controller-manager
   ```

***

**問題**: データベースの移行が失敗する

**解決策**: クラスター名が一致していることを確認します。

`WF_CLICKHOUSE_REPLICATED_CLUSTER` 環境変数の値は、`ch-server.yaml` 内のクラスター名と一致している必要があります。

```yaml theme={"system"}
# ch-server.yaml の設定:
clusters:
  - name: weavecluster # <-- この名前

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

<h2 id="resource-requirements">
  リソース要件
</h2>

このセクションでは、一般的な2つのデプロイ構成に対するリソース割り当ての例を紹介します。クラスターを計画する際の出発点として使用し、実際に観測したワークロードに基づいて数値を調整してください。

<Warning>
  このセクションのリソース割り当ては、出発点となる例です。実際の要件は、以下によって異なります。

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

  具体的なユースケースに適したリソース規模を判断するため、必ずW\&B Solutions Architect チームに相談してください。リソースの不足はパフォーマンスの問題につながり、過剰な割り当てはインフラストラクチャーのコストを無駄にします。
</Warning>

<h3 id="minimum-production-setup">
  本番環境の最小構成
</h3>

| コンポーネント | レプリカ数 | 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** |

開発、テスト、または処理量の少ない本番環境に適しています。

<h3 id="recommended-production-setup">
  推奨される本番セットアップ
</h3>

トレース量が多い本番ワークロードの場合:

| コンポーネント | レプリカ数 | 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 チームにお問い合わせください。実際のトレース量とパフォーマンス要件に応じて、個別のサイジングを提案します。

<h2 id="advanced-configuration">
  詳細設定
</h2>

このセクションでは、垂直スケーリングまたは水平スケーリングによる ClickHouse のキャパシティ拡張、Keeper とサーバーの両方の設定でイメージタグを変更することによる ClickHouse バージョンの更新、ClickHouse の健全性のモニタリングなど、セルフマネージドの Weave デプロイメントのカスタマイズオプションについて説明します。

W\&B では、インスタンスに高度な変更を加える際は、パフォーマンスと信頼性の要件を満たすよう、W\&B Solutions Architect チームに相談することを推奨しています。

<h3 id="scale-clickhouse">
  ClickHouse のスケーリング
</h3>

ClickHouse のキャパシティを増やすには、次の方法があります。

1. **垂直スケーリング**: Pod ごとのリソースを増やします (シンプルな方法です) 。

   ```yaml theme={"system"}
   resources:
     requests:
       memory: 8Gi
       cpu: 1
     limits:
       memory: 64Gi
       cpu: 16
   ```

   推奨事項: 実際のリソース使用量を監視し、それに応じてスケーリングしてください。極めて大量のデータを扱うデプロイメントについては、W\&B Solutions Architect チームにお問い合わせください。

2. **水平スケーリング**: レプリカを追加します (慎重な計画が必要です) 。
   * レプリカを増やすには、データの再分散が必要です。
   * シャード管理については、ClickHouse のドキュメントを参照してください。
   * 本番環境で水平スケーリングを実施する前に、W\&B Solutions Architect にご相談ください。

<h3 id="use-a-different-clickhouse-version">
  別の ClickHouse バージョンを使用する
</h3>

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

```yaml theme={"system"}
image: clickhouse/clickhouse-keeper:25.10   # Keeper のバージョン
image: clickhouse/clickhouse-server:25.10   # サーバーのバージョン
```

互換性を確保するため、Keeper とサーバーのバージョンを一致させるか、Keeper のバージョンをサーバーのバージョン以上にしてください。

<Warning>
  ClickHouse Server をアップグレードする際は、ClickHouse Keeper も互換性のあるバージョンにアップグレードしてください。W\&B セルフマネージドデプロイメントの ClickHouse バージョンを変更する前に、[アップグレード時の ClickHouse 互換性](/ja/products/wandb/platform/hosting/self-managed/operator#clickhouse-compatibility-for-upgrades)と[サポートされる W\&B Server リリース](/ja/release-notes/server-releases)のページを確認してください。
</Warning>

<h3 id="monitor-clickhouse">
  ClickHouse の監視
</h3>

モニタリングのために ClickHouse のシステム表にアクセスします：

```bash theme={"system"}
# ディスク使用量を確認
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --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 [WEAVE-PASSWORD] --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
```

<h3 id="backup-and-recovery">
  バックアップと復旧
</h3>

ClickHouse はデータを S3 に保存するため、S3 のバージョン管理機能とバケットレプリケーション機能により、バックアップ機能を標準で備えています。お使いのデプロイメントに適したバックアップ戦略については、W\&B Solutions Architect チームにご相談のうえ、[ClickHouse のバックアップに関するドキュメント](https://clickhouse.com/docs/en/operations/backup)を参照してください。

<h2 id="security-considerations">
  セキュリティに関する考慮事項
</h2>

本番環境のデプロイメントでは、このガイドに示すデフォルト設定のセキュリティを強化してください。セキュリティチームと確認すべき特に重要な事項を以下に示します。

1. **認証情報**: ClickHouse のパスワードは、平文ではなく Kubernetes シークレットに保存してください。
2. **ネットワークポリシー**: ClickHouse へのアクセスを制限するため、NetworkPolicies の導入を検討してください。
3. **RBAC**: サービスアカウントに必要最小限の権限のみが付与されていることを確認してください。
4. **S3 バケット**: 保存時の暗号化を有効にし、バケットへのアクセスを必要な IAM ロールに制限してください。
5. **TLS**: オプションです。本番環境では、ClickHouse へのクライアント接続で TLS を有効にしてください。

<h2 id="upgrade">
  アップグレード
</h2>

以下の手順では、オペレーター、ClickHouse サーバー、Weave Trace コンポーネントの通常のアップグレードについて説明します。コンポーネントを 1 つずつアップグレードし、デプロイメントが正常であることを確認してから次に進んでください。

<Note>
  Weave には、サポートされる ClickHouse バージョンが必要です。ClickHouse または W\&B Server をアップグレードする前に、[アップグレード時の ClickHouse 互換性](/ja/products/wandb/platform/hosting/self-managed/operator#clickhouse-compatibility-for-upgrades)と[サポートされる W\&B Server リリース](/ja/release-notes/server-releases)を参照してください。ClickHouse Server と ClickHouse Keeper は同時にアップグレードしてください。
</Note>

<h3 id="upgrade-the-clickhouse-operator">
  ClickHouse オペレーターをアップグレードする
</h3>

```bash theme={"system"}
helm upgrade ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  -f ch-operator.yaml
```

<h3 id="upgrade-clickhouse-server">
  ClickHouse Server のアップグレード
</h3>

`ch-keeper.yaml` と `ch-server.yaml` の両方でイメージのバージョンを更新し、サーバーのマニフェストを適用します。

```bash theme={"system"}
# ch-keeper.yaml と ch-server.yaml を編集し、イメージタグを変更します
kubectl apply -f ch-keeper.yaml
kubectl apply -f ch-server.yaml

# Pod を監視します
kubectl get pods -n clickhouse
```

<h3 id="upgrade-weave-trace">
  Weave Trace をアップグレードする
</h3>

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

```bash theme={"system"}
kubectl apply -f wandb-cr.yaml

# weave-trace Pod の再起動を監視します
kubectl get pods -n wandb | grep weave-trace
```

<h2 id="additional-resources">
  追加リソース
</h2>

* [取り込みサンプリングを設定する](/ja/products/wandb/weave/guides/platform/ingest-sampling): 受信したトレースの一部のみを保持することで、トレース量が多い場合のストレージコストと LLM によるスコアリングのコストを抑えられます。
* [Altinity ClickHouse Operator ドキュメント](https://docs.altinity.com/altinitykubernetesoperator/)
* [ClickHouse ドキュメント](https://clickhouse.com/docs)
* [W\&B Weave ドキュメント](/ja/products/wandb/weave)
* [ClickHouse S3 ストレージ設定](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#s3-virtual-hosted-style)

<h2 id="support">
  サポート
</h2>

本番環境へのデプロイメントや問題について：

* **CoreWeave Forge サポート**: `forge-support@coreweave.com`
* **ソリューションアーキテクト**: 超大規模なデプロイメント、個別のリソース規模の算定、デプロイメント計画について。
* **サポートリクエストに含める情報**:
  * `weave-trace`、ClickHouse Pod、オペレーターのログ。
  * W\&B のバージョン、ClickHouse バージョン、Kubernetes のバージョン。
  * クラスター情報とトレース量。

<h2 id="faq">
  よくある質問
</h2>

**Q: ClickHouse のレプリカを3つではなく1つだけ使用できますか？**

A: はい。ただし、本番環境では推奨されません。`ch-server.yaml` の設定を `replicasCount: 1` に変更し、`wandb-cr.yaml` で `clickhouse.replicated: false` を設定してください。

**Q: ClickHouse の代わりに別のデータベースを使用できますか？**

A: いいえ。Weave Trace には、高性能な列指向ストレージ機能を備えた ClickHouse が必要です。

**Q: S3 ストレージはどのくらい必要ですか？**

A: 必要な S3 ストレージ容量は、トレース量、保持期間、データ圧縮によって異なります。デプロイ後の実際の使用量を監視し、それに応じて調整してください。ClickHouse の列指向形式は、トレースデータを効率的に圧縮します。

**Q: ClickHouse で `database` 名を設定する必要がありますか？**

A: いいえ。weave-trace サービスが初回起動時に `weave` データベースを自動的に作成します。

**Q: クラスター名が `weavecluster` でない場合はどうすればよいですか？**

A: 環境変数 `WF_CLICKHOUSE_REPLICATED_CLUSTER` をクラスター名と一致するように設定する必要があります。一致しない場合、データベースの移行が失敗します。

**Q: 例に示されているセキュリティコンテキストをそのまま使用すべきですか？**

A: いいえ。このガイドに記載されている `runAsUser` や `fsGroup` などのセキュリティコンテキストは参考例です。組織のセキュリティポリシーに準拠するように調整する必要があります。特に OpenShift クラスターには、UID と GID の範囲に関する固有の要件があるため注意してください。

**Q: ClickHouse クラスターの規模が適切かどうかを確認するにはどうすればよいですか？**

A: 想定されるトレース量と使用パターンを W\&B Solutions Architect チームに伝えて相談してください。適切な規模に関する推奨事項が提供されます。デプロイメントのリソース使用量を監視し、必要に応じて調整してください。

**Q: 例で使用されている命名規則を変更できますか？**

A: はい。ただし、すべてのコンポーネント間で一貫性を保つ必要があります。

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

命名パターンと実際の名前の確認方法については、ステップ4の「Keeper の命名規則」セクションを参照してください。

**Q: クラスターのアンチアフィニティ要件が異なる場合はどうすればよいですか？**

A: ここに示すアンチアフィニティルールは、高可用性を確保するための推奨事項です。クラスターの規模、トポロジ、可用性要件に応じて調整または削除してください。小規模なクラスターや開発環境では、アンチアフィニティルールが不要な場合もあります。