Перейти к основному содержимому
Перейти к основному содержимому

Helm

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

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

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

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

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

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

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

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

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

  • Пилотных проектов
  • Продуктивной среды

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


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

  • 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

Подождите, пока поды оператора будут готовы, прежде чем продолжить:

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 и настроить его. Если вы развёртываете систему в production, вместо этого следует открыть доступ к сервису через входной шлюз или балансировщик нагрузки, чтобы обеспечить корректный сетевой доступ, терминацию 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.

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

Интерфейс 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 использует единый секрет (clickstack-secret), который заполняется из hyperdx.secrets в файле values. Все конфиденциальные переменные окружения — включая пароли ClickHouse, пароли MongoDB и API-ключ HyperDX — передаются через этот секрет.

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

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

Для внешнего управления секретами (например, с помощью оператора для секретов) можно сослаться на уже существующий секрет 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
Расширенные внешние конфигурации

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

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

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

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

clickhouse:
  enabled: false

otel-collector:
  enabled: false
Лучшие практики для production-среды

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

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

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

ПараметрОписаниеПо умолчанию
hyperdx.tasks.enabledВключает или отключает cron-задачи в кластере. По умолчанию образ HyperDX выполняет cron-задачи в рамках процесса. Установите true, если хотите использовать отдельную cron-задачу в кластере.false
hyperdx.tasks.checkAlerts.scheduleCron-расписание для задачи 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

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

Удаление ClickStack​

Выполните удаление в обратном порядке:

helm uninstall my-clickstack            # Remove app + CRs first
helm uninstall clickstack-operators     # Remove operators + CRDs

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

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

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

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, см.:

Поддержка типа JSON​

Beta feature. Learn more.
Beta Feature - not production ready

Поддержка типа JSON в ClickStack находится в статусе бета-версии. Хотя сам тип JSON готов к промышленной эксплуатации в ClickHouse 25.3+, его интеграция в ClickStack всё ещё активно разрабатывается и может иметь ограничения, изменяться в будущем или содержать ошибки.

Поддержка типа JSON в ClickStack доступна в статусе бета-версии, начиная с версии 2.0.4.

О преимуществах этого типа см. раздел Преимущества типа JSON.

Чтобы включить поддержку типа JSON, вам необходимо задать следующие переменные окружения:

  • OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' — включает поддержку в OTel collector, гарантируя, что схемы создаются с использованием типа JSON.
  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true (только ClickStack Open Source) — включает поддержку в приложении ClickStack UI, позволяя выполнять запросы к данным JSON.

Эти переменные среды можно задать через hyperdx.config в файле values.yaml:

hyperdx:
  config:
    BETA_CH_OTEL_JSON_SCHEMA_ENABLED: "true"
    OTEL_AGENT_FEATURE_GATE_ARG: "--feature-gates=clickhouse.json"

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

helm install my-clickstack clickstack/clickstack \
  --set "hyperdx.config.BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true" \
  --set "hyperdx.config.OTEL_AGENT_FEATURE_GATE_ARG=--feature-gates=clickhouse.json"

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

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

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