Helm

Chart Migration

If you are currently using the hdx-oss-v2 chart, please migrate to the clickstack chart. The hdx-oss-v2 chart is in maintenance mode and will no longer receive new features. All new development is focused on the clickstack chart, which provides the same functionality with improved naming and better organization.

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 ClickStack Helm repository

Add the ClickStack Helm repository:

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

Installing ClickStack

To install the ClickStack chart with default values:

helm install my-clickstack clickstack/clickstack

Verify the installation

Verify the installation:

kubectl get pods -l "app.kubernetes.io/name=clickstack"

When all pods are ready, proceed.

Forward ports

Port forwarding allows us to access and set up HyperDX. Users deploying to production should instead expose the service via an ingress or load balancer to ensure proper network access, TLS termination, and scalability. Port forwarding is best suited for local development or one-off administrative tasks, not long-term or high-availability environments.

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

Production Ingress Setup

For production deployments, configure ingress with TLS instead of port forwarding. See the Ingress Configuration guide for detailed setup instructions.

Navigate to the UI

Visit http://localhost:8080 to access the HyperDX UI.

Create a user, providing a username and password which meets the requirements.

On clicking Create, data sources will be created for the ClickHouse instance deployed with the Helm chart.

Overriding default connection

You can override the default connection to the integrated ClickHouse instance. For details, see "Using ClickHouse Cloud".

For an example of using an alternative ClickHouse instance, see "Create a ClickHouse Cloud connection".

Customizing values (optional)

You can customize settings by using --set flags. For example:

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

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

helm show values clickstack/clickstack > values.yaml

Example config:

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-clickstack clickstack/clickstack -f values.yaml

Using secrets (optional)

For handling sensitive data such as API keys or database credentials, use Kubernetes secrets. The HyperDX Helm charts provide default secret files that you can modify and apply to your cluster.

Using pre-configured secrets

The Helm chart includes a default secret template located at charts/clickstack/templates/secrets.yaml. This file provides a base structure for managing secrets.

If you need to manually apply a secret, modify and apply the provided secrets.yaml template:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

Apply the secret to your cluster:

kubectl apply -f secrets.yaml

Creating a custom secret

If you prefer, you can create a custom Kubernetes secret manually:

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

Referencing a secret

To reference a secret in values.yaml:

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

API Key Management

For detailed API key setup instructions including multiple configuration methods and pod restart procedures, see the API Key Setup guide.

Using ClickHouse Cloud

If using ClickHouse Cloud users disable the ClickHouse instance deployed by the Helm chart and specify the Cloud credentials:

# 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 my-clickstack clickstack/clickstack \
  --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}

Alternatively, use a values.yaml file:

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-clickstack clickstack/clickstack -f values.yaml
# or if installed...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Advanced External Configurations

For production deployments with secret-based configuration, external OTEL collectors, or minimal setups, see the Deployment Options guide.

Production notes

By default, this chart also installs ClickHouse and the OTel collector. However, for production, it is recommended that you manage ClickHouse and the OTel collector separately.

To disable ClickHouse and the OTel collector, set the following values:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

Production Best Practices

For production deployments including high availability configuration, resource management, ingress/TLS setup, and cloud-specific configurations (GKE, EKS, AKS), see:

Configuration Guide - Ingress, TLS, and secrets management
Cloud Deployments - Cloud-specific settings and production checklist

Task configuration

By default, there is one task in the chart setup as a cronjob, responsible for checking whether alerts should fire. Here are its configuration options:

Parameter	Description	Default
`tasks.enabled`	Enable/Disable cron tasks in the cluster. By default, the HyperDX image will run cron tasks in the process. Change to true if you'd rather use a separate cron task in the cluster.	`false`
`tasks.checkAlerts.schedule`	Cron schedule for the check-alerts task	`/1 * * *`
`tasks.checkAlerts.resources`	Resource requests and limits for the check-alerts task	See `values.yaml`

Upgrading the chart

To upgrade to a newer version:

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

To check available chart versions:

helm search repo clickstack

Uninstalling ClickStack

To remove the deployment:

helm uninstall my-clickstack

This will remove all resources associated with the release, but persistent data (if any) may remain.

Troubleshooting

Checking logs

kubectl logs -l app.kubernetes.io/name=clickstack

Debugging a failed install

helm install my-clickstack clickstack/clickstack --debug --dry-run

Verifying deployment

kubectl get pods -l app.kubernetes.io/name=clickstack

Additional Troubleshooting Resources

For ingress-specific issues, TLS problems, or cloud deployment troubleshooting, see:

Ingress Troubleshooting - Asset serving, path rewrites, browser issues
Cloud Deployments - GKE OpAMP issues and cloud-specific problems

JSON type support

Beta feature. Learn more.

Beta Feature - not production ready

JSON type support in ClickStack is a beta feature. While the JSON type itself is production-ready in ClickHouse 25.3+, its integration within ClickStack is still under active development and may have limitations, change in the future, or contain bugs.

ClickStack has beta support for the JSON type from version 2.0.4.

For the benefits of this type see Benefits of the JSON type.

In order to enable support for the JSON type users must set the following environment variables:

OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - enables support in the OTel collector, ensuring schemas are created using the JSON type.
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - enables support in the HyperDX application, allowing JSON data to be queried.

Users can set these environment variables via either parameters or the values.yaml e.g.

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"

or via --set:

helm install my-clickstack clickstack/clickstack \
  --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"

Deployment guides

Deployment options - External ClickHouse, OTEL collector, and minimal deployments
Configuration guide - API keys, secrets, and ingress setup
Cloud deployments - GKE, EKS, AKS configurations and production best practices

Additional resources

ClickStack getting started guide - Introduction to ClickStack
ClickStack Helm charts repository - Chart source code and values reference
Kubernetes documentation - Kubernetes reference
Helm documentation - Helm reference

Suitable for​

Deployment steps​

Prerequisites​

Add the ClickStack Helm repository​

Installing ClickStack​

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 ClickStack​

Troubleshooting​

Checking logs​

Debugging a failed install​

Verifying deployment​

JSON type support​

Related Documentation​

Deployment guides​

Additional resources​