Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

ただし、既存の 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

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"

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

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

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

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

clickhouse:
  enabled: false

otel-collector:
  enabled: false

タスク設定

デフォルトでは、チャートの設定には 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

ClickStack のアンインストール

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

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

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

トラブルシューティング

ログの確認

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

スキーマの選択: Map と JSON

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

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

デプロイメントガイド

v1.x ドキュメント

参考資料

Navigation