Helm (v1.x) - ClickHouse Documentation

Устарело — чарт v1.xНа этой странице описывается inline-template Helm-чарт v1.x, который поддерживается в режиме сопровождения и больше не будет получать новые возможности. Для новых развертываний используйте чарт v2.x. Чтобы перенести существующее развертывание v1.x, см. руководство по обновлению.

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

ClickHouse
HyperDX
коллектор OpenTelemetry (OTel)
MongoDB (для постоянного хранения состояния приложения)

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

Конфигурацию для конкретной среды через values.yaml
Ограничения ресурсов и масштабирование на уровне подов
Настройку TLS и входного шлюза
Управление секретами и настройку аутентификации

Подходит для

Пилотных проектов
Продакшн

Этапы развертывания

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

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

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

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

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

Установка ClickStack

Чтобы установить чарт 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. Подробнее см. в разделе “Using ClickHouse Cloud”.

Настройка values (необязательно)

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

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

Либо измените values.yaml. Чтобы получить значения по умолчанию:

helm show values clickstack/clickstack > values.yaml

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

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

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

Для работы с конфиденциальными данными, такими как ключ API или учетные данные базы данных, используйте секреты Kubernetes. Helm-чарты HyperDX содержат стандартные файлы секретов, которые можно изменить и применить в вашем кластере.

Использование предварительно настроенных секретов

Helm-чарт включает стандартный шаблон секрета, расположенный в charts/clickstack/templates/secrets.yaml. Этот файл служит базовой структурой для управления секретами.Если вам нужно применить секрет вручную, измените и примените предоставленный шаблон secrets.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

Примените секрет к кластеру:

kubectl apply -f secrets.yaml

Создание пользовательского секрета

При необходимости вы можете вручную создать пользовательский секрет Kubernetes:

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

Ссылка на секрет

Чтобы сослаться на секрет в values.yaml:

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

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

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

Если вы используете ClickHouse Cloud, отключите экземпляр ClickHouse, развернутый с помощью Helm-чарта, и укажите учетные данные Cloud:

# указать учётные данные ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # полный https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# как переопределить подключение по умолчанию
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}

Либо используйте файл 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
# или если уже установлен...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

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

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

По умолчанию этот чарт также устанавливает ClickHouse и OTel collector. Однако для продакшна рекомендуется управлять ClickHouse и OTel collector отдельно. Чтобы отключить ClickHouse и OTel collector, задайте следующие значения:

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

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

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

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

По умолчанию в конфигурации chart предусмотрена одна задача в виде cronjob, которая проверяет, должны ли срабатывать оповещения. Ниже приведены её параметры конфигурации:

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

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

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

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

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

helm search repo clickstack

Обновление до v2.xЕсли вы хотите перейти на чарт v2.x на базе субчартов, инструкции по миграции см. в руководстве по обновлению. Это несовместимое изменение — обновление helm upgrade на месте не поддерживается.

Удаление ClickStack

Чтобы удалить развертывание:

helm uninstall my-clickstack

Это удалит все ресурсы, связанные с этим релизом, но постоянные данные (если они есть) могут остаться.

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

Просмотр журналов

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.

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

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

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

Helm (v2.x) - руководство по развертыванию v2.x
Руководство по обновлению - переход с v1.x на v2.x

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

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

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

​Этапы развертывания

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

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

​Установка ClickStack

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

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

​Перейдите в интерфейс

​Настройка values (необязательно)

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

​Использование предварительно настроенных секретов

​Создание пользовательского секрета

​Ссылка на секрет

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

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

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

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

​Удаление ClickStack

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

​Просмотр журналов

​Диагностика сбоя при установке

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

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

​Сопутствующая документация

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

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

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

Подходит для

Этапы развертывания

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

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

Установка ClickStack

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

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

Перейдите в интерфейс

Настройка values (необязательно)

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

Использование предварительно настроенных секретов

Создание пользовательского секрета

Ссылка на секрет

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

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

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

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

Удаление ClickStack

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

Просмотр журналов

Диагностика сбоя при установке

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

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

Сопутствующая документация

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

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

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