Saltar al contenido principal
Obsoleto — gráfico v1.xEsta página documenta la configuración del gráfico de Helm v1.x con plantillas en línea, que está en modo de mantenimiento. Para el gráfico v2.x, consulta Configuración de Helm. Para migrar, consulta la guía de actualización.
Esta guía describe las opciones de configuración para las implementaciones de ClickStack con Helm. Para la instalación básica, consulta la guía principal de implementación con Helm.

​
Configuración de la clave API

Tras implementar correctamente ClickStack, configure la clave API para habilitar la recopilación de datos de telemetría:
  1. Acceda a su instancia de HyperDX a través del Ingreso configurado o del endpoint del servicio
  2. Inicie sesión en el dashboard de HyperDX y vaya a la configuración del equipo para generar o recuperar su clave API
  3. Actualice su implementación con la clave API mediante uno de los siguientes métodos:

​
Método 1: Actualizar con Helm upgrade usando un archivo de valores

Añade la clave API a tu values.yaml: 
hyperdx:
  apiKey: "your-api-key-here"
Luego, actualiza tu despliegue: 
helm upgrade my-clickstack clickstack/clickstack -f values.yaml

​
Método 2: Actualizar mediante helm upgrade con la opción —set

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

​
Reinicia los pods para aplicar los cambios

Después de actualizar la clave API, reinicia los pods para que carguen la nueva configuración: 
kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector
El gráfico crea automáticamente un secreto de Kubernetes (<release-name>-app-secrets) con su clave API. No hace falta ninguna configuración adicional del secreto, salvo que quiera usar un secreto externo.

​
Gestión de secretos

Para gestionar datos sensibles, como claves de API o credenciales de la base de datos, utiliza secretos de Kubernetes.

​
Uso de secretos preconfigurados

El gráfico de Helm incluye una plantilla de secreto predeterminada ubicada en charts/clickstack/templates/secrets.yaml. Este archivo proporciona una estructura básica para gestionar secretos. Si necesita aplicar un secreto manualmente, modifique y aplique la plantilla secrets.yaml proporcionada: 
apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>
Aplica el secreto en tu clúster: 
kubectl apply -f secrets.yaml

​
Crear un secreto personalizado

Cree manualmente un secreto de Kubernetes personalizado: 
kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

​
Referenciar un secreto en values.yaml

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

​
Configuración de Ingreso

Para exponer la UI y la API de HyperDX mediante un nombre de dominio, habilita el Ingreso en tu values.yaml.

​
Configuración general del ingreso

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Debe coincidir con el host de ingreso
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
Nota importante sobre la configuraciónhyperdx.frontendUrl debe coincidir con el host configurado en el Ingreso e incluir el protocolo (por ejemplo, https://hyperdx.yourdomain.com). Esto garantiza que todos los enlaces, las cookies y las redirecciones generados funcionen correctamente.

​
Habilitar TLS (HTTPS)

Para proteger su despliegue con HTTPS: 1. Cree un secreto de TLS con su certificado y clave privada: 
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
2. Activa TLS en la configuración de tu ingreso: 
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

​
Ejemplo de configuración de ingreso

Como referencia, este es el aspecto del recurso de ingreso generado: 
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

​
Errores comunes de Ingreso

Configuración de path y reescritura:
  • Para Next.js y otras SPA, use siempre una ruta con expresión regular y una anotación de reescritura, como se muestra arriba
  • No use solo path: / sin una reescritura, ya que esto impedirá que los recursos estáticos se sirvan correctamente
frontendUrl e ingress.host no coinciden:
  • Si no coinciden, puede tener problemas con las cookies, las redirecciones y la carga de recursos
Configuración incorrecta de TLS:
  • Asegúrese de que su secreto de TLS sea válido y esté referenciado correctamente en el Ingreso
  • Los navegadores pueden bloquear contenido no seguro si accede a la aplicación por HTTP cuando TLS está habilitado
Versión del controlador de Ingreso:
  • Algunas funciones (como las rutas con expresión regular y las reescrituras) requieren versiones recientes del controlador de Ingreso de nginx
  • Compruebe su versión con:
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

​
Ingreso del OTel collector

Si necesitas exponer los endpoints de tu OTel collector (para trazas, métricas y logs) mediante Ingreso, usa la configuración additionalIngresses. Esto resulta útil para enviar datos de telemetría desde fuera del clúster o para usar un dominio personalizado para el 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
  • Esto crea un recurso de Ingreso independiente para los endpoints del OTel collector
  • Puede usar un dominio distinto, configurar opciones específicas de TLS y aplicar anotaciones personalizadas
  • La regla de ruta con regex le permite enrutar todas las señales OTLP (trazas, métricas y logs) mediante una sola regla
Si no necesita exponer el OTel collector externamente, puede omitir esta configuración. Para la mayoría de los usuarios, la configuración general de Ingreso es suficiente.

​
Solución de problemas del ingreso

Verifique el recurso de ingreso: 
kubectl get ingress -A
kubectl describe ingress <ingress-name>
Compruebe los logs del controlador de Ingreso: 
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
URL de prueba de los recursos: Usa curl para verificar que los recursos estáticos se sirvan como JS y no como HTML: 
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Debe retornar Content-Type: application/javascript
Herramientas de desarrollo del navegador:
  • Revise la pestaña Network para ver si hay errores 404 o recursos que devuelven HTML en lugar de JS
  • Busque errores como Unexpected token < en la consola (indica que se devolvió HTML en lugar de JS)
Compruebe si hay reescrituras de rutas:
  • Asegúrese de que el Ingreso no esté eliminando ni reescribiendo incorrectamente las rutas de los recursos
Borre la caché del navegador y de la CDN:
  • Después de realizar cambios, borre la caché del navegador y cualquier caché de CDN/proxy para evitar recursos obsoletos

​
Personalizar valores

Puedes personalizar la configuración mediante las opciones --set: 
helm install my-clickstack clickstack/clickstack --set key=value
Como alternativa, cree un values.yaml personalizado. Para obtener los valores predeterminados: 
helm show values clickstack/clickstack > values.yaml
Configuración de ejemplo: 
replicaCount: 2

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

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com
Aplica tus valores personalizados: 
helm install my-clickstack clickstack/clickstack -f values.yaml

​
Siguientes pasos

Última modificación el 10 de junio de 2026