Helm

Despliegue de ClickStack con Helm - La pila de observabilidad de ClickHouse

Versión 2.x del gráfico

Esta página documenta el gráfico de Helm v2.x basado en subgráficos. Si todavía usas el gráfico v1.x con plantillas en línea, consulta la guía de Helm v1.x. Para ver los pasos de migración, consulta la guía de actualización.

El gráfico de Helm de ClickStack está disponible aquí y es el método recomendado para despliegues en producción.

El gráfico v2.x utiliza una instalación en dos fases. Primero se instalan los operadores y las CRD mediante el gráfico clickstack-operators, y después el gráfico principal clickstack, que crea recursos personalizados gestionados por operadores para ClickHouse, MongoDB y el OpenTelemetry Collector.

De forma predeterminada, el gráfico de Helm aprovisiona todos los componentes principales, incluidos:

• ClickHouse — gestionado por el ClickHouse Operator mediante los recursos personalizados ClickHouseCluster y KeeperCluster
• HyperDX — la UI y la API de observabilidad
• collector de OpenTelemetry (OTel) — desplegado mediante el gráfico oficial de Helm del OpenTelemetry Collector como subgráfico
• MongoDB — gestionado por el MongoDB Kubernetes Operator (MCK) mediante un recurso personalizado MongoDBCommunity

Sin embargo, puede personalizarse fácilmente para integrarse con una implementación existente de ClickHouse; por ejemplo, una alojada en ClickHouse Cloud.

El gráfico admite las buenas prácticas estándar de Kubernetes, entre ellas:

• Configuración específica del entorno mediante values.yaml
• Límites de recursos y escalado a nivel de pod
• Configuración de TLS y de Ingreso
• Gestión de secretos y configuración de la autenticación
• Manifiestos adicionales para desplegar objetos arbitrarios de Kubernetes (NetworkPolicy, HPA, ALB Ingress, etc.) junto con el gráfico

​

Apto para

• Pruebas de concepto
• Producción

​

Pasos de implementación

1. ​

   Requisitos previos

   • Helm v3+
   • Clúster de Kubernetes (se recomienda la versión 1.20 o superior)
   • kubectl configurado para interactuar con su clúster
2. ​

   Agrega el repositorio de Helm de ClickStack

   Agrega el repositorio de Helm de ClickStack:

   helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
   helm repo update
   
3. ​

   Instala los operadores

   Instala primero el chart del operador. Esto registra los CRD necesarios para el chart principal:

   helm install clickstack-operators clickstack/clickstack-operators
   

   Espere a que los pods del operador estén listos antes de continuar:

   kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
   
4. ​

   Instalar ClickStack

   Una vez que los operadores estén en funcionamiento, instale el chart principal:

   helm install my-clickstack clickstack/clickstack
   
5. ​

   Verifique la instalación

   Verifique la instalación:

   kubectl get pods -l "app.kubernetes.io/name=clickstack"
   

   Cuando todos los pods estén listos, continúe.

6. ​

   Reenvío de puertos

   El reenvío de puertos nos permite acceder a HyperDX y configurarlo. En los despliegues en producción, en su lugar, se debe exponer el servicio mediante un Ingreso o un balanceador de carga para garantizar un acceso de red adecuado, la terminación de TLS y la escalabilidad. El reenvío de puertos es más adecuado para el desarrollo local o para tareas administrativas puntuales, no para entornos de larga duración ni de alta disponibilidad.

   kubectl port-forward \
     pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
     8080:3000
   

   Configuración del Ingreso en producción

   Para despliegues en producción, configure el Ingreso con TLS en lugar de usar el reenvío de puertos. Consulte la guía de configuración de Ingreso para obtener instrucciones detalladas.

7. ​

   Accede a la UI

   Visita http://localhost:8080 para acceder a la UI de HyperDX.

   Crea un usuario con un nombre de usuario y una contraseña que cumplan los requisitos.

   Al hacer clic en Create, se crearán fuentes de datos para la instancia de ClickHouse desplegada con el gráfico de Helm.

   Cambiar la conexión predeterminada

   Puedes cambiar la conexión predeterminada a la instancia integrada de ClickHouse. Para obtener más información, consulta “Uso de ClickHouse Cloud”.

8. ​

   Personalización de valores (opcional)

   Puede personalizar la configuración con las opciones --set. Por ejemplo:

   helm install my-clickstack clickstack/clickstack --set key=value
   

   Como alternativa, edita el values.yaml. Para obtener los valores predeterminados:

   helm show values clickstack/clickstack > values.yaml
   

   Ejemplo de configuración:

   hyperdx:
     frontendUrl: "https://hyperdx.example.com"
   
     deployment:
       replicas: 2
       resources:
         limits:
           cpu: "2"
           memory: 4Gi
         requests:
           cpu: 500m
           memory: 1Gi
   
     ingress:
       enabled: true
       host: hyperdx.example.com
       tls:
         enabled: true
         tlsSecretName: "hyperdx-tls"
   

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

   Uso de secretos (opcional)

   El chart v2.x utiliza un secreto unificado (clickstack-secret) que se rellena a partir de hyperdx.secrets en tus values. Todas las variables de entorno sensibles —incluidas las contraseñas de ClickHouse, las contraseñas de MongoDB y la API key de HyperDX— se gestionan a través de este único secreto.

   Para sobrescribir los valores del secreto:

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

   Para la gestión externa de secretos (p. ej., con un operador de secretos), puedes hacer referencia a un secreto de Kubernetes preexistente:

   hyperdx:
     useExistingConfigSecret: true
     existingConfigSecret: "my-external-secret"
     existingConfigConnectionsKey: "connections.json"
     existingConfigSourcesKey: "sources.json"
   

   Gestión de claves de API

   Para obtener instrucciones detalladas sobre la configuración de claves de API, incluidos varios métodos de configuración y procedimientos para reiniciar pods de Kubernetes, consulta la guía de configuración de claves de API.

