Helm (v1.x) - ClickHouse Documentation

Obsoleto — gráfico v1.xEsta página documenta el gráfico de Helm v1.x con plantillas en línea, que está en modo de mantenimiento y ya no recibirá nuevas características. Para implementaciones nuevas, use el gráfico v2.x. Para migrar una implementación v1.x existente, consulte la guía de actualización.

El gráfico de Helm para ClickStack se puede encontrar aquí y es el método recomendado para implementaciones en producción. De forma predeterminada, el gráfico de Helm aprovisiona todos los componentes principales, incluidos:

ClickHouse
HyperDX
colector de OpenTelemetry (OTel)
MongoDB (para el estado persistente de la aplicación)

Sin embargo, se puede personalizar 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 e Ingreso
Gestión de secretos y configuración de autenticación

Apto para

Pruebas de concepto
Producción

Pasos de despliegue

Requisitos previos

Helm v3+
Clúster de Kubernetes (se recomienda v1.20+)
kubectl configurado para interactuar con su clúster

Añadir el repositorio de Helm de ClickStack

Añada el repositorio de Helm de ClickStack:

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

Instalación de ClickStack

Para instalar el chart de ClickStack con los valores predeterminados:

helm install my-clickstack clickstack/clickstack

Verificar 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 permite acceder a HyperDX y configurarlo. Quienes desplieguen en producción deberían, en su lugar, 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 o 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 para producciónPara las implementaciones 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 ver instrucciones detalladas.

Accede a la UI

Visita http://localhost:8080 para acceder a la UI de HyperDX.Crea un usuario e introduce 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.

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

Personalizar valores (opcional)

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

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

Como alternativa, edite el values.yaml. 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
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

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

Uso de secretos (opcional)

Para gestionar datos sensibles, como claves de API o credenciales de base de datos, usa secretos de Kubernetes. Los gráficos de Helm de HyperDX proporcionan archivos de secretos predeterminados que puedes modificar y aplicar a tu clúster.

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 necesitas aplicar manualmente un secreto, modifica y aplica 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>

Aplique el secreto a su clúster:

kubectl apply -f secrets.yaml

Crear un secret personalizado

Si lo prefieres, puedes crear manualmente un secret personalizado de Kubernetes:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

Hacer referencia a un secret

Para hacer referencia a un secret en values.yaml:

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

Gestión de claves de APIPara obtener instrucciones detalladas sobre cómo configurar la clave de API, incluidos varios métodos de configuración y procedimientos para reiniciar el pod de Kubernetes, consulte la guía de configuración de la clave de API.

Uso de ClickHouse Cloud

Si utiliza ClickHouse Cloud, desactive la instancia de ClickHouse implementada con el gráfico de Helm y especifique las credenciales de Cloud:

# especificar las credenciales de ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # url https completa
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# cómo sobreescribir la conexión predeterminada
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}

Como alternativa, utiliza un archivo values.yaml:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# o si ya está instalado...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

Configuraciones externas avanzadasPara implementaciones en 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 de producción

De forma predeterminada, este gráfico también instala ClickHouse y el OTel collector. Sin embargo, para un entorno de producción, se recomienda gestionar ClickHouse y el OTel collector por separado. Para deshabilitar ClickHouse y el OTel collector, establezca los siguientes valores:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

Buenas prácticas para producciónPara despliegues en producción, incluida la configuración de alta disponibilidad, la gestión de recursos, la configuración de Ingreso y TLS, y las configuraciones específicas de Cloud (GKE, EKS, AKS), consulta:

Guía de configuración - Ingreso, TLS y gestión de secretos
Despliegues en Cloud - Configuraciones específicas de Cloud y lista de verificación para producción

Configuración de tareas

De forma predeterminada, hay una tarea en la configuración del gráfico como cronjob, responsable de comprobar si deben activarse las alertas. Estas son sus opciones de configuración:

Parámetro	Descripción	Predeterminado
`tasks.enabled`	Habilita/deshabilita las tareas cron en el clúster. De forma predeterminada, la imagen de HyperDX ejecutará las tareas cron en el mismo proceso. Cámbielo a true si prefiere usar una tarea cron independiente en el clúster.	`false`
`tasks.checkAlerts.schedule`	Programación cron de la tarea check-alerts	`/1 * * *`
`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 consultar las versiones disponibles del gráfico:

helm search repo clickstack

Actualización a v2.xSi quieres migrar al gráfico v2.x basado en subgráficos, consulta la guía de actualización para ver las instrucciones de migración. Este cambio rompe la compatibilidad: no se admite ejecutar helm upgrade sobre la instalación existente.

Desinstalar ClickStack

Para eliminar la implementación:

helm uninstall my-clickstack

Esto eliminará todos los recursos asociados con el release, pero los datos persistentes (si los hay) pueden permanecer.

Solución de problemas

Revisión de 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 para la solución de problemasPara problemas específicos de Ingreso, problemas de TLS o solución de problemas de implementaciones en Cloud, consulta:

Solución de problemas de Ingreso - Entrega de recursos, reescritura de rutas, problemas del navegador
Implementaciones en Cloud - Problemas de OpAMP en GKE 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.

Guías de despliegue v1.x

Opciones de despliegue (v1.x) - ClickHouse externo, OTel collector y despliegues mínimos
Guía de configuración (v1.x) - claves de API, secretos y configuración de Ingreso
Despliegues en Cloud (v1.x) - configuraciones de GKE, EKS y AKS, y buenas prácticas de producción

Documentación de v2.x

Helm (v2.x) - guía de despliegue de v2.x
Guía de actualización - migración de v1.x a v2.x

Recursos adicionales

Guía de introducción a 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

​Apto para

​Pasos de despliegue

​Uso de secretos preconfigurados

​Crear un secret personalizado

​Hacer referencia a un secret

​Uso de ClickHouse Cloud

​Notas de producción

​Configuración de tareas

​Actualizar el gráfico

​Desinstalar ClickStack

​Solución de problemas

​Revisión de logs

​Depurar una instalación fallida

​Verificar la implementación

​Elección del esquema: Map vs JSON

​Documentación relacionada

​Guías de despliegue v1.x

​Documentación de v2.x

​Recursos adicionales

Apto para

Pasos de despliegue

Uso de secretos preconfigurados

Crear un secret personalizado

Hacer referencia a un secret

Uso de ClickHouse Cloud

Notas de producción

Configuración de tareas

Actualizar el gráfico

Desinstalar ClickStack

Solución de problemas

Revisión de logs

Depurar una instalación fallida

Verificar la implementación

Elección del esquema: Map vs JSON

Documentación relacionada

Guías de despliegue v1.x

Documentación de v2.x

Recursos adicionales