メインコンテンツへスキップ
メインコンテンツへスキップ

Helm

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

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

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

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

デフォルトでは、Helm チャートは以下を含むすべての主要コンポーネントをプロビジョニングします。

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

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

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

適した用途​

  • 概念実証 (PoC)
  • 本番環境

デプロイ手順​


前提条件​

  • Helm v3+
  • Kubernetes クラスター (v1.20+ 推奨)
  • クラスターに接続できるよう設定済みの kubectl

ClickStack Helm リポジトリを追加​

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

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

オペレーターをインストールする​

最初にオペレーターチャートをインストールします。これにより、メインチャートに必要な CRD が登録されます。

helm install clickstack-operators clickstack/clickstack-operators

先に進む前に、operator のポッドが準備完了になるまで待機します。

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

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

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

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

HyperDX UI

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

デフォルト接続の上書き

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

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

--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

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

v2.x チャートでは、values の hyperdx.secrets から生成される統合シークレット (clickstack-secret) を使用します。ClickHouse のパスワード、MongoDB のパスワード、HyperDX API キーなど、すべての機密環境変数はこの単一のシークレットを通して管理されます。

シークレットの値を上書きするには:

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

外部シークレット管理 (シークレットオペレーターを使用する場合など) では、既存のKubernetesシークレットを参照できます:

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-external-secret"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"
API キー管理

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

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"

接続用シークレットを別途作成します。

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
進階の外部構成

シークレットベースの構成、外部 OTel collector、または最小限の構成で本番環境にデプロイする場合は、デプロイメントオプション ガイドを参照してください。

本番環境での注意点​

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

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

clickhouse:
  enabled: false

otel-collector:
  enabled: false
本番環境のベストプラクティス

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

タスク設定​

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

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

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

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

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

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

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

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

ClickStack のアンインストール​

インストールした順と逆の順序でアンインストールします:

helm uninstall my-clickstack            # Remove app + CRs first
helm uninstall clickstack-operators     # Remove operators + CRDs

注意: MongoDB および ClickHouse のオペレーターが作成した PersistentVolumeClaim は、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
追加のトラブルシューティング情報

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

JSON 型サポート​

Beta feature. Learn more.
ベータ機能 - 本番環境向けではありません

ClickStack における JSON 型サポートは ベータ機能 です。JSON 型自体は ClickHouse 25.3+ では本番環境向けとして利用可能ですが、ClickStack との統合はまだ積極的に開発中であり、制限があったり、将来的に変更されたり、不具合を含む可能性があります。

ClickStack では、バージョン 2.0.4 以降で JSON 型 をベータ機能としてサポートしています。

この型の利点については JSON 型の利点 を参照してください。

JSON 型のサポートを有効にするには、以下の環境変数を設定する必要があります。

  • OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - OTel collector でのサポートを有効にし、スキーマが JSON 型を使用して作成されるようにします。
  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true (ClickStack オープンソース版のみ) - ClickStack UI アプリケーションでのサポートを有効にし、JSON データに対してクエリを実行できるようにします。

これらの環境変数は、values.yaml の hyperdx.config で設定できます。

hyperdx:
  config:
    BETA_CH_OTEL_JSON_SCHEMA_ENABLED: "true"
    OTEL_AGENT_FEATURE_GATE_ARG: "--feature-gates=clickhouse.json"

または --set で:

helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.config.BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true" \
  --set "hyperdx.config.OTEL_AGENT_FEATURE_GATE_ARG=--feature-gates=clickhouse.json"

デプロイガイド​

v1.x ドキュメント​

追加リソース​