Helm (v1.x)

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

Deprecated — v1.x chart

This page documents the **v1.x** inline-template Helm chart, which is in maintenance mode and will no longer receive new features. For new deployments, use the [v2.x chart](/docs/use-cases/observability/clickstack/deployment/helm). To migrate an existing v1.x deployment, 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.

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[​](#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
```

Installing ClickStack

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

To install the ClickStack chart with default values:

```
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-v1#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:

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

### Using secrets (optional)[​](#using-secrets "Direct link to 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[​](#using-pre-configured-secrets "Direct link to Using pre-configured secrets")

The Helm chart includes a default secret template located at [`charts/clickstack/templates/secrets.yaml`](https://github.com/ClickHouse/ClickStack-helm-charts/blob/main/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[​](#creating-a-custom-secret "Direct link to 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[​](#referencing-a-secret "Direct link to 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](/docs/use-cases/observability/clickstack/deployment/helm-configuration-v1#api-key-setup).

## Using ClickHouse Cloud[​](#using-clickhouse-cloud "Direct link to 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](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1).