Helm deployment options

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/deployment/oss/helm/v2/helm-deployment-options.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 [Helm deployment options (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1). For migration steps, see the [Upgrade guide](/docs/use-cases/observability/clickstack/deployment/helm-upgrade).

This guide covers advanced deployment options for ClickStack using Helm. For basic installation, see the [main Helm deployment guide](/docs/use-cases/observability/clickstack/deployment/helm).

## Overview[​](#overview "Direct link to Overview")

ClickStack's Helm chart supports multiple deployment configurations:

- **Full stack** (default) — All components included, managed by operators
- **External ClickHouse** — Use existing ClickHouse cluster
- **External OTEL Collector** — Use existing OTEL infrastructure
- **Minimal deployment** — Only HyperDX, external dependencies

## External ClickHouse[​](#external-clickhouse "Direct link to External ClickHouse")

If you have an existing ClickHouse cluster (including ClickHouse Cloud), you can disable the built-in ClickHouse and connect to your external instance.

### Option 1: Inline configuration (development/testing)[​](#external-clickhouse-inline "Direct link to Option 1: Inline configuration (development/testing)")

Use this approach for quick testing or non-production environments. Provide connection details via `hyperdx.config` and `hyperdx.secrets`:

```
# values-external-clickhouse.yaml
clickhouse:
  enabled: false  # Disable the operator-managed ClickHouse

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

  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]
```

Install with this configuration:

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

### Option 2: External secret (production recommended)[​](#external-clickhouse-secret "Direct link to Option 2: External secret (production recommended)")

For production deployments where you want to keep credentials separate from your Helm configuration:

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

For ClickHouse Cloud specifically:

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

## External OTEL Collector[​](#external-otel-collector "Direct link to External OTEL Collector")

If you have an existing OTEL collector infrastructure, disable the subchart:

```
# values-external-otel.yaml
otel-collector:
  enabled: false  # Disable the subchart OTEL collector

hyperdx:
  otelExporterEndpoint: "http://your-otel-collector:4318"
```

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

For instructions on exposing OTEL collector endpoints via ingress, see [Ingress Configuration](/docs/use-cases/observability/clickstack/deployment/helm-configuration#otel-collector-ingress).

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

For organizations with existing infrastructure, deploy only HyperDX:

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

otel-collector:
  enabled: false

hyperdx:
  otelExporterEndpoint: "http://your-otel-collector:4318"

  # Option 1: Inline (for testing)
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

  # Option 2: External secret (production)
  # useExistingConfigSecret: true
  # existingConfigSecret: "my-external-config"
  # existingConfigConnectionsKey: "connections.json"
  # existingConfigSourcesKey: "sources.json"
```

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

## Next Steps[​](#next-steps "Direct link to Next Steps")

- [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, and AKS specific configurations
- [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) - Custom Kubernetes objects
- [Main Helm Guide](/docs/use-cases/observability/clickstack/deployment/helm) - Basic installation
- [Deployment options (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options-v1) - v1.x deployment options

- [Overview](#overview)- [External ClickHouse](#external-clickhouse)
    - [Option 1: Inline configuration (development/testing)](#external-clickhouse-inline)- [Option 2: External secret (production recommended)](#external-clickhouse-secret)- [Using ClickHouse Cloud](#using-clickhouse-cloud)- [External OTEL Collector](#external-otel-collector)- [Minimal Deployment](#minimal-deployment)- [Next Steps](#next-steps)

Was this page helpful?