Helm (v1.x)

Устарело — чарт v1.x

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

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

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

ClickHouse
HyperDX
OTel collector
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 и настроить его. При развёртывании в 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.

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

После нажатия 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

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

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:

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
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
# or if installed...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

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

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

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

По умолчанию этот чарт также устанавливает 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 и управление секретами
Развертывания в Cloud - Настройки для Cloud и чек-лист для продакшена

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

По умолчанию в чарте настроена одна задача в виде 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

Если вы хотите перейти на chart v2.x на основе subchart, см. руководство по обновлению, где приведены инструкции по миграции. Это несовместимое изменение — обновление 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

Поддержка типа 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.

Вы можете задать эти переменные окружения либо через параметры, либо через 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"

Руководства по развертыванию 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 - Исходный код чартов и справочник по значениям
Документация Kubernetes - Справочник по Kubernetes
Документация Helm - Справочник по Helm

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

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

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

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

Установка ClickStack​

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

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

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

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

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

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

Создание собственного секрета​

Указание секрета​

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

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

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

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

Удаление ClickStack​

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

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

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

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

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

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

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

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

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