- Altinity ClickHouse Operator: Kubernetes 向けのエンタープライズグレードの ClickHouse 管理。
- ClickHouse Keeper: 分散コーディネーションサービス (ZooKeeper の代替) 。
- ClickHouse Cluster: トレースストレージ向けの高可用性データベースクラスター。
- S3互換 storage: ClickHouse データを永続化するためのオブジェクトストレージ。
重要なセットアップ上の注意
- セキュリティとコンプライアンス: 組織のセキュリティポリシーおよび Kubernetes または OpenShift の要件に合わせて、セキュリティコンテキスト、
runAsUserまたはfsGroupの値、その他のセキュリティ設定を調整してください。 - リソースのサイジング: ここに示すリソース割り当ては出発点にすぎません。想定されるトレース量とパフォーマンス要件に基づく適切なサイジングについては、W&B Solutions Architect チームに相談してください。
- インフラストラクチャー固有の事項: ストレージクラス、ノードセレクター、その他のインフラストラクチャー固有の設定を、使用する環境に合わせて更新してください。
アーキテクチャ
前提条件
- Kubernetes クラスター: バージョン 1.29 以降。
- Kubernetes ノード: マルチノード クラスター (高可用性のため、少なくとも 3 ノードを推奨) 。
- Storage class: 永続ボリューム用の有効な StorageClass (例:
gp3、standard、nfs-csi) 。 - S3 bucket: 適切なアクセス権限が設定された、事前構成済みの S3 または S3互換バケット。
- W&B Platform: すでにインストールされ、稼働していること。W&B Self-Managed Deployment Guideを参照してください。
- W&B license: W&B Support が提供する Weave 対応ライセンス。
必須ツール
- クラスターにアクセスできるよう設定された
kubectl。 - バージョン3.0以降の
helm。 - AWS認証情報 (S3を使用する場合) 、またはS3互換ストレージへのアクセス。
ネットワーク要件
clickhousenamespace 内の Pod は、wandbnamespace 内の Pod と通信できる必要があります。- ClickHouse ノード同士は、ポート
8123、9000、9009、2181を介して通信できる必要があります。
セルフマネージド Weave インスタンスをデプロイする
Altinity ClickHouse Operator をデプロイする
Altinity Helmリポジトリを追加する
Operator の設定を作成
ch-operator.yaml という名前のファイルを作成します。このファイルでは、operator デプロイメントのセキュリティコンテキストとメタデータを定義します。
containerSecurityContext の値は、ほとんどの Kubernetes ディストリビューションで使用できます。OpenShift では、プロジェクトに割り当てられている UID 範囲に合わせて runAsUser と fsGroup を調整する必要がある場合があります。
operatorをインストールする
operator がインストールされていることを確認する
S3ストレージを準備する
S3バケットを作成する
[BUCKET-NAME] をバケット名に、[REGION] を AWS リージョンに置き換えてください。
S3認証情報を設定する
オプション A: AWS IAM ロールを使用する (IRSA、AWS では推奨)
オプション B: アクセスキーを使用する
[ACCESS-KEY] は AWS アクセスキーに、[SECRET-KEY] は AWS シークレットキーに置き換えてください。
ClickHouse Keeper をデプロイする
Keeper の設定を作成する
ch-keeper.yaml という名前のファイルを作成します。このマニフェストは、anti-affinity、永続ストレージ、および Altinity Operator が Keeper Pod をプロビジョニングする際に使用する設定を含む、3 レプリカの Keeper クラスターを定義します。
- 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 ホスト名を必ず更新してください。
ClickHouse Keeperをデプロイする
Keeper のデプロイを確認する
ClickHouse クラスターをデプロイする
ClickHouse サーバー設定を作成する
ch-server.yaml という名前のファイルを作成します。このマニフェストでは、ClickHouse クラスター、Keeper への接続、Weave ユーザーアカウント、そしてトレースデータに使用する S3 ストレージポリシーを定義します:
- StorageClass:
storageClassName: gp3を、お使いのクラスターの StorageClass に合わせて更新します。 - S3 endpoint:
[BUCKET-NAME]と[REGION]を実際の値に置き換えます。 - Cache size:
<max_size>40Gi</max_size>は、永続ボリュームのサイズ (50Gi) より小さくする必要があります。 - セキュリティコンテキスト:
runAsUser、fsGroup、およびその他のセキュリティ設定を、組織のポリシーに合わせて調整します。 - Resource allocation: CPU とメモリの値はあくまで例です。想定されるトレース量に基づく適切なサイジングについては、W&B Solutions Architect に相談してください。
- Anti-affinity rules: クラスターのトポロジと高可用性の要件に応じて、カスタマイズするか削除します。
- Keeper hostnames: Keeper ノードのホスト名は、ステップ 3 の Keeper デプロイメントの命名 (「Keeper naming」) と一致している必要があります。
- Cluster naming: クラスター名
weaveclusterは変更できますが、ステップ 5 のWF_CLICKHOUSE_REPLICATED_CLUSTERの値と一致している必要があります。 - Credentials:
- IRSA の場合:
<use_environment_credentials>true</use_environment_credentials>をそのまま使用するか、環境変数にマッピングされたシークレットキーを使用します。
- IRSA の場合:
S3 の設定を更新する
ch-server.yaml の storage_configuration.xml セクションを編集します。
AWS S3 の設定例:
認証情報を設定する (Option B のみ)
ch-server.yaml の env セクションでそのシークレットを参照していることを確認してください。
env セクション全体を削除してください。
Keeper の命名
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 の名前空間です (例:clickhouse) 。
metadata.name: myweave) :
clusters[0].name: coordination) をカスタマイズする場合:
ch-server.yaml 内の Keeper ホスト名は、Keeper のデプロイによって作成された実際のサービス名と完全に一致している必要があります。一致していない場合、ClickHouse サーバーはコーディネーションサービスへの接続に失敗します。ClickHouse クラスターのリソースをデプロイする
ClickHouse デプロイを確認する
W&B Platform で Weave を有効にする
weave-trace サービスを有効にします。
ClickHouse の接続情報を確認する
- ホスト:
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
W&B Custom Resource を更新する
clickhouse.replicated: true: 3 レプリカを使用する場合は必須です。WF_CLICKHOUSE_REPLICATED: "true": レプリケーション構成では必須です。WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster":ch-server.yamlのクラスター名と一致する必要があります。
ここに示したセキュリティコンテキスト、リソース割り当て、およびその他の Kubernetes 固有の設定は参考例です。組織の要件に合わせて適宜カスタマイズし、適切なリソースサイジングについては W&B Solutions Architect チームに相談してください。
更新した設定を適用する
Weave Trace のデプロイを確認する
Weave データベースを初期化する
データベースの移行を監視する
データベースが作成されていることを確認します
Weave が有効になっていることを確認する
W&B Console にアクセスする
Weave ライセンスの状態を確認する
- Top Right Menu > Organization Dashboard に移動します。
- Weave access が有効になっていることを確認します。
Weave の機能をテストする
トラブルシューティング
ClickHouse Keeper の問題
Pending 状態のままになっている
解決策: 考えられる複数の原因を確認します。
- PVC と StorageClass の問題:
- アンチアフィニティとノードの可用性:
- アンチアフィニティでは 3 つの別々のノードが必要ですが、クラスター内のノード数が不足している
- ノードに、pod の要求を満たすのに十分な CPU / メモリがない
- ノードの taint によって pod をスケジュールできない
- ノード数が 3 未満の場合は、アンチアフィニティルールを削除または調整する
- より緩やかなアンチアフィニティにするには、
requiredDuringSchedulingIgnoredDuringExecutionではなくpreferredDuringSchedulingIgnoredDuringExecutionを使用する - ノードのリソースが不足している場合は、リソース要求を減らす
- クラスターにノードを追加する
問題: Keeper pod が
CrashLoopBackOff になる
解決策: ログを確認し、設定を検証する:
- セキュリティコンテキストの誤り (
runAsUserとfsGroupを確認)。 - ボリュームの権限に関する問題。
- ポートの競合。
ch-keeper.yamlの設定エラー。
ClickHouse サーバーの問題
問題: ClickHouse が Keeper に接続できません 解決策: Keeper の endpoints と Naming を確認してください:
ch-server.yaml 内の Keeper ホスト名が実際の Keeper デプロイと一致していない可能性があります。命名規則については、ステップ 4 の “Keeper の命名規則” を参照してください。
Weave Trace の問題
weave-trace pod が起動しない
解決策: ClickHouse への接続を確認してください:
問題: Console で Weave が有効と表示されない 解決策: 設定を確認します。
-
ライセンスに Weave が含まれていることを確認します。
-
wandb-cr.yamlでweave-trace.enabled: trueとclickhouse.replicated: trueが設定されていることを確認します。 -
W&B operator のログを確認します。
問題: データベースの移行に失敗する 解決策: クラスター名が一致していることを確認します。
WF_CLICKHOUSE_REPLICATED_CLUSTER 環境変数は、ch-server.yaml 内のクラスター名と一致している必要があります:
リソース要件
本番環境の最小構成
開発、テスト、またはトラフィック量が少ない本番環境に適しています。
推奨される本番構成
高トレース量の本番環境に適しています。
超高ボリュームのデプロイについては、トレース量やパフォーマンス要件に応じたカスタムのサイジング推奨事項について、W&B Solutions Architect チームにお問い合わせください。
高度な設定
ClickHouse をスケールする
-
垂直スケーリング: pod ごとのリソースを増やします (より簡単な方法)。
推奨事項: 実際のリソース使用量を監視し、それに応じてスケールしてください。非常に大規模なデプロイを行う場合は、W&B Solutions Architect チームにお問い合わせください。
-
水平スケーリング: レプリカを追加します (慎重な計画が必要です)。
- レプリカを増やすには、データの再分散が必要です。
- シャード管理については ClickHouse のドキュメントを参照してください。
- 本番環境で水平スケーリングを実施する前に、W&B Solutions Architect にお問い合わせください。
異なるバージョンの ClickHouse を使用する
ch-keeper.yaml と ch-server.yaml の両方でイメージタグを更新します。
ClickHouse を監視する
バックアップとリカバリ
セキュリティに関する考慮事項
- Credentials: ClickHouse のパスワードは、プレーンテキストではなく Kubernetes シークレットに保存してください。
- Network policies: ClickHouse へのアクセスを制限するため、NetworkPolicies の実装を検討してください。
- RBAC: サービスアカウントには、必要最小限の権限のみを付与してください。
- S3 bucket: 保存時の暗号化を有効にし、bucket へのアクセスは必要な IAM ロールのみに制限してください。
- TLS: 任意です。本番環境では、ClickHouse クライアント接続で TLS を有効にしてください。
アップグレード
ClickHouse を Weave と Models の OLAP 機能の両方で使用するセルフマネージドのデプロイでは、両方のプロダクトのバージョン要件を満たす必要があります。Models の OLAP 機能と Weave では、必要な ClickHouse のバージョン要件が異なる場合があります。ClickHouse または W&B Server をアップグレードする前に、アップグレード時の ClickHouse 互換性とサポートされる W&B Server リリースを参照してください。ClickHouse Server と ClickHouse Keeper は一緒にアップグレードしてください。
ClickHouse Operator のアップグレード
ClickHouse Server のアップグレード
ch-keeper.yaml と ch-server.yaml の両方でイメージのバージョンを更新してから、サーバーのマニフェストを適用します:
Weave Trace のアップグレード
wandb-cr.yaml のイメージタグを更新して、適用します。
参考資料
サポート
- W&B サポート:
support@wandb.com - ソリューションアーキテクト: 超大規模デプロイ、カスタムサイジング、デプロイ計画について。
- サポートへの問い合わせに含める内容:
weave-trace、ClickHouse pod、operator のログ。- W&B バージョン、ClickHouse バージョン、Kubernetes バージョン。
- クラスター情報とトレース量。
FAQ
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: はい。ただし、すべてのコンポーネント間で一貫性を維持する必要があります。
- ClickHouse Keeper 名:
ch-server.yamlのzookeeper.nodesセクションにある Keeper ノードのホスト名と一致している必要があります。 - ClickHouse クラスター名 (
weavecluster):wandb-cr.yamlのWF_CLICKHOUSE_REPLICATED_CLUSTERと一致している必要があります。 - ClickHouse インストール名:
weave-traceが使用するサービスのホスト名に影響します。