Helm - ClickHouse Documentation

チャートバージョン 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 など) をデプロイするための追加マニフェスト

適した用途

概念実証
本番環境

デプロイ手順

前提条件

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

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

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

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

Operator をインストールする

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

helm install clickstack-operators clickstack/clickstack-operators

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

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

ClickStack をインストールする

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

helm install my-clickstack clickstack/clickstack

インストールの確認

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

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

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

ポートフォワード

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

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

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

UI に移動する

HyperDX UI を開くには、http://localhost:8080 にアクセスします。要件を満たすユーザー名とパスワードを入力して、ユーザーを作成します。Create をクリックすると、Helm チャートでデプロイされた ClickHouse インスタンス用のデータソースが作成されます。

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

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

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 リファレンス

​適した用途

​デプロイ手順

​Using ClickHouse Cloud

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

​タスク設定

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

​ClickStack のアンインストール

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

​ログの確認

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

​デプロイの確認

​スキーマの選択: Map と JSON

​関連ドキュメント

​デプロイメントガイド

​v1.x ドキュメント

​参考資料

適した用途

デプロイ手順

Using ClickHouse Cloud

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

タスク設定

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

ClickStack のアンインストール

トラブルシューティング

ログの確認

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

デプロイの確認

スキーマの選択: Map と JSON

関連ドキュメント

デプロイメントガイド

v1.x ドキュメント

参考資料