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

# Helm configuration (v1.x)

> Configuring API keys, secrets, and ingress for v1.x ClickStack Helm deployments

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

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

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

<h2 id="api-key-setup">
  API key setup
</h2>

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:

<h3 id="api-key-values-file">
  Method 1: Update via Helm upgrade with values file
</h3>

Add the API key to your `values.yaml`:

```yaml theme={null}
hyperdx:
  apiKey: "your-api-key-here"
```

Then upgrade your deployment:

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

<h3 id="api-key-set-flag">
  Method 2: Update via Helm upgrade with --set flag
</h3>

```shell theme={null}
helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"
```

<h3 id="restart-pods">
  Restart pods to apply changes
</h3>

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

```shell theme={null}
kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector
```

<Note>
  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.
</Note>

<h2 id="secret-management">
  Secret management
</h2>

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

<h3 id="using-pre-configured-secrets">
  Using pre-configured secrets
</h3>

The Helm chart includes a default secret template located at [`charts/clickstack/templates/secrets.yaml`](https://github.com/hyperdxio/helm-charts/blob/main/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:

```yaml theme={null}
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:

```shell theme={null}
kubectl apply -f secrets.yaml
```

<h3 id="creating-a-custom-secret">
  Creating a custom secret
</h3>

Create a custom Kubernetes secret manually:

```shell theme={null}
kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key
```

<h3 id="referencing-a-secret">
  Referencing a secret in values.yaml
</h3>

```yaml theme={null}
hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY
```

<h2 id="ingress-setup">
  Ingress setup
</h2>

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

<h3 id="general-ingress-configuration">
  General ingress configuration
</h3>

```yaml theme={null}
hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Must match ingress host
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
```

<Info>
  **Important configuration note**

  `hyperdx.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.
</Info>

<h3 id="enabling-tls">
  Enabling TLS (HTTPS)
</h3>

To secure your deployment with HTTPS:

**1. Create a TLS secret with your certificate and key:**

```shell theme={null}
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
```

**2. Enable TLS in your ingress configuration:**

```yaml theme={null}
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"
```

<h3 id="example-ingress-configuration">
  Example ingress configuration
</h3>

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

```yaml theme={null}
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
```

<h3 id="common-ingress-pitfalls">
  Common ingress pitfalls
</h3>

**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:

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

<h2 id="otel-collector-ingress">
  OTEL collector ingress
</h2>

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.

```yaml theme={null}
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.
</Note>

<h2 id="troubleshooting-ingress">
  Troubleshooting ingress
</h2>

**Check ingress resource:**

```shell theme={null}
kubectl get ingress -A
kubectl describe ingress <ingress-name>
```

**Check ingress controller logs:**

```shell theme={null}
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:

```shell theme={null}
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

<h2 id="customizing-values">
  Customizing values
</h2>

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

```shell theme={null}
helm install my-clickstack clickstack/clickstack --set key=value
```

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

```shell theme={null}
helm show values clickstack/clickstack > values.yaml
```

Example configuration:

```yaml theme={null}
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:

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

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

* [Deployment options (v1.x)](/clickstack/deployment/helm-deployment-options-v1) - External systems and minimal deployments
* [Cloud deployments (v1.x)](/clickstack/deployment/helm-cloud-v1) - GKE, EKS, and AKS configurations
* [Main Helm guide (v1.x)](/clickstack/deployment/helm-v1) - Basic installation
* [Helm configuration (v2.x)](/clickstack/deployment/helm-configuration) - v2.x configuration guide
* [Upgrade guide](/clickstack/deployment/helm-upgrade) - Migrating from v1.x to v2.x