Configuración de Helm - ClickHouse Documentation

Versión 2.x del gráficoEsta página documenta el gráfico de Helm v2.x basado en subgráficos. Si todavía utilizas el gráfico v1.x con plantillas en línea, consulta Configuración de Helm (v1.x). Para conocer los pasos de migración, consulta la guía de actualización.

Esta guía describe las opciones de configuración para implementaciones de ClickStack con Helm. Para la instalación básica, consulta la guía principal de implementación con Helm.

Organización de los valores

El gráfico v2.x organiza los valores por tipo de recurso de Kubernetes dentro del bloque hyperdx::

hyperdx:
  ports:          # Números de puerto compartidos (Implementación, Service, ConfigMap, Ingreso)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"

  config:         # → clickstack-config ConfigMap (variables de entorno no sensibles)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (variables de entorno sensibles)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # Especificación de Implementación de K8s (imagen, réplicas, sondas, etc.)
  service:        # Especificación de Service de K8s (tipo, anotaciones)
  ingress:        # Especificación de Ingreso de K8s (host, tls, anotaciones)
  podDisruptionBudget:  # Especificación de PDB de K8s
  tasks:          # Especificaciones de CronJob de K8s

Todas las variables de entorno se canalizan a través de dos recursos con nombres estáticos compartidos por la Implementación de HyperDX y el OTel collector mediante envFrom:

clickstack-config ConfigMap — se rellena a partir de hyperdx.config
clickstack-secret secreto — se rellena a partir de hyperdx.secrets

Ya no existe un ConfigMap independiente específico para OTel. Ambas cargas de trabajo leen de las mismas fuentes.

Configuración de la clave de API

Después de implementar ClickStack correctamente, configura la clave de API para habilitar la recopilación de datos de telemetría:

Accede a tu instancia de HyperDX a través del Ingreso configurado o del endpoint del servicio
Inicia sesión en el panel de HyperDX y ve a la configuración del equipo para generar o recuperar tu clave de API
Actualiza tu Implementación con la clave de API usando uno de los siguientes métodos:

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

Añade la API key a tu values.yaml:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"

A continuación, actualiza tu Implementación:

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

Método 2: Actualizar con `helm upgrade` usando la opción `--set`

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

Reinicie los pods para aplicar los cambios

Después de actualizar la clave de API, reinicie los pods para que carguen la nueva configuración:

kubectl rollout restart deployment my-clickstack-clickstack-app

El gráfico crea automáticamente un secreto de Kubernetes (clickstack-secret) con los valores de su configuración. No se necesita ninguna configuración adicional del secreto, a menos 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, el gráfico v2.x proporciona un recurso unificado clickstack-secret cuyos valores se rellenan a partir de hyperdx.secrets.

Valores predeterminados de los secretos

El gráfico incluye valores predeterminados para todos los secretos. Sobrescríbalos en su values.yaml:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-otel-password"
    CLICKHOUSE_APP_PASSWORD: "your-clickhouse-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

Uso de un secreto externo

Para implementaciones de producción en las que desee mantener las credenciales separadas de los valores de Helm, utilice un secreto externo de Kubernetes:

# Crea tu secreto
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password

Luego, haz referencia a esto en tus values:

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

Configuración del 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 de 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, cookies y redirecciones generados funcionen correctamente.

Habilitar TLS (HTTPS)

Para proteger su Implementación con HTTPS: 1. Cree un secreto de TLS con su certificado y su clave privada:

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

2. Habilite TLS en la configuración de su Ingreso:

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

Ejemplo de configuración de ingreso

A modo de referencia, así se ve el 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 del Ingreso

Configuración de rutas y reescritura:

Para Next.js y otras SPA, usa siempre una ruta con regex y una anotación de reescritura, como se muestra arriba
No uses solo path: / sin una reescritura, ya que esto romperá la entrega de recursos estáticos

frontendUrl e ingress.host no coinciden:

Si no coinciden, puedes tener problemas con las cookies, las redirecciones y la carga de recursos

Configuración incorrecta de TLS:

Asegúrate de que tu secreto de TLS sea válido y esté referenciado correctamente en el Ingreso
Los navegadores pueden bloquear contenido no seguro si accedes a la aplicación por HTTP cuando TLS está habilitado

Versión del controlador de Ingreso:

