メインコンテンツへスキップ
Chart version 2.xこのページでは、v2.x のサブチャートベースの Helm チャートについて説明します。現在も v1.x のインラインテンプレートチャートを使用している場合は、Helm の設定 (v1.x) を参照してください。移行手順については、アップグレードガイド を参照してください。
このガイドでは、ClickStack の Helm デプロイメントで使用できる設定オプションを説明します。基本的なインストールについては、Helm デプロイメントのメインガイド を参照してください。

​
Values の構成

v2.x チャートでは、値は hyperdx: ブロック配下で Kubernetes のリソースタイプごとに整理されています: 
hyperdx:
  ports:          # 共有ポート番号（デプロイメント、Service、ConfigMap、イングレス）
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"

  config:         # → clickstack-config ConfigMap（非機密環境変数）
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret（機密環境変数）
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s デプロイメント仕様（イメージ、レプリカ、プローブ等）
  service:        # K8s Service仕様（タイプ、annotations）
  ingress:        # K8s イングレス仕様（ホスト、TLS、annotations）
  podDisruptionBudget:  # K8s PDB仕様
  tasks:          # K8s CronJob仕様
すべての環境変数は、envFrom を介して HyperDX デプロイメント および OTel collector で共有される、2 つの固定名リソースを通して渡されます。
  • clickstack-config ConfigMap — hyperdx.config から生成されます
  • clickstack-secret Secret — hyperdx.secrets から生成されます
OTel 専用の ConfigMap はもうありません。両方のワークロードが同じソースを読み取ります。

​
API キーの設定

ClickStack のデプロイが正常に完了したら、テレメトリーデータの収集を有効にするため、API キーを設定します。
  1. 設定済みのイングレスまたはサービスのエンドポイントから HyperDX インスタンスにアクセス します
  2. HyperDX ダッシュボードにログインし、Team settings に移動して API キーを生成または取得します
  3. 次のいずれかの方法で、API キーを使用して デプロイメントを更新 します:

​
方法 1: values ファイルを使用して helm upgrade で更新する

values.yaml に API キーを追加します: 
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"
続いて、デプロイメントをアップグレードします: 
helm upgrade my-clickstack clickstack/clickstack -f values.yaml

​
方法 2: —set フラグを指定した helm upgrade による更新

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

​
変更を適用するため、ポッドを再起動する

API キーを更新したら、新しい設定を反映するためにポッドを再起動します。 
kubectl rollout restart deployment my-clickstack-clickstack-app
このチャートは、設定値を格納した Kubernetes Secret (clickstack-secret) を自動的に作成します。外部の Secret を使用する場合を除き、追加の Secret 設定は不要です。

​
シークレット管理

API キーやデータベース認証情報などの機密データを扱うため、v2.x チャートでは hyperdx.secrets から生成される統一的な clickstack-secret リソースが提供されています。

​
シークレットのデフォルト値

このチャートには、すべてのシークレットにデフォルト値が用意されています。values.yaml で上書きしてください。 
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-otel-password"
    CLICKHOUSE_APP_PASSWORD: "your-clickhouse-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

​
外部シークレットを使用する

本番環境へのデプロイで、認証情報を Helm の値とは分けて管理したい場合は、外部の Kubernetes Secret を使用します。 
# Secretを作成する
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password
次に、それをvaluesで参照します： 
hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

​
イングレスの設定

ドメイン名経由で HyperDX UI と API を公開するには、values.yaml でイングレスを有効にします。

