Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm（v1.x）

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

本番環境に関する注意

デフォルトでは、このチャートによって 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

タスク設定

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

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

スキーマの選択: Map と JSON

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

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

v1.x デプロイガイド

v2.x ドキュメント

追加リソース

Navigation