Helm (v1.x)

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

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.

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

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

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

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

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

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