Helm - ClickHouse Documentation

Версия 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 и т. д.) вместе с чартом

Подходит для

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

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

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

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

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

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

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

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

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

helm install clickstack-operators clickstack/clickstack-operators

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

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

Установите ClickStack

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

helm install my-clickstack clickstack/clickstack

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

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

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

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

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

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

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

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

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

Перейдите по адресу http://localhost:8080, чтобы открыть интерфейс HyperDX.Создайте пользователя, указав имя пользователя и пароль, соответствующие требованиям.После нажатия Create для экземпляра ClickHouse, развернутого с помощью Helm-чарта, будут созданы источники данных.

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

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

Вы можете переопределить параметры с помощью флагов --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

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

Чарт 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

​Подходит для

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

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

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

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

​Установите ClickStack

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

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

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

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

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

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

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

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

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

​Удаление ClickStack

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

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

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

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

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

​См. также

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

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

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

Подходит для

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

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

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

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

Установите ClickStack

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

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

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

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

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

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

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

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

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

Удаление ClickStack

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

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

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

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

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

См. также

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

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

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