Helm

Миграция чарта

Если вы в данный момент используете чарт hdx-oss-v2, перейдите на чарт clickstack. Чарт hdx-oss-v2 находится в режиме сопровождения и больше не будет получать новые функции. Весь новый функционал разрабатывается для чарта clickstack, который обеспечивает ту же функциональность с более понятными названиями и улучшённой структурой.

Helm-чарт для HyperDX можно найти здесь; это рекомендованный способ продакшен-развертываний.

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

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

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

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

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

Подходит для

Пилотных проектов (proof of concept)
Продакшена (production)

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

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

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

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

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

helm repo add clickstack https://hyperdxio.github.io/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

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

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

Переход к UI

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

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

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

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

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

Пример использования альтернативного экземпляра ClickHouse см. в разделе "Создание подключения к ClickHouse Cloud".

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

Настройки можно изменить с помощью флагов --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-чарта, и укажите учетные данные ClickHouse Cloud:

# укажите учетные данные ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # полный https-адрес
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": "Внешний ClickHouse",
        "host": "http://ваш-clickhouse-сервер:8123",
        "port": 8123,
        "username": "ваше-имя-пользователя",
        "password": "ваш-пароль"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# или, если уже установлен...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

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

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

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

По умолчанию этот chart также устанавливает 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 и облачные конфигурации (GKE, EKS, AKS), см.:

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

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

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

Parameter	Description	Default
`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

Удаление 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 или диагностикой проблем облачного развертывания, см.:

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

JSON type support

Beta feature. Learn more.

Beta Feature - not production ready

JSON type support in ClickStack is a beta feature. While the JSON type itself is production-ready in ClickHouse 25.3+, its integration within ClickStack is still under active development and may have limitations, change in the future, or contain bugs.

ClickStack has beta support for the JSON type from version 2.0.4.

For the benefits of this type see Benefits of the JSON type.

In order to enable support for the JSON type users must set the following environment variables:

OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - enables support in the OTel collector, ensuring schemas are created using the JSON type.
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - enables support in the HyperDX application, allowing JSON data to be queried.

Пользователи могут задать эти переменные окружения либо через параметры, либо в файле values.yaml, например:

values.yaml

hyperdx:
  ...
  env:
    - name: BETA_CH_OTEL_JSON_SCHEMA_ENABLED
      value: "true"

otel:
  ...
  env:
    - name: OTEL_AGENT_FEATURE_GATE_ARG
      value: "--feature-gates=clickhouse.json"

или с помощью --set:

helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.env[0].name=BETA_CH_OTEL_JSON_SCHEMA_ENABLED" \
  --set "hyperdx.env[0].value=true" \
  --set "otel.env[0].name=OTEL_AGENT_FEATURE_GATE_ARG" \
  --set "otel.env[0].value=--feature-gates=clickhouse.json"

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

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

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

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

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

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

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

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

Установка ClickStack​

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

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

Переход к UI​

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

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

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

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

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

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

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

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

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

Удаление ClickStack​

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

Проверка логов​

Устранение неполадок при неудачной установке​

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

JSON type support​

См. также​

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

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