Helm (v1.x)

Развертывание ClickStack с помощью inline-template Helm-чарта v1.x

Устарело — чарт 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 и входного шлюза
• Управление секретами и настройку аутентификации

​

Подходит для

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

​

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

1. ​

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

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

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

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

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

   Установка ClickStack

   Чтобы установить чарт ClickStack со значениями по умолчанию:

   helm install my-clickstack clickstack/clickstack
   
4. ​

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

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

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

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

5. ​

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

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

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

   Настройка входного шлюза для продакшна

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

6. ​

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

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

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

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

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

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

7. ​

   Настройка 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
   
8. ​

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

   Для работы с конфиденциальными данными, такими как ключ 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