Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm configuration (v1.x)

View as MarkdownEdit this pageReport an issueSet up docs MCP

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:

  1. Access your HyperDX instance via the configured ingress or service endpoint
  2. Log into the HyperDX dashboard and navigate to Team settings to generate or retrieve your API key
  3. 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

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"

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

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

Navigation