Skip to main content
Skip to main content
Edit this page

Helm deployment options

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). For migration steps, see the Upgrade guide.

This guide covers advanced deployment options for ClickStack using Helm. For basic installation, see the main Helm deployment guide.

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​

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

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

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

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​

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.

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​