Helm configuration (v1.x)

Deprecated — v1.x chartThis page documents configuration for the v1.x inline-template Helm chart, which is in maintenance mode. For the v2.x chart, see Helm configuration. To migrate, see the Upgrade guide.

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

API key setup

After successfully deploying ClickStack, configure the API key to enable telemetry data collection:

Access your HyperDX instance via the configured ingress or service endpoint
Log into the HyperDX dashboard and navigate to Team settings to generate or retrieve your API key
Update your deployment with the API key using one of the following methods:

Method 1: Update via Helm upgrade with values file

Add the API key to your values.yaml:

hyperdx:
  apiKey: "your-api-key-here"

Then upgrade your deployment:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Method 2: Update via Helm upgrade with —set flag

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

Restart pods to apply changes

After updating the API key, restart the pods to pick up the new configuration:

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector

The chart automatically creates a Kubernetes secret (<release-name>-app-secrets) with your API key. No additional secret configuration is needed unless you want to use an external secret.

Secret management

For handling sensitive data such as API keys or database credentials, use Kubernetes secrets.

Using pre-configured secrets

The Helm chart includes a default secret template located at 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

Create a custom Kubernetes secret manually:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

Referencing a secret in values.yaml

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

Ingress setup

To expose the HyperDX UI and API via a domain name, enable ingress in your values.yaml.

General ingress configuration

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Must match ingress host
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Important configuration notehyperdx.frontendUrl should match the ingress host and include the protocol (e.g., https://hyperdx.yourdomain.com). This ensures that all generated links, cookies, and redirects work correctly.

Enabling TLS (HTTPS)

To secure your deployment with HTTPS: 1. Create a TLS secret with your certificate and key:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. Enable TLS in your ingress configuration:

hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

Example ingress configuration

For reference, here’s what the generated ingress resource looks like:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

Common ingress pitfalls

Path and rewrite configuration:

For Next.js and other SPAs, always use a regex path and rewrite annotation as shown above
Don’t use just path: / without a rewrite, as this will break static asset serving

Mismatched frontendUrl and ingress.host:

If these don’t match, you may experience issues with cookies, redirects, and asset loading

TLS misconfiguration:

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

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

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.

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

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

Example configuration:

replicaCount: 2

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

Apply your custom values:

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

Next steps

Deployment options (v1.x) - External systems and minimal deployments
Cloud deployments (v1.x) - GKE, EKS, and AKS configurations
Main Helm guide (v1.x) - Basic installation
Helm configuration (v2.x) - v2.x configuration guide
Upgrade guide - Migrating from v1.x to v2.x

Features

Guides

API key setup

Method 1: Update via Helm upgrade with values file

Method 2: Update via Helm upgrade with —set flag

Restart pods to apply changes

Secret management

Using pre-configured secrets

Creating a custom secret

Referencing a secret in values.yaml

Ingress setup

General ingress configuration

Enabling TLS (HTTPS)

Example ingress configuration

Common ingress pitfalls

OTEL collector ingress

Troubleshooting ingress

Customizing values

Next steps

​API key setup

​Method 1: Update via Helm upgrade with values file

​Method 2: Update via Helm upgrade with —set flag

​Restart pods to apply changes

​Secret management

​Using pre-configured secrets

​Creating a custom secret

​Referencing a secret in values.yaml

​Ingress setup

​General ingress configuration

​Enabling TLS (HTTPS)

​Example ingress configuration

​Common ingress pitfalls

​OTEL collector ingress

​Troubleshooting ingress

​Customizing values

​Next steps

API key setup

Method 1: Update via Helm upgrade with values file

Method 2: Update via Helm upgrade with —set flag

Restart pods to apply changes

Secret management

Using pre-configured secrets

Creating a custom secret

Referencing a secret in values.yaml

Ingress setup

General ingress configuration

Enabling TLS (HTTPS)

Example ingress configuration

Common ingress pitfalls

OTEL collector ingress

Troubleshooting ingress

Customizing values

Next steps