Helm の設定

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 キーを設定します。

設定済みのイングレスまたはサービスのエンドポイントから HyperDX インスタンスにアクセス します
HyperDX ダッシュボードにログインし、Team settings に移動して API キーを生成または取得します
次のいずれかの方法で、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

次のステップ

デプロイオプション - 外部システムと最小構成のデプロイ
Cloud デプロイメント - GKE、EKS、AKS の構成
アップグレードガイド - v1.x から v2.x への移行
追加マニフェスト - カスタム Kubernetes オブジェクト
Helm メインガイド - 基本インストール
設定 (v1.x) - v1.x の設定ガイド

Features

Guides

Values の構成

API キーの設定

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

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

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

シークレット管理

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

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

イングレスの設定

イングレスの一般設定

TLS (HTTPS) の有効化

イングレス設定の例

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

OTel collector イングレス

OTel collector の設定

MongoDB の設定

ClickHouse の設定

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

値のカスタマイズ

次のステップ

​Values の構成

​API キーの設定

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

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

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

​シークレット管理

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

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

​イングレスの設定

​イングレスの一般設定

​TLS (HTTPS) の有効化

​イングレス設定の例

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

​OTel collector イングレス

​OTel collector の設定

​MongoDB の設定

​ClickHouse の設定

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

​値のカスタマイズ

​次のステップ

Values の構成

API キーの設定

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

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

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

シークレット管理

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

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

イングレスの設定

イングレスの一般設定

TLS (HTTPS) の有効化

イングレス設定の例

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

OTel collector イングレス

OTel collector の設定

MongoDB の設定

ClickHouse の設定

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

値のカスタマイズ

次のステップ