Helm

Развертывание ClickStack с помощью Helm — стек обсервабилити ClickHouse

Версия Helm-чарта 2.x

На этой странице описан Helm-чарт v2.x на основе субчартов. Если вы всё ещё используете чарт v1.x со встроенными шаблонами, см. руководство по Helm v1.x. Инструкции по миграции см. в руководстве по обновлению.

Helm-чарт для ClickStack доступен здесь и является рекомендуемым способом развертывания в production.

В чарте v2.x используется двухэтапная установка. Сначала через чарт clickstack-operators устанавливаются операторы и CRD, затем — основной чарт clickstack, который создаёт управляемые операторами пользовательские ресурсы для ClickHouse, MongoDB и OpenTelemetry Collector.

По умолчанию Helm-чарт разворачивает все основные компоненты, включая:

• ClickHouse — управляется ClickHouse Operator через пользовательские ресурсы ClickHouseCluster и KeeperCluster
• HyperDX — интерфейс и API для обсервабилити
• OpenTelemetry (OTel) collector — разворачивается как субчарт через официальный Helm-чарт OpenTelemetry Collector
• MongoDB — управляется MongoDB Kubernetes Operator (MCK) через пользовательский ресурс MongoDBCommunity

Однако его можно легко настроить для интеграции с существующим развертыванием ClickHouse — например, в ClickHouse Cloud.

Чарт поддерживает стандартные рекомендации Kubernetes, включая:

• Конфигурацию для конкретных сред через values.yaml
• Ограничения ресурсов и масштабирование на уровне подов
• Настройку TLS и входного шлюза
• Управление секретами и настройку аутентификации
• Дополнительные манифесты для развертывания произвольных объектов Kubernetes (NetworkPolicy, HPA, ALB Ingress и т. д.) вместе с чартом

​

Подходит для

• Пилотных проектов
• Промышленной эксплуатации

​

Шаги развертывания

1. ​

   Предварительные требования

   • Helm v3+
   • кластер Kubernetes (рекомендуется v1.20+)
   • настроенный kubectl для взаимодействия с вашим кластером
2. ​

   Добавьте репозиторий Helm ClickStack

   Добавьте репозиторий Helm ClickStack:

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

   Установите операторы

   Сначала установите чарт оператора. При этом будут зарегистрированы CRD, необходимые для основного чарта:

   helm install clickstack-operators clickstack/clickstack-operators
   

   Подождите, пока поды оператора не перейдут в состояние Ready, прежде чем продолжить:

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

   Установите ClickStack

   После запуска операторов установите основной чарт:

   helm install my-clickstack clickstack/clickstack
   
5. ​

   Проверьте установку

   Проверьте установку:

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

   После того как все поды будут готовы, продолжайте.

6. ​

   Проброс портов

   Проброс портов позволяет получить доступ к HyperDX и настроить его. При развертывании в рабочей среде вместо этого следует открывать доступ к сервису через входной шлюз или балансировщик нагрузки, чтобы обеспечить корректный сетевой доступ, терминацию TLS и масштабируемость. Проброс портов лучше всего подходит для локальной разработки или разовых административных задач, а не для долгосрочного использования или сред с высокой доступностью.

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

   Настройка входного шлюза для продуктивной среды

   Для развертываний в продуктивной среде настройте входной шлюз с TLS вместо проброса портов. Подробные инструкции см. в руководстве по настройке входного шлюза.

7. ​

   Откройте интерфейс

   Перейдите по адресу http://localhost:8080, чтобы открыть интерфейс HyperDX.

   Создайте пользователя, указав имя пользователя и пароль, соответствующие требованиям.

   После нажатия Create для экземпляра ClickHouse, развернутого с помощью Helm-чарта, будут созданы источники данных.

   Переопределение подключения по умолчанию

   Вы можете переопределить подключение по умолчанию к встроенному экземпляру ClickHouse. Подробнее см. в разделе “Использование ClickHouse Cloud”.

8. ​

   Переопределение значений (необязательно)

   Вы можете переопределить параметры с помощью флагов --set. Например:

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

   Или отредактируйте values.yaml. Чтобы получить значения по умолчанию:

   helm show values clickstack/clickstack > values.yaml
   

   Пример конфигурации:

   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. ​

   Использование секретов (необязательно)

   Чарт v2.x использует единый secret (clickstack-secret), который заполняется из hyperdx.secrets в ваших values. Все конфиденциальные переменные окружения — включая пароли ClickHouse, пароли MongoDB и API key HyperDX — передаются через этот единый secret.

   Чтобы переопределить значения secret:

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

   Для внешнего управления секретами (например, с помощью оператора для secrets) можно сослаться на уже существующий секрет Kubernetes:

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

   Управление API-ключами

   Подробные инструкции по настройке API-ключей, включая различные методы конфигурирования и процедуры перезапуска подов, см. в руководстве по настройке API-ключей.

​

Использование ClickHouse Cloud

