Helm

Helm を使用した ClickStack のデプロイ - ClickHouse オブザーバビリティスタック

チャートバージョン 2.x

このページでは、v2.x のサブチャートベースの Helm チャートについて説明します。まだ v1.x のインラインテンプレートチャートを使用している場合は、v1.x Helm ガイドを参照してください。移行手順については、アップグレード ガイドを参照してください。

ClickStack の Helm チャートはこちらにあり、本番環境へのデプロイにはこの方法が推奨されています。

v2.x チャートでは、2 段階のインストールを採用しています。まず clickstack-operators チャートでオペレーターと CRD をインストールし、その後メインの clickstack チャートで、ClickHouse、MongoDB、OpenTelemetry Collector 用のオペレーター管理カスタムリソースを作成します。

デフォルトでは、Helm チャートは次のコアコンポーネントをすべてプロビジョニングします。

• ClickHouse — ClickHouseCluster および KeeperCluster カスタムリソースを通じて ClickHouse Operator により管理
• HyperDX — オブザーバビリティ UI と API
• OpenTelemetry (OTel) collector — サブチャートとして 公式の OpenTelemetry Collector Helm チャート を使用してデプロイ
• MongoDB — MongoDBCommunity カスタムリソースを通じて MongoDB Kubernetes Operator (MCK) により管理

ただし、既存の ClickHouse デプロイメントと統合できるよう、簡単にカスタマイズすることも可能です。たとえば、ClickHouse Cloud でホストされている環境と統合できます。

このチャートは、以下のような Kubernetes の標準的なベストプラクティスをサポートしています。

• values.yaml による環境別の設定
• リソース制限とポッドレベルのスケーリング
• TLS とイングレスの設定
• シークレット管理と認証の設定
• チャートとあわせて任意の Kubernetes オブジェクト (NetworkPolicy、HPA、ALB Ingress など) をデプロイするための追加マニフェスト

​

適した用途

• 概念実証
• 本番環境

​

デプロイ手順

1. ​

   前提条件

   • Helm v3+
   • Kubernetes クラスター (v1.20+ 推奨)
   • クラスターに接続できるように設定された kubectl
2. ​

   ClickStack の Helm リポジトリを追加する

   ClickStack の Helm リポジトリを追加します:

   helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
   helm repo update
   
3. ​

   Operator をインストールする

   まず、Operator のチャートをインストールします。これにより、メインチャートに必要な CRD が登録されます。

   helm install clickstack-operators clickstack/clickstack-operators
   

   次に進む前に、オペレーターのポッドの準備が完了するまで待ちます:

   kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
   
4. ​

   ClickStack をインストールする

   オペレーターが起動したら、メインの Helm チャートをインストールします。

   helm install my-clickstack clickstack/clickstack
   
5. ​

   インストールの確認

   インストールを確認します。

   kubectl get pods -l "app.kubernetes.io/name=clickstack"
   

   すべてのポッドの準備が整ったら、次に進んでください。

6. ​

   ポートフォワード

   ポートフォワードを使用すると、HyperDX にアクセスしてセットアップできます。本番環境にデプロイする場合は、適切なネットワークアクセス、TLS 終端、スケーラビリティを確保するため、代わりにイングレスまたはロードバランサー経由でサービスを公開してください。ポートフォワードは、ローカル開発や一時的な管理作業には適していますが、長期運用や高可用性が求められる環境には向きません。

   kubectl port-forward \
     pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
     8080:3000
   

   本番環境向けイングレス設定

   本番環境でデプロイする場合は、ポートフォワーディングではなく、TLS を使用してイングレスを設定してください。詳しい設定手順については、イングレス設定ガイドを参照してください。

7. ​

   UI に移動する

   HyperDX UI を開くには、http://localhost:8080 にアクセスします。

   要件を満たすユーザー名とパスワードを入力して、ユーザーを作成します。

   Create をクリックすると、Helm チャートでデプロイされた ClickHouse インスタンス用のデータソースが作成されます。

   デフォルト接続の上書き

   統合された ClickHouse インスタンスへのデフォルト接続は上書きできます。詳細は、“Using ClickHouse Cloud” を参照してください。

8. ​

   values のカスタマイズ (任意)

   --set フラグを使って設定をカスタマイズできます。たとえば、

   helm install my-clickstack clickstack/clickstack --set key=value
   

   または、values.yaml を編集します。デフォルト値を取得するには、

   helm show values clickstack/clickstack > values.yaml
   

   設定例:

   hyperdx:
     frontendUrl: "https://hyperdx.example.com"
   
     deployment:
       replicas: 2
       resources:
         limits:
           cpu: "2"
           memory: 4Gi
         requests:
           cpu: 500m
           memory: 1Gi
   
     ingress:
       enabled: true
       host: hyperdx.example.com
       tls:
         enabled: true
         tlsSecretName: "hyperdx-tls"
   

   helm install my-clickstack clickstack/clickstack -f values.yaml
   
9. ​

   Secret の使用 (任意)

   v2.x チャートでは、values の hyperdx.secrets から設定される単一の Secret (clickstack-secret) を使用します。ClickHouse のパスワード、MongoDB のパスワード、HyperDX の API key を含むすべての機密環境変数は、この 1 つの Secret を通じて扱われます。

   Secret の値を上書きするには:

   hyperdx:
     secrets:
       HYPERDX_API_KEY: "your-api-key"
       CLICKHOUSE_PASSWORD: "your-clickhouse-password"
       CLICKHOUSE_APP_PASSWORD: "your-app-password"
       MONGODB_PASSWORD: "your-mongodb-password"
   

   外部のシークレット管理 (secrets operator の使用など) では、既存の Kubernetes Secret を参照できます：

   hyperdx:
     useExistingConfigSecret: true
     existingConfigSecret: "my-external-secret"
     existingConfigConnectionsKey: "connections.json"
     existingConfigSourcesKey: "sources.json"
   

   API キーの管理

   複数の設定方法やポッドの再起動手順を含む API キーの詳しい設定方法については、API キーのセットアップガイドを参照してください。

