Helm

Chart Migration

現在 hdx-oss-v2 チャートを使用している場合は、clickstack チャートへ移行してください。hdx-oss-v2 チャートはメンテナンスモードとなっており、新機能は今後追加されません。新規開発はすべて clickstack チャートに集約されており、同等の機能を提供しつつ、名称と構成が改善されています。

HyperDX 用の Helm チャートはこちらで公開されており、本番環境へのデプロイにはこの方法を推奨します。

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

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

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

このチャートは、以下を含む一般的な Kubernetes のベストプラクティスをサポートします:

values.yaml を用いた環境別設定
リソース制限およびポッド単位のスケーリング
TLS およびイングレスの設定
シークレット管理および認証設定

適した用途

検証・PoC
本番運用

デプロイ手順

前提条件

Helm v3 以降
Kubernetes クラスター（v1.20 以降を推奨）
クラスターとやり取りできるように設定済みの kubectl

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

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

helm repo add clickstack https://hyperdxio.github.io/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を使用したイングレスを構成してください。詳細な設定手順については、イングレス設定ガイドを参照してください。

UIへ移動する

http://localhost:8080 にアクセスして HyperDX UI を開きます。

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

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

デフォルト接続の上書き

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

代替のClickHouseインスタンスを使用する例については、"ClickHouse Cloud接続を作成する"を参照してください。

値のカスタマイズ（任意）

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

シークレットの参照

values.yamlでシークレットを参照する方法:

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

APIキー管理

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

ClickHouse Cloud の使用

ClickHouse Cloud を使用する場合は、Helm チャートでデプロイされる ClickHouse インスタンスを無効化し、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": "外部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、または最小構成で本番環境にデプロイする場合は、Deployment Options ガイドを参照してください。

本番環境向けの注意事項

デフォルトでは、このチャートは 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）を含む本番環境向けデプロイについては、以下を参照してください：

Configuration Guide - イングレス、TLS、およびシークレット管理
Cloud Deployments - クラウド固有の設定と本番環境チェックリスト

タスク設定

デフォルトでは、アラートを発火させる必要があるかどうかをチェックする 1 つのタスクが、CronJob としてチャート内に設定されています。以下はその設定オプションです。

Parameter	Description	Default
`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

追加のトラブルシューティング用リソース

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

Ingress のトラブルシューティング - アセット配信、パス書き換え、ブラウザ関連の問題
Cloud Deployments - GKE の OpAMP に関する問題およびクラウド特有の問題

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 - HyperDX アプリケーションでのサポートを有効にし、JSON データに対してクエリを実行できるようにします。

ユーザーは、パラメータまたは values.yaml を用いてこれらの環境変数を設定できます。例:

values.yaml

hyperdx:
  ...
  env:
    - name: BETA_CH_OTEL_JSON_SCHEMA_ENABLED
      value: "true"

otel:
  ...
  env:
    - name: OTEL_AGENT_FEATURE_GATE_ARG
      value: "--feature-gates=clickhouse.json"

または --set で:

helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.env[0].name=BETA_CH_OTEL_JSON_SCHEMA_ENABLED" \
  --set "hyperdx.env[0].value=true" \
  --set "otel.env[0].name=OTEL_AGENT_FEATURE_GATE_ARG" \
  --set "otel.env[0].value=--feature-gates=clickhouse.json"

デプロイメントガイド

デプロイメントオプション - 外部 ClickHouse、OTel collector、最小構成デプロイメント
設定ガイド - API キー、シークレット、イングレスのセットアップ
クラウドデプロイメント - GKE、EKS、AKS の設定および本番環境向けベストプラクティス

追加リソース

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

適した用途​

デプロイ手順​

前提条件​

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

ClickStackのインストール​

インストールの確認​

ポートのフォワード​

UIへ移動する​

値のカスタマイズ（任意）​

シークレットの使用（オプション）​

事前設定されたシークレットの使用​

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

シークレットの参照​

ClickHouse Cloud の使用​

本番環境向けの注意事項​

タスク設定​

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

ClickStack のアンインストール​

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

ログの確認​

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

デプロイメントの検証​

JSON 型サポート​

関連ドキュメント​

デプロイメントガイド​

追加リソース​