Helm

The helm chart for HyperDX can be found here and is the recommended method for production deployments.

By default, the Helm chart provisions all core components, including:

ClickHouse
HyperDX
OpenTelemetry (OTel) collector
MongoDB (for persistent application state)

However, it can be easily customized to integrate with an existing ClickHouse deployment - for example, one hosted in ClickHouse Cloud.

The chart supports standard Kubernetes best practices, including:

Environment-specific configuration via values.yaml
Resource limits and pod-level scaling
TLS and ingress configuration
Secrets management and authentication setup

Suitable for

Proof of concepts
Production

Deployment steps

Prerequisites

Helm v3+
Kubernetes cluster (v1.20+ recommended)
kubectl configured to interact with your cluster

Add the HyperDX Helm repository

Add the HyperDX Helm repository:

helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo update

Installing HyperDX

To install the HyperDX chart with default values:

helm install my-hyperdx hyperdx/hdx-oss-v2

Verify the installation

Verify the installation:

kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2"

When all pods are ready, proceed.

Forward ports

ポートフォワーディングを使用することで、HyperDXにアクセスして設定することができます。プロダクションにデプロイするユーザーは、適切なネットワークアクセス、TLS終端、およびスケーラビリティを保証するために、代わりにサービスをイングレスまたはロードバランサーを介して公開するべきです。ポートフォワーディングは、ローカル開発や一時的な管理タスクには適していますが、長期的または高可用性の環境には最適ではありません。

kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}') \
  8080:3000

Navigate to the UI

http://localhost:8080を訪れて、HyperDXのUIにアクセスします。

ユーザーを作成し、要件を満たすユーザー名とパスワードを提供します。

Createをクリックすると、HelmチャートでデプロイされたClickHouseインスタンスに対してデータソースが作成されます。

デフォルト接続のオーバーライド

統合されたClickHouseインスタンスへのデフォルト接続をオーバーライドできます。詳細については、"Using ClickHouse Cloud"を参照してください。

代替のClickHouseインスタンスの使用例については、"Create a ClickHouse Cloud connection"を参照してください。

Customizing values (optional)

--setフラグを使用して設定をカスタマイズできます。たとえば：

helm install my-hyperdx hyperdx/hdx-oss-v2 --set key=value

Alternatively, edit the `values.yaml`. To retrieve the default values:

```shell
helm show values hyperdx/hdx-oss-v2 > 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-hyperdx hyperdx/hdx-oss-v2 -f values.yaml

Using secrets (optional)

APIキーやデータベース資格情報などの機密データを処理するために、Kubernetesシークレットを使用します。HyperDX Helmチャートは、デフォルトのシークレットファイルを提供しており、それを変更してクラスターに適用できます。

Using pre-configured secrets

Helmチャートには、charts/hdx-oss-v2/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

Creating a custom secret

好みで、カスタムのKubernetesシークレットを手動で作成できます：

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

Referencing a secret

values.yamlでシークレットを参照するには：

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

Using 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 myrelease hyperdx-helm --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-hyperdx hyperdx/hdx-oss-v2 -f values.yaml

# or if installed...

# helm upgrade my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml

Production notes

デフォルトでは、このチャートはClickHouseとOTelコレクタもインストールします。ただし、プロダクション環境では、ClickHouseとOTelコレクタを別々に管理することをお勧めします。

ClickHouseとOTelコレクタを無効にするには、次の値を設定します：

helm install myrelease hyperdx-helm --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false

Task configuration

デフォルトでは、チャートにはcronjobとして設定された1つのタスクがあります。これはアラートが発生すべきかどうかを確認します。その設定オプションは以下の通りです：

パラメーター	説明	デフォルト
`tasks.enabled`	クラスターでのcronタスクの有効/無効を設定します。デフォルトでは、HyperDXイメージはプロセス内でcronタスクを実行します。クラスター内の別のcronタスクを使用したい場合はtrueに変更します。	`false`
`tasks.checkAlerts.schedule`	check-alertsタスクのcronスケジュール	`/1 * * *`
`tasks.checkAlerts.resources`	check-alertsタスクのリソース要求と制限	`values.yaml`参照

Upgrading the chart

新しいバージョンにアップグレードするには：

helm upgrade my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml

利用可能なチャートバージョンを確認するには：

helm search repo hyperdx

Uninstalling HyperDX

デプロイメントを削除するには：

helm uninstall my-hyperdx

これにより、リリースに関連付けられたすべてのリソースが削除されますが、永続データ（ある場合）は残る可能性があります。

Troubleshooting

Checking logs

kubectl logs -l app.kubernetes.io/name=hdx-oss-v2

Debugging a failed install

helm install my-hyperdx hyperdx/hdx-oss-v2 --debug --dry-run

Verifying deployment

kubectl get pods -l app.kubernetes.io/name=hdx-oss-v2

JSONタイプサポート

Beta feature. Learn more.

ClickStackはバージョン 2.0.4 から JSONタイプに対するベータサポートを提供しています。

このタイプの利点については、JSONタイプの利点を参照してください。

JSONタイプのサポートを有効にするためには、ユーザーは以下の環境変数を設定する必要があります：

OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - OTelコレクターでのサポートを有効にし、JSONタイプを使用してスキーマが作成されることを保証します。
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - HyperDXアプリケーションでのサポートを有効にし、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 myrelease hyperdx-helm --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"

Suitable for​

Deployment steps​

Prerequisites​

Add the HyperDX Helm repository​

Installing HyperDX​

Verify the installation​

Forward ports​

Navigate to the UI​

Customizing values (optional)​

Using secrets (optional)​

Using pre-configured secrets​

Creating a custom secret​

Referencing a secret​

Using ClickHouse Cloud​

Production notes​

Task configuration​

Upgrading the chart​

Uninstalling HyperDX​

Troubleshooting​

Checking logs​

Debugging a failed install​

Verifying deployment​

JSONタイプサポート​