> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm の設定

> ClickStack の Helm デプロイメント向けに API キー、シークレット、イングレスを設定する

<Warning>
  **Chart version 2.x**

  このページでは、**v2.x** のサブチャートベースの Helm チャートについて説明します。現在も v1.x のインラインテンプレートチャートを使用している場合は、[Helm の設定 (v1.x)](/ja/clickstack/deployment/helm-configuration-v1) を参照してください。移行手順については、[アップグレードガイド](/ja/clickstack/deployment/helm-upgrade) を参照してください。
</Warning>

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

<div id="values-organization">
  ## Values の構成
</div>

v2.x チャートでは、値は `hyperdx:` ブロック配下で Kubernetes のリソースタイプごとに整理されています:

```yaml theme={null}
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 はもうありません。両方のワークロードが同じソースを読み取ります。

<div id="api-key-setup">
  ## API キーの設定
</div>

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

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

<div id="api-key-values-file">
  ### 方法 1: values ファイルを使用して helm upgrade で更新する
</div>

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

```yaml theme={null}
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"
```

続いて、デプロイメントをアップグレードします:

```shell theme={null}
helm upgrade my-clickstack clickstack/clickstack -f values.yaml
```

<div id="api-key-set-flag">
  ### 方法 2: --set フラグを指定した helm upgrade による更新
</div>

```shell theme={null}
helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"
```

<div id="restart-pods">
  ### 変更を適用するため、ポッドを再起動する
</div>

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

```shell theme={null}
kubectl rollout restart deployment my-clickstack-clickstack-app
```

<Note>
  このチャートは、設定値を格納した Kubernetes Secret (`clickstack-secret`) を自動的に作成します。外部の Secret を使用する場合を除き、追加の Secret 設定は不要です。
</Note>

<div id="secret-management">
  ## シークレット管理
</div>

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

<div id="default-secret-values">
  ### シークレットのデフォルト値
</div>

このチャートには、すべてのシークレットにデフォルト値が用意されています。`values.yaml` で上書きしてください。

```yaml theme={null}
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"
```

<div id="using-external-secret">
  ### 外部シークレットを使用する
</div>

本番環境へのデプロイで、認証情報を Helm の値とは分けて管理したい場合は、外部の Kubernetes Secret を使用します。

```bash theme={null}
# 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で参照します：

```yaml theme={null}
hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"
```

<div id="ingress-setup">
  ## イングレスの設定
</div>

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

<div id="general-ingress-configuration">
  ### イングレスの一般設定
</div>

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

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
```

<Info>
  **重要な設定上の注意**

  `hyperdx.frontendUrl` はイングレスのホスト名と一致し、プロトコル (例: `https://hyperdx.yourdomain.com`) を含める必要があります。これにより、生成されるリンク、Cookie、リダイレクトがすべて正しく機能します。
</Info>

<div id="enabling-tls">
  ### TLS (HTTPS) の有効化
</div>

デプロイメントをHTTPSで保護するには、次の手順を実行します。

**1. 証明書と秘密鍵を含むTLSシークレットを作成します。**

```shell theme={null}
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
```

**2. イングレス設定でTLSを有効にします:**

```yaml theme={null}
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"
```

<div id="example-ingress-configuration">
  ### イングレス設定の例
</div>

参考までに、生成されるイングレスリソースは以下のようになります。

```yaml theme={null}
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
```

<div id="common-ingress-pitfalls">
  ### よくあるイングレスの落とし穴
</div>

**パスとリライトの設定:**

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

**`frontendUrl` と `ingress.host` の不一致:**

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

**TLS の設定ミス:**

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

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

* 一部の機能 (正規表現パスやリライトなど) を使うには、比較的新しいバージョンの nginx ingress controller が必要です
* 次のコマンドでバージョンを確認してください:

```shell theme={null}
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"
```

<div id="otel-collector-ingress">
  ## OTel collector イングレス
</div>

イングレス経由で OTel collector のエンドポイント (トレース、メトリクス、ログ) を公開する必要がある場合は、`additionalIngresses` 設定を使用します。これは、クラスター外からテレメトリーデータを送信する場合や、collector にカスタムドメインを使用する場合に便利です。

```yaml theme={null}
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 つのルールでルーティングできます

<Note>
  OTel collector を外部公開する必要がなければ、この設定は省略できます。ほとんどの場合、一般的なイングレス設定で十分です。
</Note>

または、[`additionalManifests`](/ja/clickstack/deployment/helm-additional-manifests) を使って、AWS ALB Ingress などの完全にカスタムなイングレスリソースを定義することもできます。

<div id="otel-collector-configuration">
  ## OTel collector の設定
</div>

OTel collector は、公式の OpenTelemetry Collector Helm チャートの `otel-collector:` サブチャートとしてデプロイされます。values では、`otel-collector:` の直下で直接設定してください。

```yaml theme={null}
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 チャート](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector)を参照してください。

<div id="mongodb-configuration">
  ## MongoDB の設定
</div>

MongoDB は、`MongoDBCommunity` カスタムリソースを通じて MCK operator によって管理されます。CR スペックは `mongodb.spec` の内容がそのまま反映されます：

```yaml theme={null}
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 ドキュメント](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity) を参照してください。

<div id="clickhouse-configuration">
  ## ClickHouse の設定
</div>

ClickHouse は、`ClickHouseCluster` および `KeeperCluster` のカスタムリソースを通じて、ClickHouse Operator によって管理されます。両方の CR スペックは、values からそのままレンダリングされます。

```yaml theme={null}
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 構成ガイド](/ja/products/kubernetes-operator/guides/configuration) を参照してください。

<div id="troubleshooting-ingress">
  ## イングレスのトラブルシューティング
</div>

**イングレスリソースを確認する:**

```shell theme={null}
kubectl get ingress -A
kubectl describe ingress <ingress-name>
```

**イングレスコントローラーのログを確認します。**

```shell theme={null}
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
```

**アセット URL のテスト:**

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

```shell theme={null}
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 をクリアします

<div id="customizing-values">
  ## 値のカスタマイズ
</div>

`--set` フラグを使用して設定をカスタマイズできます：

```shell theme={null}
helm install my-clickstack clickstack/clickstack --set key=value
```

または、独自の `values.yaml` を作成します。デフォルト値を取得するには、次のようにします。

```shell theme={null}
helm show values clickstack/clickstack > values.yaml
```

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

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values.yaml
```

<div id="next-steps">
  ## 次のステップ
</div>

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