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

Helm（v1.x）

非推奨 — v1.x チャート

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

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

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

設定例:

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インスタンスを無効にし、Cloudの認証情報を指定します。

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
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
# or if installed...
# 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 のセットアップ、Cloud 固有の設定 (GKE、EKS、AKS) を含む本番環境へのデプロイについては、以下を参照してください。

タスク設定​

デフォルトでは、チャートの設定には CronJob として 1 つのタスクがあり、アラートを発報すべきかどうかを確認します。設定項目は次のとおりです。

ParameterDescriptionDefault
tasks.enabledクラスター内の cron タスクを有効または無効にします。デフォルトでは、HyperDX イメージがプロセス内で cron タスクを実行します。クラスター内で個別の cron タスクを使用する場合は、true に変更してください。false
tasks.checkAlerts.schedulecheck-alerts タスクの cron スケジュール*/1 * * * *
tasks.checkAlerts.resourcescheck-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 デプロイ時のトラブルシューティングについては、以下を参照してください。

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 で設定できます。例:

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"

v1.x デプロイ ガイド​

v2.x ドキュメント​

追加リソース​