Helm 設定 (v1.x) | ClickHouse Docs

このガイドでは、ClickStack の Helm デプロイメントで使用できる設定オプションを説明します。基本的なインストールについては、メインの Helm デプロイメントガイドを参照してください。

API キーの設定

ClickStack のデプロイが完了したら、テレメトリーデータの収集を有効にするため、API キーを設定します。

設定済みのイングレスまたはサービスのエンドポイント から HyperDX インスタンスにアクセス します
HyperDX ダッシュボードにログイン し、Team Settings に移動して API キーを生成または取得します
以下のいずれかの方法で、API キーを使用してデプロイメントを更新 します:

方法1: valuesファイルを使って Helm upgrade で更新

values.yaml に API キーを追加します:

hyperdx:
  apiKey: "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.apiKey="your-api-key-here"

変更を反映するためにポッドを再起動する

APIキーを更新したら、新しい設定を反映させるためにポッドを再起動します：

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector

シークレット管理

APIキーやデータベース認証情報などの機密データを扱うには、Kubernetes Secret を使用します。

事前設定済みのシークレットを使用する

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 Secret の作成

カスタム Kubernetes Secret を手動で作成します。

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

values.yaml で Secret を参照する

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

イングレスの設定

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

一般的なイングレスの設定

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

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

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

パスと rewrite の設定:

Next.js やその他の SPA では、必ず上記のように正規表現のパスと rewrite アノテーションを使用してください
rewrite を設定せずに path: / だけを使うと、静的アセットを配信できなくなります

frontendUrl と ingress.host の不一致:

これらが一致していないと、Cookie、リダイレクト、アセットの読み込みで問題が発生することがあります

TLS の設定ミス:

TLS シークレットが有効で、イングレスから正しく参照されていることを確認してください
TLS が有効な状態で HTTP 経由でアプリにアクセスすると、ブラウザーが安全でないコンテンツをブロックすることがあります

イングレスコントローラーのバージョン:

一部の機能 (正規表現パスや rewrite など) には、新しめの 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 つのルールでルーティングできます

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

イングレスリソースを確認します:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

イングレスコントローラーのログを確認する:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

アセット URL のテスト:

curl を使って、静的アセットが HTML ではなく JavaScript として配信されていることを確認します。

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Content-Type: application/javascript が返されるはずです

ブラウザの DevTools:

404 や、JS ではなく HTML を返しているアセットがないか、ネットワーク タブで確認します
コンソールで Unexpected token < のようなエラーを確認します (JS の代わりに HTML が返されていることを示します)

パスの書き換えを確認する:

イングレスがアセットのパスを削除したり、誤って書き換えたりしていないことを確認します

ブラウザと CDN cache をクリアする:

変更後は、古いアセットが残らないように、ブラウザの cache と CDN/プロキシ cache をクリアします

values のカスタマイズ

--set フラグを使って設定をカスタマイズできます。

helm install my-clickstack clickstack/clickstack --set key=value

または、カスタムの values.yaml を作成します。デフォルトのvaluesを取得するには:

helm show values clickstack/clickstack > values.yaml

設定例:

replicaCount: 2

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

カスタム values を適用します:

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

次のステップ

デプロイオプション (v1.x) - 外部システムと最小構成のデプロイメント
Cloud デプロイメント (v1.x) - GKE、EKS、AKS 向けの構成
Helm ガイド (v1.x) - 基本インストール
Helm 設定 (v2.x) - v2.x の設定ガイド
アップグレードガイド - v1.x から v2.x への移行