Helm

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/deployment/oss/helm/v2/helm.md)

Chart version 2.x

This page documents the **v2.x** subchart-based Helm chart. If you are still using the v1.x inline-template chart, see the [v1.x Helm guide](/docs/use-cases/observability/clickstack/deployment/helm-v1). For migration steps, see the [Upgrade guide](/docs/use-cases/observability/clickstack/deployment/helm-upgrade).

The Helm chart for ClickStack can be found [here](https://github.com/ClickHouse/ClickStack-helm-charts) and is the **recommended** method for production deployments.

The v2.x chart uses a **two-phase installation**. Operators and CRDs are installed first via the `clickstack-operators` chart, followed by the main `clickstack` chart which creates operator-managed custom resources for ClickHouse, MongoDB, and the OpenTelemetry Collector.

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

- **ClickHouse** — managed by the [ClickHouse Operator](https://clickhouse.com/docs/clickhouse-operator/overview) via `ClickHouseCluster` and `KeeperCluster` custom resources
- **HyperDX** — the observability UI and API
- **OpenTelemetry (OTel) collector** — deployed via the [official OpenTelemetry Collector Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts) as a subchart
- **MongoDB** — managed by the [MongoDB Kubernetes Operator (MCK)](https://github.com/mongodb/mongodb-kubernetes) via a `MongoDBCommunity` custom resource

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
- [Additional manifests](/docs/use-cases/observability/clickstack/deployment/helm-additional-manifests) for deploying arbitrary Kubernetes objects (NetworkPolicy, HPA, ALB Ingress, etc.) alongside the chart

### Suitable for[​](#suitable-for "Direct link to Suitable for")

- Proof of concepts
- Production

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

  

Prerequisites

### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- [Helm](https://helm.sh/) v3+
- Kubernetes cluster (v1.20+ recommended)
- `kubectl` configured to interact with your cluster

Add the ClickStack Helm repository

### Add the ClickStack Helm repository[​](#add-the-clickstack-helm-repository "Direct link to Add the ClickStack Helm repository")

Add the ClickStack Helm repository:

```
helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update
```

Install the operators

### Install the operators[​](#install-the-operators "Direct link to Install the operators")

Install the operator chart first. This registers the CRDs required by the main chart:

```
helm install clickstack-operators clickstack/clickstack-operators
```

Wait for the operator pods to become ready before proceeding:

```
kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
```

Install ClickStack

### Install ClickStack[​](#installing-clickstack "Direct link to Install ClickStack")

Once the operators are running, install the main chart:

```
helm install my-clickstack clickstack/clickstack
```

Verify the installation

### Verify the installation[​](#verify-the-installation "Direct link to Verify the installation")

Verify the installation:

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

When all pods are ready, proceed.

Forward ports

### Forward ports[​](#forward-ports "Direct link to 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](/docs/use-cases/observability/clickstack/deployment/helm-configuration#ingress-setup) for detailed setup instructions.

Navigate to the UI

### Navigate to the UI[​](#navigate-to-the-ui "Direct link to 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"](#using-clickhouse-cloud).

Customizing values (optional)

### Customizing values (optional)[​](#customizing-values "Direct link to 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:

```
hyperdx:
  frontendUrl: "https://hyperdx.example.com"

  deployment:
    replicas: 2
    resources:
      limits:
        cpu: "2"
        memory: 4Gi
      requests:
        cpu: 500m
        memory: 1Gi

  ingress:
    enabled: true
    host: hyperdx.example.com
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"
```

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

Using secrets (optional)

### Using secrets (optional)[​](#using-secrets "Direct link to Using secrets (optional)")

The v2.x chart uses a unified secret (`clickstack-secret`) populated from `hyperdx.secrets` in your values. All sensitive environment variables — including ClickHouse passwords, MongoDB passwords, and the HyperDX API key — flow through this single secret.

To override secret values:

```
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-password"
    CLICKHOUSE_APP_PASSWORD: "your-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"
```

For external secret management (e.g. using a secrets operator), you can reference a pre-existing Kubernetes secret:

```
hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-external-secret"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"
```

API Key Management

For detailed API key setup instructions including multiple configuration methods and pod restart procedures, see the [API Key Setup guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration#api-key-setup).

## Using ClickHouse Cloud[​](#using-clickhouse-cloud "Direct link to Using ClickHouse Cloud")

If using ClickHouse Cloud, disable the built-in ClickHouse instance and provide your Cloud credentials:

```
# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

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
```