​

Uso de ClickHouse Cloud

Si utiliza ClickHouse Cloud, desactive la instancia de ClickHouse integrada y proporcione sus credenciales de Cloud:

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

Cree por separado el secret de conexión:

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

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

Configuraciones externas avanzadas

Para implementaciones de producción con configuración basada en secretos, OTel collectors externos o configuraciones mínimas, consulta la guía de opciones de implementación.

​

Notas sobre producción

De forma predeterminada, este gráfico instala ClickHouse, MongoDB y el OTel collector. Para un entorno de producción, se recomienda administrar ClickHouse y el OTel collector por separado.

Para deshabilitar ClickHouse y el OTel collector:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

Buenas prácticas para producción

Para despliegues en producción, incluidos la configuración de alta disponibilidad, la gestión de recursos, la configuración de Ingreso/TLS y las configuraciones específicas de Cloud (GKE, EKS, AKS), consulta:

• Guía de configuración - Gestión de Ingreso, TLS y secretos
• Implementaciones en Cloud - Configuraciones específicas de Cloud y lista de comprobación para producción

​

Configuración de tareas

De forma predeterminada, la configuración del gráfico incluye una tarea como cronjob, encargada de comprobar si deben dispararse alertas. En la versión 2.x, la configuración de tareas se ha movido a hyperdx.tasks:

Parámetro	Descripción	Predeterminado
hyperdx.tasks.enabled	Activa/desactiva las tareas cron en el clúster. De forma predeterminada, la imagen de HyperDX ejecutará las tareas cron dentro del propio proceso. Cámbielo a true si prefiere usar una tarea cron independiente en el clúster.	false
hyperdx.tasks.checkAlerts.schedule	Programación cron de la tarea check-alerts	*/1 * * * *
hyperdx.tasks.checkAlerts.resources	Solicitudes y límites de recursos para la tarea check-alerts	Consulte values.yaml

​

Actualizar el gráfico

Para actualizar a una versión más reciente:

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

Para ver las versiones disponibles del gráfico:

helm search repo clickstack

Actualización desde v1.x

Si está actualizando desde el gráfico inline-template de v1.x, consulte la guía de actualización para ver las instrucciones de migración. Este es un cambio incompatible: no se admite ejecutar helm upgrade sobre la instalación existente.

​

Desinstalar ClickStack

Desinstálelo en orden inverso:

helm uninstall my-clickstack            # Eliminar la app + CRs primero
helm uninstall clickstack-operators     # Eliminar los operadores + CRDs

Nota: Las PersistentVolumeClaims creadas por los operadores de MongoDB y de ClickHouse no se eliminan con helm uninstall. Esto es intencional para evitar la pérdida accidental de datos. Para limpiar los PVC, consulta:

• documentación del operador de Kubernetes de MongoDB

​

Solución de problemas

​

Revisión de los logs

kubectl logs -l app.kubernetes.io/name=clickstack

​

Depurar una instalación fallida

helm install my-clickstack clickstack/clickstack --debug --dry-run

​

Verificar la implementación

kubectl get pods -l app.kubernetes.io/name=clickstack

Recursos adicionales de troubleshooting

Para problemas específicos de Ingreso, problemas de TLS o troubleshooting de implementaciones en Cloud, consulta:

• Troubleshooting de Ingreso - Entrega de recursos, reescritura de rutas, problemas del navegador
• Implementaciones en Cloud - Problemas de GKE OpAMP y problemas específicos de Cloud

​

Elección del esquema: Map vs JSON

ClickStack almacena los atributos como columnas Map(LowCardinality(String), String) de forma predeterminada. Este es el esquema recomendado para las cargas de trabajo de observabilidad. En combinación con la serialización de mapas por buckets y los índices de texto sobre las claves y los valores del mapa, ofrece lookups selectivos sin la sobrecarga de ingesta por clave de las subcolumnas JSON dinámicas.

También hay disponible, en fase beta, un esquema de tipo JSON para evaluarlo en cargas de trabajo con un conjunto pequeño y estable de claves de atributos. No se recomienda como opción predeterminada. Consulta Map vs tipo JSON para ver la comparación completa y las variables de entorno necesarias para habilitar la compatibilidad con JSON.

​

Documentación relacionada

​

Guías de implementación

• Opciones de implementación - ClickHouse externo, OTel collector e implementaciones mínimas
• Guía de configuración - claves de API, secretos y configuración del Ingreso
• Implementaciones en Cloud - configuraciones de GKE, EKS y AKS, y buenas prácticas de producción
• Guía de actualización - Migración de v1.x a v2.x
• Manifiestos adicionales - Implementación de objetos personalizados de Kubernetes junto con el gráfico

​

documentación de la versión 1.x

• Helm (v1.x) - guía de implementación para v1.x
• Configuración (v1.x) - configuración de v1.x
• Opciones de implementación (v1.x) - opciones de implementación de v1.x
• Implementaciones en Cloud (v1.x) - configuraciones de Cloud de v1.x

​

Recursos adicionales

• Guía de inicio de ClickStack - Introducción a ClickStack
• Repositorio de gráficos de Helm de ClickStack - Código fuente del gráfico y referencia de valores
• Documentación de Kubernetes - Referencia de Kubernetes
• Documentación de Helm - Referencia de Helm