​

Using ClickHouse Cloud

ClickHouse Cloud を使用する場合は、組み込みの ClickHouse インスタンスを無効にし、ClickHouse Cloud の認証情報を指定します。

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

接続用のSecretを別途作成します：

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

helm install my-clickstack clickstack/clickstack -f values-clickhouse-cloud.yaml

高度な外部設定

secret ベースの設定、外部 OTel collector、または最小構成での本番デプロイについては、デプロイメントオプション ガイドを参照してください。

​

本番環境に関する注意事項

デフォルトでは、このチャートによってClickHouse、MongoDB、OTel collectorがインストールされます。本番環境では、ClickHouse と OTel collector は個別に管理することを推奨します。

ClickHouse と OTel collector を無効にするには:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

本番環境のベストプラクティス

高可用性構成、リソース管理、イングレス/TLS の設定、クラウド固有の構成 (GKE、EKS、AKS) を含む本番環境へのデプロイについては、次を参照してください。

• 設定ガイド - イングレス、TLS、シークレットの管理
• Cloud デプロイメント - Cloud 固有の設定と本番環境向けチェックリスト

​

タスク設定

デフォルトでは、チャートの設定には CronJob として 1 つのタスクがあり、アラートを発報すべきかどうかを確認します。v2.x では、タスク設定は hyperdx.tasks 配下に移動しました。

Parameter	Description	Default
hyperdx.tasks.enabled	クラスター内の cron タスクを有効/無効にします。デフォルトでは、HyperDX イメージがプロセス内で cron タスクを実行します。クラスター内で別の cron タスクを使用したい場合は、true に変更してください。	false
hyperdx.tasks.checkAlerts.schedule	check-alerts タスクの Cron スケジュール	*/1 * * * *
hyperdx.tasks.checkAlerts.resources	check-alerts タスクのリソースのリクエストと上限	values.yaml を参照

​

チャートのアップグレード

新しいバージョンにアップグレードするには:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

利用可能なチャートのバージョンを確認するには:

helm search repo clickstack

v1.x からアップグレードする場合

v1.x の inline-template チャート からアップグレードする場合は、移行手順について Upgrade guide を参照してください。これは破壊的変更のため、インプレースでの helm upgrade はサポートされていません。

​

ClickStack のアンインストール

逆の順序でアンインストールします。

helm uninstall my-clickstack            # アプリとCRを先に削除
helm uninstall clickstack-operators     # operatorとCRDを削除

注: MongoDB および ClickHouse Operator によって作成された PersistentVolumeClaims は、helm uninstall を実行しても削除されません。これは、意図しないデータ損失を防ぐための仕様です。PVC をクリーンアップするには、以下を参照してください。

• MongoDB Kubernetes Operator docs

​

トラブルシューティング

​

ログの確認

kubectl logs -l app.kubernetes.io/name=clickstack

​

インストール失敗時のデバッグ

helm install my-clickstack clickstack/clickstack --debug --dry-run

​

デプロイの確認

kubectl get pods -l app.kubernetes.io/name=clickstack

追加のトラブルシューティング リソース

イングレス固有の問題、TLS の問題、または Cloud デプロイのトラブルシューティングについては、以下を参照してください。

• Ingress Troubleshooting - アセット配信、パスの書き換え、ブラウザーの問題
• Cloud デプロイメント - GKE OpAMP の問題や Cloud 固有の問題

​

スキーマの選択: Map と JSON

ClickStack は、デフォルトで属性を Map(LowCardinality(String), String) カラムとして保存します。これは、オブザーバビリティのワークロードに推奨されるスキーマです。bucketed map serialization と、Map のキーおよび値に対するテキスト索引を組み合わせることで、動的な JSON サブカラムのようにキーごとの取り込みオーバーヘッドを発生させることなく、必要なルックアップだけを効率的に実行できます。

JSON 型のスキーマは、属性キーの集合が小さく安定しているワークロードで評価するためのベータ機能として利用できます。これはデフォルトとしては推奨されません。詳しい比較と、JSON サポートを有効にするために必要な環境変数については、Map と JSON 型の比較 を参照してください。

​

関連ドキュメント

​

デプロイメントガイド

• デプロイメントオプション - 外部 ClickHouse、OTel collector、最小構成のデプロイメント
• 設定ガイド - API keys、シークレット、イングレスの設定
• Cloud デプロイメント - GKE、EKS、AKS の設定と本番環境向けのベストプラクティス
• アップグレードガイド - v1.x から v2.x への移行
• 追加マニフェスト - チャート とあわせてカスタム Kubernetes オブジェクトをデプロイ

​

v1.x ドキュメント

• Helm (v1.x) - v1.x デプロイメントガイド
• 設定 (v1.x) - v1.x 設定
• デプロイメントオプション (v1.x) - v1.x デプロイメントオプション
• Cloud デプロイメント (v1.x) - v1.x Cloud 設定

​

参考資料

• ClickStack スタートガイド - ClickStack の紹介
• ClickStack Helm チャート リポジトリ - チャートのソースコードと values のリファレンス
• Kubernetes ドキュメント - Kubernetes リファレンス
• Helm ドキュメント - Helm リファレンス