Helm

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

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

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

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

Instalar ClickStack

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

helm install my-clickstack clickstack/clickstack

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.

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

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.

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

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"

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

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

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

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

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.

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