> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm deployment options (v1.x)

> Advanced deployment configurations for the v1.x ClickStack Helm chart

<Warning>
  **Deprecated — v1.x chart**

  This page documents deployment options for the **v1.x** inline-template Helm chart, which is in maintenance mode. For the v2.x chart, see [Helm deployment options](/clickstack/deployment/helm-deployment-options). To migrate, see the [Upgrade guide](/clickstack/deployment/helm-upgrade).
</Warning>

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

<h2 id="overview">
  Overview
</h2>

ClickStack's Helm chart supports multiple deployment configurations:

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

<h2 id="external-clickhouse">
  External ClickHouse
</h2>

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

<h3 id="external-clickhouse-inline">
  Option 1: Inline configuration (development/testing)
</h3>

Use this approach for quick testing or non-production environments:

```yaml theme={null}
# values-external-clickhouse.yaml
clickhouse:
  enabled: false  # Disable the built-in ClickHouse

otel:
  clickhouseEndpoint: "tcp://your-clickhouse-server:9000"
  clickhousePrometheusEndpoint: "http://your-clickhouse-server:9363"  # Optional

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

Install with this configuration:

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values-external-clickhouse.yaml
```

<h3 id="external-clickhouse-secret">
  Option 2: External secret (production recommended)
</h3>

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

<h4 id="create-configuration">
  Create your configuration files
</h4>

```bash theme={null}
# Create connections.json
cat <<EOF > connections.json
[
  {
    "name": "Production ClickHouse",
    "host": "https://your-production-clickhouse.com",
    "port": 8123,
    "username": "hyperdx_user",
    "password": "your-secure-password"
  }
]
EOF

# Create sources.json
cat <<EOF > sources.json
[
  {
    "from": {
      "databaseName": "default",
      "tableName": "otel_logs"
    },
    "kind": "log",
    "name": "Logs",
    "connection": "Production ClickHouse",
    "timestampValueExpression": "TimestampTime",
    "displayedTimestampValueExpression": "Timestamp",
    "implicitColumnExpression": "Body",
    "serviceNameExpression": "ServiceName",
    "bodyExpression": "Body",
    "eventAttributesExpression": "LogAttributes",
    "resourceAttributesExpression": "ResourceAttributes",
    "severityTextExpression": "SeverityText",
    "traceIdExpression": "TraceId",
    "spanIdExpression": "SpanId"
  },
  {
    "from": {
      "databaseName": "default",
      "tableName": "otel_traces"
    },
    "kind": "trace",
    "name": "Traces",
    "connection": "Production ClickHouse",
    "timestampValueExpression": "Timestamp",
    "displayedTimestampValueExpression": "Timestamp",
    "implicitColumnExpression": "SpanName",
    "serviceNameExpression": "ServiceName",
    "traceIdExpression": "TraceId",
    "spanIdExpression": "SpanId",
    "durationExpression": "Duration"
  }
]
EOF
```

<h4 id="create-kubernetes-secret">
  Create the Kubernetes secret
</h4>

```bash theme={null}
kubectl create secret generic hyperdx-external-config \
  --from-file=connections.json=connections.json \
  --from-file=sources.json=sources.json

# Clean up local files
rm connections.json sources.json
```

<h4 id="configure-helm-secret">
  Configure Helm to use the secret
</h4>

```yaml theme={null}
# values-external-clickhouse-secret.yaml
clickhouse:
  enabled: false

otel:
  clickhouseEndpoint: "tcp://your-clickhouse-server:9000"
  clickhousePrometheusEndpoint: "http://your-clickhouse-server:9363"

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

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values-external-clickhouse-secret.yaml
```

<h3 id="using-clickhouse-cloud">
  Using ClickHouse Cloud
</h3>

For ClickHouse Cloud specifically:

```yaml theme={null}
# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false
  persistence:
    enabled: false

otel:
  clickhouseEndpoint: "tcp://your-cloud-instance.clickhouse.cloud:9440?secure=true"

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"
```

<h2 id="external-otel-collector">
  External OTEL Collector
</h2>

If you have an existing OTEL collector infrastructure:

```yaml theme={null}
# values-external-otel.yaml
otel:
  enabled: false  # Disable the built-in OTEL collector

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

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values-external-otel.yaml
```

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

<h2 id="minimal-deployment">
  Minimal deployment
</h2>

For organizations with existing infrastructure, deploy only HyperDX:

```yaml theme={null}
# values-minimal.yaml
clickhouse:
  enabled: false

otel:
  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"
```

```shell theme={null}
helm install my-clickstack clickstack/clickstack -f values-minimal.yaml
```

<h2 id="next-steps">
  Next steps
</h2>

* [Configuration Guide (v1.x)](/clickstack/deployment/helm-configuration-v1) - API keys, secrets, and ingress setup
* [Cloud Deployments (v1.x)](/clickstack/deployment/helm-cloud-v1) - GKE, EKS, and AKS specific configurations
* [Main Helm Guide (v1.x)](/clickstack/deployment/helm-v1) - Basic installation
* [Deployment options (v2.x)](/clickstack/deployment/helm-deployment-options) - v2.x deployment options
* [Upgrade guide](/clickstack/deployment/helm-upgrade) - Migrating from v1.x to v2.x