​
イングレスの一般設定

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # イングレスホストと一致させる必要があります

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
重要な設定上の注意hyperdx.frontendUrl はイングレスのホスト名と一致し、プロトコル (例: https://hyperdx.yourdomain.com) を含める必要があります。これにより、生成されるリンク、Cookie、リダイレクトがすべて正しく機能します。

​
TLS (HTTPS) の有効化

デプロイメントをHTTPSで保護するには、次の手順を実行します。 1. 証明書と秘密鍵を含むTLSシークレットを作成します。 
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
2. イングレス設定でTLSを有効にします: 
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

​
イングレス設定の例

参考までに、生成されるイングレスリソースは以下のようになります。 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

​
よくあるイングレスの落とし穴

パスとリライトの設定:
  • Next.js やその他の SPA では、必ず上記のように正規表現パスとリライト用のアノテーションを使用してください
  • リライトなしで path: / だけを使用すると、静的アセットを正しく配信できなくなります
frontendUrl と ingress.host の不一致:
  • これらが一致していないと、Cookie、リダイレクト、アセットの読み込みに問題が発生することがあります
TLS の設定ミス:
  • TLS シークレットが有効であり、イングレスで正しく参照されていることを確認してください
  • TLS が有効な状態で HTTP 経由でアプリにアクセスすると、ブラウザが安全でないコンテンツをブロックすることがあります
イングレスコントローラーのバージョン:
  • 一部の機能 (正規表現パスやリライトなど) を使うには、比較的新しいバージョンの nginx ingress controller が必要です
  • 次のコマンドでバージョンを確認してください:
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

​
OTel collector イングレス

イングレス経由で OTel collector のエンドポイント (トレース、メトリクス、ログ) を公開する必要がある場合は、additionalIngresses 設定を使用します。これは、クラスター外からテレメトリーデータを送信する場合や、collector にカスタムドメインを使用する場合に便利です。 
hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls
  • これにより、OTel collector のエンドポイント用に個別のイングレスリソースが作成されます
  • 別のドメインを使用したり、TLS の詳細設定を行ったり、カスタムアノテーションを適用したりできます
  • 正規表現のパスルールを使うことで、すべての OTLP シグナル (トレース、メトリクス、ログ) を 1 つのルールでルーティングできます
OTel collector を外部公開する必要がなければ、この設定は省略できます。ほとんどの場合、一般的なイングレス設定で十分です。
または、additionalManifests を使って、AWS ALB Ingress などの完全にカスタムなイングレスリソースを定義することもできます。

​
OTel collector の設定

OTel collector は、公式の OpenTelemetry Collector Helm チャートの otel-collector: サブチャートとしてデプロイされます。values では、otel-collector: の直下で直接設定してください。 
otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
環境変数 (ClickHouse エンドポイント、OpAMP URL など) は、共通の clickstack-config ConfigMap と clickstack-secret Secret を介して共有されます。サブチャートの extraEnvsFrom は、あらかじめその両方を参照するようになっています。 利用可能なすべてのサブチャート値については、OpenTelemetry Collector Helm チャートを参照してください。

​
MongoDB の設定

MongoDB は、MongoDBCommunity カスタムリソースを通じて MCK operator によって管理されます。CR スペックは mongodb.spec の内容がそのまま反映されます： 
mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
MongoDB のパスワードは hyperdx.secrets.MONGODB_PASSWORD で設定します。使用可能なすべての CRD フィールドについては、MCK ドキュメント を参照してください。

​
ClickHouse の設定

ClickHouse は、ClickHouseCluster および KeeperCluster のカスタムリソースを通じて、ClickHouse Operator によって管理されます。両方の CR スペックは、values からそのままレンダリングされます。 
clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
ClickHouse ユーザーの認証情報は hyperdx.secrets から取得されます (v1.x のように clickhouse.config.users から取得されるわけではありません) 。利用可能なすべての CRD フィールドについては、ClickHouse Operator 構成ガイド を参照してください。

​
イングレスのトラブルシューティング

イングレスリソースを確認する: 
kubectl get ingress -A
kubectl describe ingress <ingress-name>
イングレスコントローラーのログを確認します。 
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
アセット URL のテスト: curl を使って、静的アセットが HTML ではなく JS として配信されていることを確認します。 
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Content-Type: application/javascript が返されるはずです
ブラウザの DevTools:
  • 404 や、JS ではなく HTML を返しているアセットがないか、ネットワーク タブで確認します
  • コンソールで Unexpected token < のような error を探します (JS の代わりに HTML が返されていることを示します)
パスの書き換えを確認します:
  • イングレスがアセットのパスを取り除いたり、誤って書き換えたりしていないことを確認します
ブラウザと CDN の cache をクリアします:
  • 変更後は、古いアセットが使われないように、ブラウザの cache と CDN/プロキシ cache をクリアします

​
値のカスタマイズ

--set フラグを使用して設定をカスタマイズできます： 
helm install my-clickstack clickstack/clickstack --set key=value
または、独自の values.yaml を作成します。デフォルト値を取得するには、次のようにします。 
helm show values clickstack/clickstack > values.yaml
カスタム値を適用します: 
helm install my-clickstack clickstack/clickstack -f values.yaml

​
次のステップ

最終更新日 2026年6月10日