Если вы используете ClickHouse Cloud, отключите встроенный экземпляр ClickHouse и укажите учетные данные 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"

Создайте секрет подключения отдельно:

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

Расширенные варианты внешней конфигурации

Для развертываний в production со конфигурацией на основе secret, внешними OTel collector или минимальной настройкой см. руководство по вариантам развертывания.

​

Примечания для продакшена

По умолчанию этот чарт устанавливает ClickHouse, MongoDB и OTel collector. Для продакшена рекомендуется управлять ClickHouse и OTel collector отдельно.

Чтобы отключить ClickHouse и OTel collector:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

Рекомендации для продакшена

Сведения о развертываниях в продакшене, включая конфигурацию высокой доступности, управление ресурсами, настройку входного шлюза/TLS и облачные конфигурации (GKE, EKS, AKS), см. здесь:

• Руководство по настройке - Входной шлюз, TLS и управление секретами
• Облачные развертывания - Облачные настройки и контрольный список для продакшена

​

Конфигурация задач

По умолчанию в конфигурации чарта предусмотрена одна задача в виде CronJob, которая проверяет, должны ли срабатывать оповещения. В v2.x конфигурация задач перенесена в hyperdx.tasks:

Параметр	Описание	По умолчанию
hyperdx.tasks.enabled	Включает/отключает cron-задачи в кластере. По умолчанию образ HyperDX выполняет cron-задачи в рамках основного процесса. Установите значение true, если хотите использовать отдельную cron-задачу в кластере.	false
hyperdx.tasks.checkAlerts.schedule	Расписание cron для задачи check-alerts	*/1 * * * *
hyperdx.tasks.checkAlerts.resources	Запросы и лимиты ресурсов для задачи check-alerts	См. values.yaml

​

Обновление чарта

Чтобы обновить чарт до новой версии:

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

Чтобы проверить доступные версии чарта:

helm search repo clickstack

Обновление с v1.x

Если вы обновляетесь с чарта inline-template версии v1.x, инструкции по миграции см. в руководстве по обновлению. Это несовместимое изменение — обновление на месте с помощью helm upgrade не поддерживается.

​

Удаление ClickStack

Удаляйте в обратном порядке:

helm uninstall my-clickstack            # Сначала удалить приложение и CR
helm uninstall clickstack-operators     # Удалить операторы и CRD

Примечание: PersistentVolumeClaims, созданные операторами MongoDB и ClickHouse, не удаляются при выполнении helm uninstall. Это сделано намеренно, чтобы предотвратить случайную потерю данных. Инструкции по очистке PVC см. здесь:

• в документации MongoDB Kubernetes Operator

​

Устранение неполадок

​

Проверка журналов

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

​

Отладка сбоя при установке

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

​

Проверка развертывания

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

Дополнительные ресурсы по устранению неполадок

Если у вас возникают проблемы с входным шлюзом, TLS или развертыванием в Cloud, см.:

• Устранение неполадок входного шлюза - Раздача ресурсов, перезапись путей, проблемы с браузером
• Развертывания в Cloud - Проблемы с GKE OpAMP и специфичные для Cloud проблемы

​

Выбор схемы: Map или JSON

По умолчанию ClickStack хранит атрибуты в столбцах Map(LowCardinality(String), String). Это рекомендуемая схема для рабочих нагрузок обсервабилити. В сочетании с сериализацией Map по бакетам и текстовыми индексами по ключам и значениям в Map она обеспечивает точечные lookup-операции без накладных расходов на приём для каждого ключа, характерных для динамических подстолбцов JSON.

Схема с типом JSON доступна в статусе бета для оценки на рабочих нагрузках с небольшим стабильным набором ключей атрибутов. Использовать её по умолчанию не рекомендуется. Полное сравнение и переменные окружения, необходимые для включения поддержки JSON, см. в разделе Map vs JSON type.

​

См. также

​

Руководства по развертыванию

• Варианты развертывания - внешний ClickHouse, OTel collector и минимальные развертывания
• Руководство по настройке - ключ API, секреты и настройка входного шлюза
• Развертывания в Cloud - конфигурации GKE, EKS, AKS и рекомендации для production
• Руководство по обновлению - переход с v1.x на v2.x
• Дополнительные манифесты - развертывание пользовательских объектов Kubernetes вместе с чартом

​

Документация v1.x

• Helm (v1.x) - руководство по развертыванию v1.x
• Конфигурация (v1.x) - конфигурация v1.x
• Варианты развертывания (v1.x) - варианты развертывания v1.x
• Развертывания в Cloud (v1.x) - конфигурации Cloud для v1.x

​

Дополнительные ресурсы

• Руководство по началу работы с ClickStack - Введение в ClickStack
• Репозиторий Helm-чартов ClickStack - Исходный код чартов и справочник по values
• Документация Kubernetes - Справочник по Kubernetes
• Документация Helm - Справочник по Helm