Helm

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"
```

Create the connection secret separately:

```
cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json
```

```
helm install my-clickstack clickstack/clickstack -f values-clickhouse-cloud.yaml
```

Advanced External Configurations

For production deployments with secret-based configuration, external OTEL collectors, or minimal setups, see the [Deployment Options guide](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options).

## Production notes[​](#production-notes "Direct link to Production notes")

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

To disable ClickHouse and the OTel collector:

```
clickhouse:
  enabled: false

otel-collector:
  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](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - Ingress, TLS, and secrets management
- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - Cloud-specific settings and production checklist

## Task configuration[​](#task-configuration "Direct link to Task configuration")

By default, there is one task in the chart setup as a cronjob, responsible for checking whether alerts should fire. In v2.x, task configuration has moved under `hyperdx.tasks`:

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Description Default|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `hyperdx.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`| `hyperdx.tasks.checkAlerts.schedule` Cron schedule for the check-alerts task `*/1 * * * *`| `hyperdx.tasks.checkAlerts.resources` Resource requests and limits for the check-alerts task See `values.yaml` | | | | | | | | | | | |

## Upgrading the chart[​](#upgrading-the-chart "Direct link to 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
```

Upgrading from v1.x

If you are upgrading from the v1.x inline-template chart, see the [Upgrade guide](/docs/use-cases/observability/clickstack/deployment/helm-upgrade) for migration instructions. This is a breaking change — an in-place `helm upgrade` is not supported.

## Uninstalling ClickStack[​](#uninstalling-clickstack "Direct link to Uninstalling ClickStack")

Uninstall in reverse order:

```
helm uninstall my-clickstack            # Remove app + CRs first
helm uninstall clickstack-operators     # Remove operators + CRDs
```

**Note:** PersistentVolumeClaims created by the MongoDB and ClickHouse operators are **not** removed by `helm uninstall`. This is by design to prevent accidental data loss. To clean up PVCs, refer to:

- [MongoDB Kubernetes Operator docs](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity)
- [ClickHouse Operator cleanup docs](https://clickhouse.com/docs/clickhouse-operator/managing-clusters/cleanup)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Checking logs[​](#checking-logs "Direct link to Checking logs")

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

### Debugging a failed install[​](#debugging-a-failed-install "Direct link to Debugging a failed install")

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

### Verifying deployment[​](#verifying-deployment "Direct link to 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](/docs/use-cases/observability/clickstack/deployment/helm-configuration#troubleshooting-ingress) - Asset serving, path rewrites, browser issues
- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud#loadbalancer-dns-resolution-issue) - GKE OpAMP issues and cloud-specific problems

## JSON type support[​](#json-type-support "Direct link to JSON type support")

Beta feature. [Learn more.](/docs/beta-and-experimental-features#beta-features)

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](/docs/interfaces/formats/JSON) from version `2.0.4`.

For the benefits of this type see [Benefits of the JSON type](/docs/use-cases/observability/clickstack/ingesting-data/otel-collector#benefits-json-type).

In order to enable support for the JSON type you 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` (ClickStack Open Source only) - enables support in the ClickStack UI application, allowing JSON data to be queried.

You can set these environment variables via `hyperdx.config` in your `values.yaml`:

```
hyperdx:
  config:
    BETA_CH_OTEL_JSON_SCHEMA_ENABLED: "true"
    OTEL_AGENT_FEATURE_GATE_ARG: "--feature-gates=clickhouse.json"
```

or via `--set`:

```
helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.config.BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true" \
  --set "hyperdx.config.OTEL_AGENT_FEATURE_GATE_ARG=--feature-gates=clickhouse.json"
```

## Related documentation[​](#related-documentation "Direct link to Related documentation")

### Deployment guides[​](#deployment-guides "Direct link to Deployment guides")

- [Deployment options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External ClickHouse, OTEL collector, and minimal deployments
- [Configuration guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress setup
- [Cloud deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, AKS configurations and production best practices
- [Upgrade guide](/docs/use-cases/observability/clickstack/deployment/helm-upgrade) - Migrating from v1.x to v2.x
- [Additional manifests](/docs/use-cases/observability/clickstack/deployment/helm-additional-manifests) - Deploying custom Kubernetes objects alongside the chart

### v1.x documentation[​](#v1x-documentation "Direct link to v1.x documentation")

- [Helm (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-v1) - v1.x deployment guide
- [Configuration (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-configuration-v1) - v1.x configuration
- [Deployment options (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1) - v1.x deployment options
- [Cloud deployments (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-cloud-v1) - v1.x cloud configurations

### Additional resources[​](#additional-resources "Direct link to Additional resources")