Algunas funciones (como las rutas con regex y las reescrituras) requieren versiones recientes del controlador de Ingreso de NGINX
Comprueba tu 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 necesita exponer los endpoints de su OTel collector (para trazas, métricas y logs) a través de Ingreso, use la configuración additionalIngresses. Esto es ú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 del Ingreso es suficiente.

Como alternativa, puede usar additionalManifests para definir recursos de Ingreso totalmente personalizados, como un Ingreso de AWS ALB.

Configuración del OTel collector

El OTel Collector se despliega mediante el gráfico de Helm oficial de OpenTelemetry Collector como subgráfico otel-collector:. Configúralo directamente en otel-collector: dentro de tus valores:

otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

Las variables de entorno (endpoint de ClickHouse, URL de OpAMP, etc.) se comparten mediante el ConfigMap unificado clickstack-config y el Secret clickstack-secret. El extraEnvsFrom del subgráfico ya está configurado para leer de ambos. Consulta el gráfico de Helm de OpenTelemetry Collector para ver todos los valores disponibles del subgráfico.

Configuración de MongoDB

MongoDB es gestionado por el operador MCK mediante un recurso personalizado MongoDBCommunity. La especificación del CR se genera literalmente a partir de mongodb.spec:

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

La contraseña de MongoDB se configura en hyperdx.secrets.MONGODB_PASSWORD. Consulta la documentación de MCK para ver todos los campos CRD disponibles.

Configuración de ClickHouse

ClickHouse se gestiona mediante el ClickHouse Operator a través de los recursos personalizados ClickHouseCluster y KeeperCluster. Las especificaciones de ambos CR se renderizan literalmente a partir de los valores:

clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Las credenciales de usuario de ClickHouse provienen de hyperdx.secrets (no de clickhouse.config.users, como en la versión v1.x). Consulta la guía de configuración de ClickHouse Operator para conocer todos los campos disponibles de la CRD.

Solución de problemas del Ingreso

Revise el recurso de Ingreso:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

Revise los logs del controlador de ingreso:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

Probar las URL de los recursos: Usa curl para verificar que los recursos estáticos se sirvan como JavaScript, 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:

Revisa la pestaña Network para detectar errores 404 o recursos que devuelvan HTML en lugar de JS
Busca errores como Unexpected token < en la consola (indica que se devolvió HTML en vez de JS)

Comprueba si hay reescrituras de rutas:

Asegúrate de que el Ingreso no esté eliminando ni reescribiendo incorrectamente las rutas de los recursos

Borra la caché del navegador y la de la CDN:

Después de hacer cambios, borra la caché del navegador y cualquier caché de CDN/proxy para evitar recursos desactualizados

Personalización de valores

Puede 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

Aplica valores personalizados:

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

Próximos pasos

Opciones de implementación - Sistemas externos e implementaciones mínimas
Implementaciones en Cloud - Configuraciones de GKE, EKS y AKS
Guía de actualización - Migración de v1.x a v2.x
Manifiestos adicionales - Objetos personalizados de Kubernetes
Guía principal de Helm - Instalación básica
Configuración (v1.x) - Guía de configuración de v1.x

​Organización de los valores

​Configuración de la clave de API

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

​Método 2: Actualizar con helm upgrade usando la opción --set

​Reinicie los pods para aplicar los cambios

​Gestión de secretos

​Valores predeterminados de los secretos

​Uso de un secreto externo

​Configuración del ingreso

​Configuración general de Ingreso

​Habilitar TLS (HTTPS)

​Ejemplo de configuración de ingreso

​Errores comunes del Ingreso

​Ingreso del OTel collector

​Configuración del OTel collector

​Configuración de MongoDB

​Configuración de ClickHouse

​Solución de problemas del Ingreso

​Personalización de valores

​Próximos pasos

Organización de los valores

Configuración de la clave de API

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

Método 2: Actualizar con `helm upgrade` usando la opción `--set`

Reinicie los pods para aplicar los cambios

Gestión de secretos

Valores predeterminados de los secretos

Uso de un secreto externo

Configuración del ingreso

Configuración general de Ingreso

Habilitar TLS (HTTPS)

Ejemplo de configuración de ingreso

Errores comunes del Ingreso

Ingreso del OTel collector

Configuración del OTel collector

Configuración de MongoDB

Configuración de ClickHouse

Solución de problemas del Ingreso

Personalización de valores

Próximos pasos