Конфигурация Helm (v1.x)

В этом руководстве описаны параметры конфигурации для Helm-развертываний ClickStack. Базовую установку см. в основном руководстве по Helm-развертыванию.

После успешного развертывания ClickStack настройте ключ API, чтобы включить сбор телеметрических данных:

1. Откройте свой экземпляр HyperDX через настроенный входной шлюз или конечную точку сервиса
2. Войдите в панель мониторинга HyperDX и перейдите в настройки команды, чтобы создать или получить ключ API
3. Обновите свое развертывание, добавив ключ API одним из следующих способов:

Добавьте API-ключ в файл values.yaml:

hyperdx:
  apiKey: "your-api-key-here"

Затем обновите развертывание:

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

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

После обновления API-ключа перезапустите поды, чтобы они подхватили новую конфигурацию:

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector

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

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

Если вам нужно применить секрет вручную, измените и примените предоставленный шаблон 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

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

Чтобы открыть доступ к интерфейсу HyperDX и API по доменному имени, включите входной шлюз в values.yaml.

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Должен совпадать с хостом входного шлюза
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"

Чтобы защитить развертывание с помощью HTTPS:

1. Создайте TLS-секрет с вашим сертификатом и ключом:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. Включите TLS в конфигурации входного шлюза:

hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

Для справки: ниже показано, как выглядит сгенерированный ресурс входного шлюза:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

Настройка пути и rewrite:

• Для Next.js и других SPA всегда используйте путь с регулярным выражением и аннотацию rewrite, как показано выше
• Не используйте просто path: / без rewrite, так как это нарушит раздачу статических ресурсов

Несоответствие frontendUrl и ingress.host:

• Если они не совпадают, возможны проблемы с cookie, перенаправлениями и загрузкой ресурсов

Ошибки в настройке TLS:

• Убедитесь, что ваш TLS-секрет действителен и правильно указан во входном шлюзе
• Браузеры могут блокировать небезопасный контент, если вы открываете приложение по HTTP при включённом TLS

Версия контроллера входного шлюза:

• Некоторые возможности (например, пути с регулярными выражениями и rewrites) требуют свежих версий контроллера входного шлюза nginx
• Проверьте версию с помощью:

kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

Если вам нужно открыть доступ к конечным точкам OTel collector (для трассировок, метрик и журналов) через входной шлюз, используйте конфигурацию additionalIngresses. Это полезно, если вы отправляете данные телеметрии извне кластера или хотите использовать для collector собственный домен.

hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls

• Это создаёт отдельный ресурс входного шлюза для конечных точек OTel collector
• Вы можете использовать другой домен, настроить параметры TLS и добавить собственные аннотации
• Правило пути с регулярным выражением позволяет направлять все сигналы OTLP (трассировки, метрики, журналы) через одно правило

Проверьте ресурс входного шлюза:

kubectl get ingress -A
kubectl describe ingress <ingress-name>

Проверьте журналы контроллера входного шлюза:

kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx

Проверьте URL-адреса ресурсов:

С помощью curl убедитесь, что статические ресурсы отдаются как JS, а не как HTML:

curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Должен вернуть Content-Type: application/javascript

Инструменты разработчика в браузере:

• Проверьте вкладку Network на наличие ответов 404 и ресурсов, которые возвращают HTML вместо JS
• Поищите в консоли ошибки вроде Unexpected token < (это означает, что вместо JS вернулся HTML)

Проверьте перезапись путей:

• Убедитесь, что входной шлюз не отбрасывает части путей к ресурсам и не переписывает их некорректно

Очистите кэш браузера и CDN:

• После внесения изменений очистите кэш браузера и любой кэш CDN/proxy, чтобы не использовать устаревшие ресурсы

Вы можете изменить параметры с помощью флагов --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

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

Примените пользовательские значения:

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

• Варианты развертывания (v1.x) - Внешние системы и минимальные варианты развертывания
• Развертывания в Cloud (v1.x) - Конфигурации для GKE, EKS и AKS
• Основное руководство по Helm (v1.x) - Базовая установка
• Конфигурация Helm (v2.x) - Руководство по настройке v2.x
• Руководство по обновлению - Переход с v1.x на v2.x