Helm（v1.x） - ClickHouse Documentation

非推奨 — v1.x チャートこのページでは、メンテナンスモードとなっており、今後新機能が追加されない v1.x のインラインテンプレート Helm チャートについて説明します。新規デプロイには v2.x チャートを使用してください。既存の v1.x デプロイを移行する場合は、アップグレードガイドを参照してください。

ClickStack の Helm チャートはこちらで公開されており、本番環境へのデプロイに推奨される方法です。デフォルトでは、Helm チャートは以下を含むすべての中核コンポーネントをプロビジョニングします。

ClickHouse
HyperDX
OpenTelemetry (OTel) collector
MongoDB (永続的なアプリケーション状態用)

ただし、既存の ClickHouse デプロイメントと連携できるよう、簡単にカスタマイズすることもできます。たとえば、ClickHouse Cloud でホストされている環境に接続できます。このチャートは、以下を含む Kubernetes の標準的なベストプラクティスをサポートしています。

values.yaml による環境ごとの設定
リソース制限とポッドレベルのスケーリング
TLS とイングレスの設定
シークレット管理と認証の設定

適した用途

概念実証
本番環境

デプロイ手順

前提条件

Helm v3+
Kubernetes クラスター (v1.20+ 推奨)
ご利用のクラスターとやり取りできるように kubectl が設定されていること

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

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

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

ClickStack のインストール

デフォルト値で ClickStack チャートをインストールするには:

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 を使用してイングレスを設定してください。詳しい設定手順については、Ingress Configuration ガイドを参照してください。

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

設定例：

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

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

シークレットの使用 (任意)

API キーやデータベース認証情報などの機密データを扱うには、Kubernetes のシークレットを使用します。HyperDX の Helm チャートには、変更してクラスターに適用できるデフォルトのシークレットファイルが用意されています。

事前設定済みシークレットの使用

Helm チャートには、charts/clickstack/templates/secrets.yaml にあるデフォルトのシークレットテンプレートが含まれています。このファイルは、シークレットを管理するための基本構成を提供します。シークレットを手動で適用する必要がある場合は、提供されている secrets.yaml テンプレートを編集して適用します。

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

シークレットをクラスターに適用します。

kubectl apply -f secrets.yaml

カスタムシークレットの作成

必要に応じて、カスタム Kubernetes シークレットを手動で作成することもできます：

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

Secretを参照する

values.yaml でSecretを参照するには:

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

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

Using ClickHouse Cloud

ClickHouse Cloud を使用する場合は、Helm チャートでデプロイした ClickHouse インスタンスを無効にし、Cloud の認証情報を指定します。

# ClickHouse Cloud の認証情報を指定する
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # 完全な https URL
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# デフォルト接続を上書きする方法
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

または、values.yaml ファイルを使用します:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# すでにインストール済みの場合...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

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

本番環境に関する注意

デフォルトでは、このチャートによって ClickHouse と OTel collector もインストールされます。ただし、本番環境では、ClickHouse と OTel collector は個別に管理することを推奨します。 ClickHouse と OTel collector を無効にするには、次の値を設定します。

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

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

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

タスク設定

デフォルトでは、チャート設定には CronJob として 1 つのタスクが含まれており、アラートを発報する必要があるかどうかを確認します。設定オプションは以下のとおりです。

パラメーター	説明	デフォルト
`tasks.enabled`	クラスター内の cron タスクの有効/無効を切り替えます。デフォルトでは、HyperDX イメージがプロセス内で cron タスクを実行します。クラスター内で別個の cron タスクを使用する場合は、true に変更してください。	`false`
`tasks.checkAlerts.schedule`	check-alerts タスクの cron スケジュール	`/1 * * *`
`tasks.checkAlerts.resources`	check-alerts タスクのリソース要求と上限	`values.yaml` を参照

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

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

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

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

helm search repo clickstack

v2.x へのアップグレードv2.x のサブチャートベースのチャートに移行する場合は、移行手順についてアップグレードガイドを参照してください。これは破壊的変更であり、インプレースでの helm upgrade はサポートされていません。

ClickStack のアンインストール

デプロイメントを削除するには:

helm uninstall my-clickstack

これにより、リリースに関連するすべてのリソースは削除されますが、永続データ (存在する場合) は残る可能性があります。

トラブルシューティング

ログの確認

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 デプロイメントのトラブルシューティングについては、次を参照してください。

イングレス Troubleshooting - アセットの配信、パスの書き換え、ブラウザーの問題
Cloud Deployments - GKE OpAMP の問題や Cloud 固有の問題

スキーマの選択: Map と JSON

ClickStack は、デフォルトで属性を Map(LowCardinality(String), String) カラムとして保存します。これは、オブザーバビリティのワークロードに推奨されるスキーマです。bucketed map serialization と、Map のキーおよび値に対するテキスト索引を組み合わせることで、動的な JSON サブカラムのようにキーごとの取り込みオーバーヘッドを発生させることなく、必要なルックアップだけを効率的に実行できます。 JSON 型のスキーマは、属性キーの集合が小さく安定しているワークロードで評価するためのベータ機能として利用できます。これはデフォルトとしては推奨されません。詳しい比較と、JSON サポートを有効にするために必要な環境変数については、Map と JSON 型の比較を参照してください。

v1.x デプロイガイド

デプロイオプション (v1.x) - 外部 ClickHouse、OTel collector、最小構成でのデプロイ
設定ガイド (v1.x) - APIキー、シークレット、イングレスの設定
Cloud デプロイ (v1.x) - GKE、EKS、AKS の構成と本番環境向けベストプラクティス

v2.x ドキュメント

Helm (v2.x) - v2.x のデプロイガイド
アップグレードガイド - v1.x から v2.x への移行ガイド

追加リソース

ClickStack 入門ガイド - ClickStack の概要
ClickStack Helm チャートリポジトリ - チャートのソースコードと values のリファレンス
Kubernetes ドキュメント - Kubernetes リファレンス
Helm ドキュメント - Helm リファレンス

​適した用途

​デプロイ手順

​前提条件

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

​ClickStack のインストール

​インストールを確認する

​ポートフォワーディング

​UI にアクセスする

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

​シークレットの使用 (任意)

​事前設定済みシークレットの使用

​カスタムシークレットの作成

​Secretを参照する

​Using ClickHouse Cloud

​本番環境に関する注意

​タスク設定

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

​ClickStack のアンインストール

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

​ログの確認

​インストールに失敗した場合のデバッグ

​デプロイの確認

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

​関連ドキュメント

​v1.x デプロイガイド

​v2.x ドキュメント

​追加リソース

適した用途

デプロイ手順

前提条件

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

ClickStack のインストール

インストールを確認する

ポートフォワーディング

UI にアクセスする

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

シークレットの使用 (任意)

事前設定済みシークレットの使用

カスタムシークレットの作成

Secretを参照する

Using ClickHouse Cloud

本番環境に関する注意

タスク設定

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

ClickStack のアンインストール

トラブルシューティング

ログの確認

インストールに失敗した場合のデバッグ

デプロイの確認

スキーマの選択: Map と JSON

関連ドキュメント

v1.x デプロイガイド

v2.x ドキュメント

追加リソース