Skip to main content
Skip to main content
Edit this page

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:

Installing HyperDX​

To install the HyperDX chart with default values:

Verify the installation​

Verify the installation:

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.

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

Create a user, providing a username and password which means 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:

Example config:

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/hdx-oss-v2/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:

Apply the secret to your cluster:

Creating a custom secret​

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

Referencing a secret​

To reference a secret in values.yaml:

Using ClickHouse Cloud​

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

Alternatively, use a values.yaml file:

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:

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:

ParameterDescriptionDefault
tasks.enabledEnable/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.scheduleCron schedule for the check-alerts task*/1 * * * *
tasks.checkAlerts.resourcesResource requests and limits for the check-alerts taskSee values.yaml

Upgrading the chart​

To upgrade to a newer version:

To check available chart versions:

Uninstalling HyperDX​

To remove the deployment:

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

Troubleshooting​

Checking logs​

Debugging a failed install​

Verifying deployment​

JSON type support​

Beta feature. Learn more.

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

or via --set: