Helm configuration

- Ensure your TLS secret is valid and referenced correctly in the ingress
- Browsers may block insecure content if you access the app over HTTP when TLS is enabled

**Ingress controller version:**

- Some features (like regex paths and rewrites) require recent versions of nginx ingress controller
- Check your version with:

```
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"
```

## OTEL collector ingress[​](#otel-collector-ingress "Direct link to OTEL collector ingress")

If you need to expose your OTEL collector endpoints (for traces, metrics, logs) through ingress, use the `additionalIngresses` configuration. This is useful for sending telemetry data from outside the cluster or using a custom domain for the collector.

```
hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls
```

- This creates a separate ingress resource for the OTEL collector endpoints
- You can use a different domain, configure specific TLS settings, and apply custom annotations
- The regex path rule allows you to route all OTLP signals (traces, metrics, logs) through a single rule

Note

If you don't need to expose the OTEL collector externally, you can skip this configuration. For most users, the general ingress setup is sufficient.

Alternatively, you can use [`additionalManifests`](/docs/use-cases/observability/clickstack/deployment/helm-additional-manifests) to define fully custom ingress resources, such as an AWS ALB Ingress.

## OTEL collector configuration[​](#otel-collector-configuration "Direct link to OTEL collector configuration")

The OTEL Collector is deployed via the official OpenTelemetry Collector Helm chart as the `otel-collector:` subchart. Configure it directly under `otel-collector:` in your values:

```
otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
```

Environment variables (ClickHouse endpoint, OpAMP URL, etc.) are shared via the unified `clickstack-config` ConfigMap and `clickstack-secret` Secret. The subchart's `extraEnvsFrom` is pre-wired to read from both.

See the [OpenTelemetry Collector Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector) for all available subchart values.

## MongoDB configuration[​](#mongodb-configuration "Direct link to MongoDB configuration")

MongoDB is managed by the MCK operator via a `MongoDBCommunity` custom resource. The CR spec is rendered verbatim from `mongodb.spec`:

```
mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
```

The MongoDB password is set in `hyperdx.secrets.MONGODB_PASSWORD`. See the [MCK documentation](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity) for all available CRD fields.

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

ClickHouse is managed by the ClickHouse Operator via `ClickHouseCluster` and `KeeperCluster` custom resources. Both CR specs are rendered verbatim from values:

```
clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
```

ClickHouse user credentials are sourced from `hyperdx.secrets` (not `clickhouse.config.users` as in v1.x). See the [ClickHouse Operator configuration guide](https://clickhouse.com/docs/clickhouse-operator/guides/configuration) for all available CRD fields.

## Troubleshooting ingress[​](#troubleshooting-ingress "Direct link to Troubleshooting ingress")

**Check ingress resource:**

```
kubectl get ingress -A
kubectl describe ingress <ingress-name>
```

**Check ingress controller logs:**

```
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
```

**Test asset URLs:**

Use `curl` to verify static assets are served as JS, not HTML:

```
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Should return Content-Type: application/javascript
```

**Browser DevTools:**

- Check the Network tab for 404s or assets returning HTML instead of JS
- Look for errors like `Unexpected token <` in the console (indicates HTML returned for JS)

**Check for path rewrites:**

- Ensure the ingress isn't stripping or incorrectly rewriting asset paths

**Clear browser and CDN cache:**

- After changes, clear your browser cache and any CDN/proxy cache to avoid stale assets

## Customizing values[​](#customizing-values "Direct link to Customizing values")

You can customize settings by using `--set` flags:

```
helm install my-clickstack clickstack/clickstack --set key=value
```

Alternatively, create a custom `values.yaml`. To retrieve the default values:

```
helm show values clickstack/clickstack > values.yaml
```

Apply your custom values:

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

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

- [Deployment options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External systems and minimal deployments
- [Cloud deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, and AKS 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
- [Configuration (v1.x)](/docs/use-cases/observability/clickstack/deployment/helm-configuration-v1) - v1.x configuration guide