From 00f9b7175cf0b94a323f665bcfcbfbd362aa705a Mon Sep 17 00:00:00 2001 From: Dominic Tran Date: Fri, 21 Nov 2025 12:07:42 -0600 Subject: [PATCH 1/2] Adding additional helm docs from helm-chart --- .../clickstack/deployment/helm/helm-cloud.md | 168 ++++++++++ .../deployment/helm/helm-configuration.md | 290 ++++++++++++++++++ .../helm/helm-deployment-options.md | 229 ++++++++++++++ .../clickstack/deployment/{ => helm}/helm.md | 128 +++++--- 4 files changed, 764 insertions(+), 51 deletions(-) create mode 100644 docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md create mode 100644 docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md create mode 100644 docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md rename docs/use-cases/observability/clickstack/deployment/{ => helm}/helm.md (60%) diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md new file mode 100644 index 00000000000..749ac2bfdb4 --- /dev/null +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md @@ -0,0 +1,168 @@ +--- +slug: /use-cases/observability/clickstack/deployment/helm-cloud +title: 'Helm Cloud Deployments' +pagination_prev: null +pagination_next: null +sidebar_position: 5 +description: 'Cloud-specific configurations for deploying ClickStack on GKE, EKS, and AKS' +doc_type: 'guide' +keywords: ['ClickStack GKE', 'ClickStack EKS', 'ClickStack AKS', 'Kubernetes cloud deployment', 'production deployment'] +--- + +This guide covers cloud-specific configurations for deploying ClickStack on managed Kubernetes services. For basic installation, see the [main Helm deployment guide](/docs/use-cases/observability/clickstack/deployment/helm). + +## Google Kubernetes Engine (GKE) {#google-kubernetes-engine-gke} + +When deploying to GKE, you may need to override certain values due to cloud-specific networking behavior. + +### LoadBalancer DNS resolution issue {#loadbalancer-dns-resolution-issue} + +GKE's LoadBalancer service can cause internal DNS resolution issues where pod-to-pod communication resolves to external IPs instead of staying within the cluster network. This specifically affects the OTEL collector's connection to the OpAMP server. + +**Symptoms:** +- OTEL collector logs showing "connection refused" errors with cluster IP addresses +- OpAMP connection failures like: `dial tcp 34.118.227.30:4320: connect: connection refused` + +**Solution:** + +Use the fully qualified domain name (FQDN) for the OpAMP server URL: +```shell +helm install my-clickstack clickstack/clickstack \ + --set hyperdx.frontendUrl="http://your-external-ip-or-domain.com" \ + --set otel.opampServerUrl="http://my-clickstack-clickstack-app.default.svc.cluster.local:4320" +``` + +### Other GKE considerations {#other-gke-considerations} + +```yaml +# values-gke.yaml +hyperdx: + frontendUrl: "http://34.123.61.99" # Use your LoadBalancer external IP + +otel: + opampServerUrl: "http://my-clickstack-clickstack-app.default.svc.cluster.local:4320" + +# Adjust for GKE pod networking if needed +clickhouse: + config: + clusterCidrs: + - "10.8.0.0/16" # GKE commonly uses this range + - "10.0.0.0/8" # Fallback for other configurations +``` + +## Amazon EKS {#amazon-eks} + +For EKS deployments, consider these common configurations: +```yaml +# values-eks.yaml +hyperdx: + frontendUrl: "http://your-alb-domain.com" + +# EKS typically uses these pod CIDRs +clickhouse: + config: + clusterCidrs: + - "192.168.0.0/16" + - "10.0.0.0/8" + +# Enable ingress for production +hyperdx: + ingress: + enabled: true + host: "hyperdx.yourdomain.com" + tls: + enabled: true +``` + +## Azure AKS {#azure-aks} + +For AKS deployments: +```yaml +# values-aks.yaml +hyperdx: + frontendUrl: "http://your-azure-lb.com" + +# AKS pod networking +clickhouse: + config: + clusterCidrs: + - "10.244.0.0/16" # Common AKS pod CIDR + - "10.0.0.0/8" +``` + +## Production Cloud deployment checklist {#production-cloud-deployment-checklist} + +Before deploying ClickStack to production on any cloud provider: + +- [ ] Configure proper `frontendUrl` with your external domain/IP +- [ ] Set up ingress with TLS for HTTPS access +- [ ] Override `otel.opampServerUrl` with FQDN if experiencing connection issues (especially on GKE) +- [ ] Adjust `clickhouse.config.clusterCidrs` for your pod network CIDR +- [ ] Configure persistent storage for production workloads +- [ ] Set appropriate resource requests and limits +- [ ] Enable monitoring and alerting +- [ ] Configure backup and disaster recovery +- [ ] Implement proper secret management + +## Production best practices {#production-best-practices} + +### Resource management {#resource-management} + +```yaml +hyperdx: + resources: + requests: + cpu: 500m + memory: 1Gi + limits: + cpu: 2000m + memory: 4Gi +``` + +### High availability {#high-availability} + +```yaml +hyperdx: + replicaCount: 3 + + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app.kubernetes.io/name + operator: In + values: + - clickstack + topologyKey: kubernetes.io/hostname +``` + +### Persistent storage {#persistent-storage} + +Ensure persistent volumes are configured for data retention: +```yaml +clickhouse: + persistence: + enabled: true + size: 100Gi + storageClass: "fast-ssd" # Use cloud-specific storage class +``` + +**Cloud-specific storage classes:** +- **GKE**: `pd-ssd` or `pd-balanced` +- **EKS**: `gp3` or `io2` +- **AKS**: `managed-premium` or `managed-csi` + +### Browser compatibility notes {#browser-compatibility-notes} + +For HTTP-only deployments (development/testing), some browsers may show crypto API errors due to secure context requirements. For production deployments, always use HTTPS with proper TLS certificates through ingress configuration. + +See [Ingress configuration](/docs/use-cases/observability/clickstack/deployment/helm-configuration#ingress-setup) for TLS setup instructions. + +## Next steps {#next-steps} + +- [Configuration guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress +- [Deployment options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External systems configuration +- [Main Helm guide](/docs/use-cases/observability/clickstack/deployment/helm) - Basic installation diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md new file mode 100644 index 00000000000..ecb893ae968 --- /dev/null +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md @@ -0,0 +1,290 @@ +--- +slug: /use-cases/observability/clickstack/deployment/helm-configuration +title: 'Helm Configuration' +pagination_prev: null +pagination_next: null +sidebar_position: 4 +description: 'Configuring API keys, secrets, and ingress for ClickStack Helm deployments' +doc_type: 'guide' +keywords: ['ClickStack configuration', 'Helm secrets', 'API key setup', 'ingress configuration', 'TLS setup'] +--- + +This guide covers configuration options for ClickStack Helm deployments. For basic installation, see the [main Helm deployment guide](/docs/use-cases/observability/clickstack/deployment/helm). + +## API key setup {#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 {#api-key-values-file} + +Add the API key to your `values.yaml`: +```yaml +hyperdx: + apiKey: "your-api-key-here" +``` + +Then upgrade your deployment: +```shell +helm upgrade my-clickstack clickstack/clickstack -f values.yaml +``` + +### Method 2: Update via Helm upgrade with --set flag {#api-key-set-flag} +```shell +helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here" +``` + +### Restart pods to apply changes {#restart-pods} + +After updating the API key, restart the pods to pick up the new configuration: +```shell +kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector +``` + +:::note +The chart automatically creates a Kubernetes secret (`-app-secrets`) with your API key. No additional secret configuration is needed unless you want to use an external secret. +::: + +## Secret management {#secret-management} + +For handling sensitive data such as API keys or database credentials, use Kubernetes secrets. + +### Using pre-configured secrets {#using-pre-configured-secrets} + +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 +apiVersion: v1 +kind: Secret +metadata: + name: hyperdx-secret + annotations: + "helm.sh/resource-policy": keep +type: Opaque +data: + API_KEY: +``` + +Apply the secret to your cluster: +```shell +kubectl apply -f secrets.yaml +``` + +### Creating a custom secret {#creating-a-custom-secret} + +Create a custom Kubernetes secret manually: +```shell +kubectl create secret generic hyperdx-secret \ + --from-literal=API_KEY=my-secret-api-key +``` + +### Referencing a secret in values.yaml {#referencing-a-secret} +```yaml +hyperdx: + apiKey: + valueFrom: + secretKeyRef: + name: hyperdx-secret + key: API_KEY +``` + +## Ingress setup {#ingress-setup} + +To expose the HyperDX UI and API via a domain name, enable ingress in your `values.yaml`. + +### General ingress configuration {#general-ingress-configuration} +```yaml +hyperdx: + frontendUrl: "https://hyperdx.yourdomain.com" # Must match ingress host + ingress: + enabled: true + host: "hyperdx.yourdomain.com" +``` + +:::note 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. +::: + +### Enabling TLS (HTTPS) {#enabling-tls} + +To secure your deployment with HTTPS: + +**1. Create a TLS secret with your certificate and key:** +```shell +kubectl create secret tls hyperdx-tls \ + --cert=path/to/tls.crt \ + --key=path/to/tls.key +``` + +**2. Enable TLS in your ingress configuration:** +```yaml +hyperdx: + ingress: + enabled: true + host: "hyperdx.yourdomain.com" + tls: + enabled: true + tlsSecretName: "hyperdx-tls" +``` + +### Example ingress configuration {#example-ingress-configuration} + +For reference, here's what the generated ingress resource looks like: +```yaml +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 {#common-ingress-pitfalls} + +**Path and rewrite configuration:** +- For Next.js and other SPAs, always use a regex path and rewrite annotation as shown above +- Do not use just `path: /` without a rewrite, as this will break static asset serving + +**Mismatched `frontendUrl` and `ingress.host`:** +- If these do not 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 +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} + +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 +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 do not need to expose the OTEL collector externally, you can skip this configuration. For most users, the general ingress setup is sufficient. +::: + +## Troubleshooting ingress {#troubleshooting-ingress} + +**Check ingress resource:** +```shell +kubectl get ingress -A +kubectl describe ingress +``` + +**Check ingress controller logs:** +```shell +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 +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 is not 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} + +You can customize settings by using `--set` flags: +```shell +helm install my-clickstack clickstack/clickstack --set key=value +``` + +Alternatively, create a custom `values.yaml`. To retrieve the default values: +```shell +helm show values clickstack/clickstack > values.yaml +``` + +Example configuration: +```yaml +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 +helm install my-clickstack clickstack/clickstack -f values.yaml +``` + +## Next steps {#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 +- [Main Helm guide](/docs/use-cases/observability/clickstack/deployment/helm) - Basic installation diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md new file mode 100644 index 00000000000..a347591633e --- /dev/null +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md @@ -0,0 +1,229 @@ +--- +slug: /use-cases/observability/clickstack/deployment/helm-deployment-options +title: 'Helm Deployment Options' +pagination_prev: null +pagination_next: null +sidebar_position: 3 +description: 'Advanced deployment configurations for ClickStack with Helm' +doc_type: 'guide' +keywords: ['ClickStack deployment options', 'external ClickHouse', 'external OTEL', 'minimal deployment', 'Helm configuration'] +--- + +This guide covers advanced deployment options for ClickStack using Helm. For basic installation, see the [main Helm deployment guide](/docs/use-cases/observability/clickstack/deployment/helm). + +## Overview {#overview} + +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 + +## External ClickHouse {#external-clickhouse} + +If you have an existing ClickHouse cluster (including ClickHouse Cloud), you can disable the built-in ClickHouse and connect to your external instance. + +### Option 1: Inline configuration (development/testing) {#external-clickhouse-inline} + +Use this approach for quick testing or non-production environments: +```yaml +# 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 +helm install my-clickstack clickstack/clickstack -f values-external-clickhouse.yaml +``` + +### Option 2: External secret (production recommended) {#external-clickhouse-secret} + +For production deployments where you want to keep credentials separate from your Helm configuration: + + + +#### Create your configuration files {#create-configuration} +```bash +# Create connections.json +cat < 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 < 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 +``` + +#### Create the Kubernetes secret {#create-kubernetes-secret} +```bash +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 +``` + +#### Configure Helm to use the secret {#configure-helm-secret} +```yaml +# 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 +helm install my-clickstack clickstack/clickstack -f values-external-clickhouse-secret.yaml +``` + + +### Using ClickHouse Cloud {#using-clickhouse-cloud} + +For ClickHouse Cloud specifically: +```yaml +# 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" +``` + +For a complete example of connecting to ClickHouse Cloud, see ["Create a ClickHouse Cloud connection"](/docs/use-cases/observability/clickstack/getting-started#create-a-cloud-connection). + +## External OTEL Collector {#external-otel-collector} + +If you have an existing OTEL collector infrastructure: +```yaml +# values-external-otel.yaml +otel: + enabled: false # Disable the built-in OTEL collector + +hyperdx: + otelExporterEndpoint: "http://your-otel-collector:4318" +``` +```shell +helm install my-clickstack clickstack/clickstack -f values-external-otel.yaml +``` + +For instructions on exposing OTEL collector endpoints via ingress, see [Ingress Configuration](/docs/use-cases/observability/clickstack/deployment/helm-configuration#otel-collector-ingress). + +## Minimal Deployment {#minimal-deployment} + +For organizations with existing infrastructure, deploy only HyperDX: +```yaml +# 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 +helm install my-clickstack clickstack/clickstack -f values-minimal.yaml +``` + +## Next Steps {#next-steps} + +- [Configuration Guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress setup +- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, and AKS specific configurations +- [Main Helm Guide](/docs/use-cases/observability/clickstack/deployment/helm) - Basic installation diff --git a/docs/use-cases/observability/clickstack/deployment/helm.md b/docs/use-cases/observability/clickstack/deployment/helm/helm.md similarity index 60% rename from docs/use-cases/observability/clickstack/deployment/helm.md rename to docs/use-cases/observability/clickstack/deployment/helm/helm.md index e992ba04976..bd457ad62da 100644 --- a/docs/use-cases/observability/clickstack/deployment/helm.md +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm.md @@ -14,6 +14,10 @@ import hyperdx_24 from '@site/static/images/use-cases/observability/hyperdx-24.p import hyperdx_login from '@site/static/images/use-cases/observability/hyperdx-login.png'; import JSONSupport from '@site/docs/use-cases/observability/clickstack/deployment/_snippets/_json_support.md'; +:::note Chart Migration +If you are currently using the `hdx-oss-v2` chart, please migrate to the `clickstack` chart. The `hdx-oss-v2` chart is in maintenance mode and will no longer receive new features. All new development is focused on the `clickstack` chart, which provides the same functionality with improved naming and better organization. +::: + The helm chart for HyperDX can be found [here](https://github.com/hyperdxio/helm-charts) and is the **recommended** method for production deployments. By default, the Helm chart provisions all core components, including: @@ -48,29 +52,26 @@ The chart supports standard Kubernetes best practices, including: - Kubernetes cluster (v1.20+ recommended) - `kubectl` configured to interact with your cluster -### Add the HyperDX Helm repository {#add-the-hyperdx-helm-repository} - -Add the HyperDX Helm repository: +### Add the ClickStack Helm repository {#add-the-clickstack-helm-repository} +Add the ClickStack Helm repository: ```shell -helm repo add hyperdx https://hyperdxio.github.io/helm-charts +helm repo add clickstack https://hyperdxio.github.io/helm-charts helm repo update ``` -### Installing HyperDX {#installing-hyperdx} - -To install the HyperDX chart with default values: +### Installing ClickStack {#installing-clickstack} +To install the ClickStack chart with default values: ```shell -helm install my-hyperdx hyperdx/hdx-oss-v2 +helm install my-clickstack clickstack/clickstack ``` ### Verify the installation {#verify-the-installation} Verify the installation: - ```shell -kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2" +kubectl get pods -l "app.kubernetes.io/name=clickstack" ``` When all pods are ready, proceed. @@ -78,18 +79,21 @@ When all pods are ready, proceed. ### Forward ports {#forward-ports} Port forwarding allows us to access and set up HyperDX. Users deploying to production should instead expose the service via an ingress or load balancer to ensure proper network access, TLS termination, and scalability. Port forwarding is best suited for local development or one-off administrative tasks, not long-term or high-availability environments. - ```shell kubectl port-forward \ - pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}') \ + pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \ 8080:3000 ``` +:::tip Production Ingress Setup +For production deployments, configure ingress with TLS instead of port forwarding. See the [Ingress Configuration guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration#ingress-setup) for detailed setup instructions. +::: + ### Navigate to the UI {#navigate-to-the-ui} Visit [http://localhost:8080](http://localhost:8080) to access the HyperDX UI. -Create a user, providing a username and password which means the requirements. +Create a user, providing a username and password which meets the requirements. HyperDX UI @@ -99,24 +103,21 @@ On clicking `Create`, data sources will be created for the ClickHouse instance d You can override the default connection to the integrated ClickHouse instance. For details, see ["Using ClickHouse Cloud"](#using-clickhouse-cloud). ::: -For an example of using an alternative ClickHouse instance, see ["Create a ClickHouse Cloud connection"](/use-cases/observability/clickstack/getting-started#create-a-cloud-connection). +For an example of using an alternative ClickHouse instance, see ["Create a ClickHouse Cloud connection"](/docs/use-cases/observability/clickstack/getting-started#create-a-cloud-connection). ### Customizing values (optional) {#customizing-values} You can customize settings by using `--set` flags. For example: - ```shell -helm install my-hyperdx hyperdx/hdx-oss-v2 --set key=value +helm install my-clickstack clickstack/clickstack --set key=value ``` Alternatively, edit the `values.yaml`. To retrieve the default values: - ```shell -helm show values hyperdx/hdx-oss-v2 > values.yaml +helm show values clickstack/clickstack > values.yaml ``` Example config: - ```yaml replicaCount: 2 resources: @@ -136,9 +137,8 @@ ingress: - path: / pathType: ImplementationSpecific ``` - ```shell -helm install my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml +helm install my-clickstack clickstack/clickstack -f values.yaml ``` ### Using secrets (optional) {#using-secrets} @@ -147,10 +147,9 @@ For handling sensitive data such as API keys or database credentials, use Kubern #### Using pre-configured secrets {#using-pre-configured-secrets} -The Helm chart includes a default secret template located at [`charts/hdx-oss-v2/templates/secrets.yaml`](https://github.com/hyperdxio/helm-charts/blob/main/charts/hdx-oss-v2/templates/secrets.yaml). This file provides a base structure for managing secrets. +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 apiVersion: v1 kind: Secret @@ -164,7 +163,6 @@ data: ``` Apply the secret to your cluster: - ```shell kubectl apply -f secrets.yaml ``` @@ -172,7 +170,6 @@ kubectl apply -f secrets.yaml #### Creating a custom secret {#creating-a-custom-secret} If you prefer, you can create a custom Kubernetes secret manually: - ```shell kubectl create secret generic hyperdx-secret \ --from-literal=API_KEY=my-secret-api-key @@ -181,7 +178,6 @@ kubectl create secret generic hyperdx-secret \ #### Referencing a secret {#referencing-a-secret} To reference a secret in `values.yaml`: - ```yaml hyperdx: apiKey: @@ -191,12 +187,15 @@ hyperdx: key: API_KEY ``` +:::tip API Key Management +For detailed API key setup instructions including multiple configuration methods and pod restart procedures, see the [API Key Setup guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration#api-key-setup). +::: + ## Using ClickHouse Cloud {#using-clickhouse-cloud} If using ClickHouse Cloud users disable the ClickHouse instance deployed by the Helm chart and specify the Cloud credentials: - ```shell # specify ClickHouse Cloud credentials export CLICKHOUSE_URL= # full https url @@ -204,11 +203,15 @@ export CLICKHOUSE_USER= export CLICKHOUSE_PASSWORD= # how to overwrite default connection -helm install myrelease hyperdx-helm --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} +helm install my-clickstack clickstack/clickstack \ + --set clickhouse.enabled=false \ + --set clickhouse.persistence.enabled=false \ + --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \ + --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \ + --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} ``` Alternatively, use a `values.yaml` file: - ```yaml clickhouse: enabled: false @@ -234,23 +237,34 @@ hyperdx: } ] ``` - ```shell -helm install my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml +helm install my-clickstack clickstack/clickstack -f values.yaml # or if installed... -# helm upgrade my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml +# helm upgrade my-clickstack clickstack/clickstack -f values.yaml ``` +:::tip Advanced External Configurations +For production deployments with secret-based configuration, external OTEL collectors, or minimal setups, see the [Deployment Options guide](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options). +::: + ## Production notes {#production-notes} By default, this chart also installs ClickHouse and the OTel collector. However, for production, it is recommended that you manage ClickHouse and the OTel collector separately. To disable ClickHouse and the OTel collector, set the following values: - ```shell -helm install myrelease hyperdx-helm --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false +helm install my-clickstack clickstack/clickstack \ + --set clickhouse.enabled=false \ + --set clickhouse.persistence.enabled=false \ + --set otel.enabled=false ``` +:::tip Production Best Practices +For production deployments including high availability configuration, resource management, ingress/TLS setup, and cloud-specific configurations (GKE, EKS, AKS), see: +- [Configuration Guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - Ingress, TLS, and secrets management +- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - Cloud-specific settings and production checklist +::: + ## Task configuration {#task-configuration} By default, there is one task in the chart setup as a cronjob, responsible for checking whether alerts should fire. Here are its configuration options: @@ -264,23 +278,20 @@ By default, there is one task in the chart setup as a cronjob, responsible for c ## Upgrading the chart {#upgrading-the-chart} To upgrade to a newer version: - ```shell -helm upgrade my-hyperdx hyperdx/hdx-oss-v2 -f values.yaml +helm upgrade my-clickstack clickstack/clickstack -f values.yaml ``` To check available chart versions: - ```shell -helm search repo hyperdx +helm search repo clickstack ``` -## Uninstalling HyperDX {#uninstalling-hyperdx} +## Uninstalling ClickStack {#uninstalling-clickstack} To remove the deployment: - ```shell -helm uninstall my-hyperdx +helm uninstall my-clickstack ``` This will remove all resources associated with the release, but persistent data (if any) may remain. @@ -288,29 +299,31 @@ This will remove all resources associated with the release, but persistent data ## Troubleshooting {#troubleshooting} ### Checking logs {#checking-logs} - ```shell -kubectl logs -l app.kubernetes.io/name=hdx-oss-v2 +kubectl logs -l app.kubernetes.io/name=clickstack ``` -### Debugging a failed install {#debugging-a-failed-instance} - +### Debugging a failed install {#debugging-a-failed-install} ```shell -helm install my-hyperdx hyperdx/hdx-oss-v2 --debug --dry-run +helm install my-clickstack clickstack/clickstack --debug --dry-run ``` ### Verifying deployment {#verifying-deployment} - ```shell -kubectl get pods -l app.kubernetes.io/name=hdx-oss-v2 +kubectl get pods -l app.kubernetes.io/name=clickstack ``` +:::tip Additional Troubleshooting Resources +For ingress-specific issues, TLS problems, or cloud deployment troubleshooting, see: +- [Ingress Troubleshooting](/docs/use-cases/observability/clickstack/deployment/helm-configuration#troubleshooting-ingress) - Asset serving, path rewrites, browser issues +- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud#loadbalancer-dns-resolution-issue) - GKE OpAMP issues and cloud-specific problems +::: + Users can set these environment variables via either parameters or the `values.yaml` e.g. *values.yaml* - ```yaml hyperdx: ... @@ -326,10 +339,23 @@ otel: ``` or via `--set`: - ```shell -helm install myrelease hyperdx-helm --set "hyperdx.env[0].name=BETA_CH_OTEL_JSON_SCHEMA_ENABLED" \ +helm install my-clickstack clickstack/clickstack \ + --set "hyperdx.env[0].name=BETA_CH_OTEL_JSON_SCHEMA_ENABLED" \ --set "hyperdx.env[0].value=true" \ --set "otel.env[0].name=OTEL_AGENT_FEATURE_GATE_ARG" \ --set "otel.env[0].value=--feature-gates=clickhouse.json" ``` + +## Related Documentation {#related-documentation} + +### Deployment Guides {#deployment-guides} +- [Deployment Options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External ClickHouse, OTEL collector, and minimal deployments +- [Configuration Guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress setup +- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, AKS configurations and production best practices + +### Additional Resources {#additional-resources} +- [ClickStack Getting Started Guide](/docs/use-cases/observability/clickstack/getting-started) - Introduction to ClickStack +- [ClickStack Helm Charts Repository](https://github.com/hyperdxio/helm-charts) - Chart source code and values reference +- [Kubernetes Documentation](https://kubernetes.io/docs/) - Kubernetes reference +- [Helm Documentation](https://helm.sh/docs/) - Helm reference From 64b17a9c55d4a687e47351cc851dbe5f7ce64efd Mon Sep 17 00:00:00 2001 From: Dominic Tran Date: Fri, 21 Nov 2025 12:25:27 -0600 Subject: [PATCH 2/2] tweaks and polish --- .../clickstack/deployment/helm/helm-cloud.md | 2 +- .../deployment/helm/helm-configuration.md | 2 +- .../helm/helm-deployment-options.md | 2 +- .../clickstack/deployment/helm/helm.md | 20 +++++++++---------- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md index 749ac2bfdb4..b323ed9dbda 100644 --- a/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-cloud.md @@ -1,6 +1,6 @@ --- slug: /use-cases/observability/clickstack/deployment/helm-cloud -title: 'Helm Cloud Deployments' +title: 'Helm cloud deployments' pagination_prev: null pagination_next: null sidebar_position: 5 diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md index ecb893ae968..65bcae02926 100644 --- a/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-configuration.md @@ -1,6 +1,6 @@ --- slug: /use-cases/observability/clickstack/deployment/helm-configuration -title: 'Helm Configuration' +title: 'Helm configuration' pagination_prev: null pagination_next: null sidebar_position: 4 diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md b/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md index a347591633e..5d016242899 100644 --- a/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm-deployment-options.md @@ -1,6 +1,6 @@ --- slug: /use-cases/observability/clickstack/deployment/helm-deployment-options -title: 'Helm Deployment Options' +title: 'Helm deployment options' pagination_prev: null pagination_next: null sidebar_position: 3 diff --git a/docs/use-cases/observability/clickstack/deployment/helm/helm.md b/docs/use-cases/observability/clickstack/deployment/helm/helm.md index bd457ad62da..f4d1dfe2c7b 100644 --- a/docs/use-cases/observability/clickstack/deployment/helm/helm.md +++ b/docs/use-cases/observability/clickstack/deployment/helm/helm.md @@ -14,7 +14,7 @@ import hyperdx_24 from '@site/static/images/use-cases/observability/hyperdx-24.p import hyperdx_login from '@site/static/images/use-cases/observability/hyperdx-login.png'; import JSONSupport from '@site/docs/use-cases/observability/clickstack/deployment/_snippets/_json_support.md'; -:::note Chart Migration +:::warning Chart Migration If you are currently using the `hdx-oss-v2` chart, please migrate to the `clickstack` chart. The `hdx-oss-v2` chart is in maintenance mode and will no longer receive new features. All new development is focused on the `clickstack` chart, which provides the same functionality with improved naming and better organization. ::: @@ -349,13 +349,13 @@ helm install my-clickstack clickstack/clickstack \ ## Related Documentation {#related-documentation} -### Deployment Guides {#deployment-guides} -- [Deployment Options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External ClickHouse, OTEL collector, and minimal deployments -- [Configuration Guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress setup -- [Cloud Deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, AKS configurations and production best practices +### Deployment guides {#deployment-guides} +- [Deployment options](/docs/use-cases/observability/clickstack/deployment/helm-deployment-options) - External ClickHouse, OTEL collector, and minimal deployments +- [Configuration guide](/docs/use-cases/observability/clickstack/deployment/helm-configuration) - API keys, secrets, and ingress setup +- [Cloud deployments](/docs/use-cases/observability/clickstack/deployment/helm-cloud) - GKE, EKS, AKS configurations and production best practices -### Additional Resources {#additional-resources} -- [ClickStack Getting Started Guide](/docs/use-cases/observability/clickstack/getting-started) - Introduction to ClickStack -- [ClickStack Helm Charts Repository](https://github.com/hyperdxio/helm-charts) - Chart source code and values reference -- [Kubernetes Documentation](https://kubernetes.io/docs/) - Kubernetes reference -- [Helm Documentation](https://helm.sh/docs/) - Helm reference +### Additional resources {#additional-resources} +- [ClickStack getting started guide](/docs/use-cases/observability/clickstack/getting-started) - Introduction to ClickStack +- [ClickStack Helm charts repository](https://github.com/hyperdxio/helm-charts) - Chart source code and values reference +- [Kubernetes documentation](https://kubernetes.io/docs/) - Kubernetes reference +- [Helm documentation](https://helm.sh/docs/) - Helm reference