Helm (v1.x)

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](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1).

## Production notes[​](#production-notes "Direct link to 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](/docs/use-cases/observability/clickstack/deployment/helm-configuration-v1) - Ingress, TLS, and secrets management
- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud-v1) - 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. 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[​](#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 to v2.x

If you want to migrate to the v2.x subchart-based 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")

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[​](#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-v1#troubleshooting-ingress) - Asset serving, path rewrites, browser issues
- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud-v1#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 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"
```

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

### v1.x deployment guides[​](#deployment-guides "Direct link to v1.x deployment guides")

- [Deployment options (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1) - External ClickHouse, OTEL collector, and minimal deployments
- [Configuration guide (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-configuration-v1) - API keys, secrets, and ingress setup
- [Cloud deployments (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-cloud-v1) - GKE, EKS, AKS configurations and production best practices

### v2.x documentation[​](#v2x-documentation "Direct link to v2.x documentation")

- [Helm (v2.x)](/docs/use-cases/observability/clickstack/deployment/helm) - v2.x deployment guide
- [Upgrade guide](/docs/use-cases/observability/clickstack/deployment/helm-upgrade) - Migrating from v1.x to v2.x

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

- [ClickStack getting started guide](/docs/use-cases/observability/clickstack/getting-started) - Introduction to ClickStack
- [ClickStack Helm charts repository](https://github.com/ClickHouse/ClickStack-helm-charts) - Chart source code and values reference
- [Kubernetes documentation](https://kubernetes.io/docs/) - Kubernetes reference
- [Helm documentation](https://helm.sh/docs/) - Helm reference