Мониторинг Kubernetes

Это руководство позволит вам собирать журналы и метрики из вашей системы Kubernetes и отправлять их в ClickStack для визуализации и анализа. В качестве демонстрационных данных при желании можно использовать форк официального демо OpenTelemetry от ClickStack.

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

Для работы с этим руководством вам потребуется:

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

Варианты развертывания

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

ClickStack с открытым исходным кодом: разверните ClickStack целиком в своем кластере Kubernetes, включая:
- ClickHouse
- HyperDX
- MongoDB (используется для хранения состояния и конфигурации панели мониторинга)
Управляемый ClickStack, где ClickHouse и интерфейс ClickStack (HyperDX) управляются в ClickHouse Cloud. Это избавляет от необходимости запускать ClickHouse или HyperDX внутри вашего кластера.

Чтобы имитировать трафик приложения, при желании можно развернуть форк приложения OpenTelemetry Demo Application, подготовленный ClickStack. Это позволяет генерировать телеметрические данные, включая журналы, метрики и трассировки. Если в вашем кластере уже запущены рабочие нагрузки, этот шаг можно пропустить и отслеживать существующие поды, узлы и контейнеры.

Установите cert-manager (необязательно)

Если в вашей конфигурации нужны TLS-сертификаты, установите cert-manager с помощью Helm:

# Добавить репозиторий Cert Manager 

helm repo add jetstack https://charts.jetstack.io 

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set startupapicheck.timeout=5m --set installCRDs=true --set global.leaderElection.namespace=cert-manager

Разверните OpenTelemetry Demo (необязательно)

Этот шаг необязателен и предназначен для случаев, когда у вас нет существующих подов для мониторинга. Пользователи, у которых в среде Kubernetes уже развернуты сервисы, могут пропустить его, однако это демо включает инструментированные микросервисы, которые генерируют данные трассировок и воспроизведения сеанса, что позволяет изучить все возможности ClickStack.Ниже разворачивается форк ClickStack стека приложений OpenTelemetry Demo в кластере Kubernetes, адаптированный для тестирования обсервабилити и демонстрации инструментирования. Он включает бэкенд-микросервисы, генераторы нагрузки, конвейеры телеметрии, вспомогательную инфраструктуру (например, Kafka и Redis), а также интеграции SDK с ClickStack.Все сервисы развертываются в пространстве имен otel-demo. Каждое развертывание включает:

Автоматическое инструментирование с OTel и ClickStack SDKS для трассировок, метрик и журналов.
Все сервисы отправляют данные своего инструментирования в коллектор OpenTelemetry my-hyperdx-hdx-oss-v2-otel-collector (не развернут)
Пересылка тегов ресурсов для корреляции журналов, метрик и трассировок через переменную среды OTEL_RESOURCE_ATTRIBUTES.

## скачать демонстрационный манифест-файл Kubernetes
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# альтернатива wget
# wget https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
kubectl apply --namespace otel-demo -f opentelemetry-demo.yaml

После развертывания демо убедитесь, что все поды успешно созданы и находятся в состоянии Running:

kubectl get pods -n=otel-demo

NAME                                 READY   STATUS    RESTARTS   AGE
accounting-fd44f4996-fcl4k           1/1     Running   0          13m
ad-769f968468-qq8mw                  1/1     Running   0          13m
artillery-loadgen-7bc4bdf47d-5sb96   1/1     Running   0          13m
cart-5b4c98bd8-xm7m2                 1/1     Running   0          13m
checkout-784f69b785-cnlpp            1/1     Running   0          13m
currency-fd7775b9c-rf6cr             1/1     Running   0          13m
email-5c54598f99-2td8s               1/1     Running   0          13m
flagd-5466775df7-zjb4x               2/2     Running   0          13m
fraud-detection-5769fdf75f-cjvgh     1/1     Running   0          13m
frontend-6dcb696646-fmcdz            1/1     Running   0          13m
frontend-proxy-7b8f6cd957-s25qj      1/1     Running   0          13m
image-provider-5fdb455756-fs4xv      1/1     Running   0          13m
kafka-7b6666866d-xfzn6               1/1     Running   0          13m
load-generator-57cbb7dfc9-ncxcf      1/1     Running   0          13m
payment-6d96f9bcbd-j8tj6             1/1     Running   0          13m
product-catalog-7fb77f9c78-49bhj     1/1     Running   0          13m
quote-576c557cdf-qn6pr               1/1     Running   0          13m
recommendation-546cc68fdf-8x5mm      1/1     Running   0          13m
shipping-7fc69f7fd7-zxrx6            1/1     Running   0          13m
valkey-cart-5f7b667bb7-gl5v4         1/1     Running   0          13m

Архитектура демо

Демо состоит из микросервисов, написанных на разных языках программирования, которые взаимодействуют друг с другом по gRPC и HTTP, а также генератора нагрузки, использующего Locust для имитации пользовательского трафика. Оригинальный исходный код этого демо был изменён, чтобы использовать инструментирование ClickStack.Источник: https://opentelemetry.io/docs/demo/architecture/Дополнительные сведения о демо можно найти здесь:

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

Для развертывания ClickStack мы используем официальный Helm-чарт.Для этого необходимо добавить Helm-репозиторий HyperDX:

helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo update

Развертывание ClickStack

После установки Helm-чарта вы можете развернуть ClickStack в своем кластере. Можно либо запустить все компоненты, включая ClickHouse и HyperDX, в своей среде Kubernetes, либо развернуть только collector и использовать Управляемый ClickStack для ClickHouse и интерфейса HyperDX.

ClickStack с открытым исходным кодом (самоуправляемый)

Следующая команда устанавливает ClickStack в пространстве имен otel-demo. Helm-чарт развертывает:

Экземпляр ClickHouse
HyperDX
Дистрибутив OTel collector от ClickStack
MongoDB для хранения состояния приложения HyperDX

Возможно, вам потребуется скорректировать storageClassName в соответствии с конфигурацией вашего кластера Kubernetes.

Если вы не развертываете OTel demo, можете изменить этот параметр, указав подходящее пространство имен.

helm install my-hyperdx hyperdx/hdx-oss-v2   --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo

ClickStack в productionЭтот чарт также устанавливает ClickHouse и OTel collector. Для production рекомендуется использовать операторы clickhouse и OTel collector и/или Управляемый ClickStack.Чтобы отключить clickhouse и OTel collector, задайте следующие значения:

helm install myrelease <chart-name-or-path> --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false

Управляемый ClickStack

Если вы предпочитаете использовать Управляемый ClickStack, можно развернуть ClickStack и отключить входящий в комплект ClickHouse.

Сейчас чарт всегда развертывает и HyperDX, и MongoDB. Хотя эти компоненты предоставляют альтернативный способ доступа, они не интегрированы с аутентификацией ClickHouse Cloud. В этой модели развертывания эти компоненты предназначены для администраторов, предоставляя доступ к защищенному ключу ингестии, необходимому для ингестии через развернутый OTel collector, но не должны быть доступны конечным пользователям.

# укажите учетные данные ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # полный URL https
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

helm install my-hyperdx hyperdx/hdx-oss-v2  --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} --set clickhouse.config.users.otelUserName=${CLICKHOUSE_USER} --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} --set global.storageClassName="standard-rwo" -n otel-demo

Чтобы проверить статус развертывания, выполните следующую команду и убедитесь, что все компоненты находятся в состоянии Running. Обратите внимание: если вы используете Управляемый ClickStack, ClickHouse будет отсутствовать:

kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2" -n otel-demo

NAME                                                    READY   STATUS    RESTARTS   AGE
my-hyperdx-hdx-oss-v2-app-78876d79bb-565tb              1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-clickhouse-57975fcd6-ggnz2        1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-mongodb-984845f96-czb6m           1/1     Running   0          14m
my-hyperdx-hdx-oss-v2-otel-collector-64cf698f5c-8s7qj   1/1     Running   0          14m

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

Даже при использовании Управляемого ClickStack локальный экземпляр HyperDX, развернутый в кластере Kubernetes, всё равно необходим. Он предоставляет ключ ингестии, которым управляет сервер OpAMP, входящий в состав HyperDX, и обеспечивает защищённую ингестию через развернутый OTel collector — эта возможность в настоящее время недоступна в Управляемом ClickStack.

В целях безопасности сервис использует ClusterIP и по умолчанию не доступен извне.Чтобы открыть интерфейс HyperDX, настройте проброс порта с 3000 на локальный порт 8080.

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

Откройте http://localhost:8080, чтобы перейти в интерфейс HyperDX.Создайте пользователя, указав имя пользователя и пароль, которые соответствуют требованиям сложности.

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

Приём данных в OTel collector, развёрнутом коллектором ClickStack, защищён ключом API для приёма данных.Перейдите в Team Settings и скопируйте Ingestion API Key из раздела API Keys. Этот ключ API обеспечивает безопасную ингестию данных через OpenTelemetry Collector.

Создание секрета Kubernetes с ключом API

Создайте новый секрет Kubernetes с ключом API для приёма данных и ConfigMap, содержащий адрес OTel collector, развернутого с помощью Helm-чарта ClickStack. Позднее другие компоненты будут использовать эти ресурсы, чтобы отправлять данные в OTel collector, развернутый с помощью Helm-чарта ClickStack:

# создать секрет с ключом API для приёма данных
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# создать ConfigMap, указывающий на развёрнутый выше OTel collector ClickStack
kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318

Перезапустите поды демо-приложения OpenTelemetry, чтобы изменения ключа API для приёма данных вступили в силу.

kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demo

Данные трассировок и логов из демо-сервисов теперь должны начать поступать в HyperDX.

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

Чтобы собирать метрики Kubernetes, мы развернём стандартный OTel collector и настроим его на безопасную отправку данных в наш коллектор ClickStack с помощью указанного выше ключа API для приёма данных.Для этого нужно установить Helm-репозиторий OpenTelemetry:

# Добавить репозиторий OTel Helm
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts 

Развёртывание компонентов коллектора Kubernetes

Для сбора журналов и метрик как с самого кластера, так и с каждого узла потребуется развернуть два отдельных коллектора OpenTelemetry, каждый со своим манифестом. Два предоставленных манифеста — k8s_deployment.yaml и k8s_daemonset.yaml — работают совместно и обеспечивают полный сбор телеметрических данных из вашего кластера Kubernetes.

k8s_deployment.yaml разворачивает единственный экземпляр OpenTelemetry Collector, отвечающий за сбор событий и метаданных всего кластера. Он собирает события Kubernetes, метрики кластера и обогащает телеметрические данные метками и аннотациями подов. Этот коллектор работает как автономное Развертывание с одной репликой, чтобы избежать дублирования данных.
k8s_daemonset.yaml разворачивает коллектор в виде ДемонСет, который запускается на каждом узле кластера. Он собирает метрики на уровне узла и пода, а также журналы контейнеров, используя такие компоненты, как kubeletstats, hostmetrics и процессоры Kubernetes Attribute Processor. Эти коллекторы обогащают журналы метаданными и отправляют их в HyperDX с помощью экспортера OTLP.

В совокупности эти манифесты обеспечивают полноценную обсервабилити всего стека в рамках кластера — от инфраструктуры до телеметрии на уровне приложений — и отправляют обогащённые данные в ClickStack для централизованного анализа.Сначала установите коллектор в виде развертывания:

# скачать файл манифеста
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# установить Helm-чарт
helm install --namespace otel-demo k8s-otel-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml

k8s_deployment.yaml

# k8s_deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Нужен только один такой коллектор — большее количество приведёт к дублированию данных
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # При включении процессор извлечёт все метки связанного пода и добавит их как атрибуты ресурса.
    # Точное имя метки будет использоваться в качестве ключа.
    extractAllPodLabels: true
    # При включении процессор извлечёт все аннотации связанного пода и добавит их как атрибуты ресурса.
    # Точное имя аннотации будет использоваться в качестве ключа.
    extractAllPodAnnotations: true
  # Настраивает коллектор для сбора событий Kubernetes.
  # Добавляет k8sobject receiver в конвейер журналов и по умолчанию собирает события Kubernetes.
  # Подробнее: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Настраивает k8s_cluster receiver для сбора метрик уровня кластера.
  # Добавляет k8s_cluster receiver в конвейер метрик и добавляет необходимые правила в ClusterRole.
  # Подробнее: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
  clusterMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT
 
config:
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Затем разверните collector в виде ДемонСета для сбора метрик и журналов на уровне узлов и подов:

# скачать файл манифеста
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# установить Helm-чарт
helm install --namespace otel-demo k8s-otel-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

k8s_daemonset.yaml

# k8s_daemonset.yaml
mode: daemonset

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
   
# Требуется для использования метрик утилизации cpu/memory в kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Настраивает Kubernetes Processor для добавления метаданных Kubernetes.
  # Добавляет процессор k8sattributes во все конвейеры и добавляет необходимые правила в РольКластера.
  # Подробнее: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # При включении процессор извлечёт все метки связанного пода и добавит их как атрибуты ресурса.
    # Точное имя метки будет использоваться в качестве ключа.
    extractAllPodLabels: true
    # При включении процессор извлечёт все аннотации связанного пода и добавит их как атрибуты ресурса.
    # Точное имя аннотации будет использоваться в качестве ключа.
    extractAllPodAnnotations: true
  # Настраивает коллектор для сбора метрик узла, пода и контейнера с API-сервера Кубелета.
  # Добавляет приёмник kubeletstats в конвейер метрик и добавляет необходимые правила в РольКластера.
  # Подробнее: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
  kubeletMetrics:
    enabled: true

extraEnvs:
  - name: HYPERDX_API_KEY
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: HYPERDX_API_KEY
        optional: true
  - name: YOUR_OTEL_COLLECTOR_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: otel-config-vars
        key: YOUR_OTEL_COLLECTOR_ENDPOINT

config:
  receivers:
    # Настраивает дополнительные метрики Кубелета
    kubeletstats:
      collection_interval: 20s
      auth_type: 'serviceAccount'
      endpoint: '${env:K8S_NODE_NAME}:10250'
      insecure_skip_verify: true
      metrics:
        k8s.pod.cpu_limit_utilization:
          enabled: true
        k8s.pod.cpu_request_utilization:
          enabled: true
        k8s.pod.memory_limit_utilization:
          enabled: true
        k8s.pod.memory_request_utilization:
          enabled: true
        k8s.pod.uptime:
          enabled: true
        k8s.node.uptime:
          enabled: true
        k8s.container.cpu_limit_utilization:
          enabled: true
        k8s.container.cpu_request_utilization:
          enabled: true
        k8s.container.memory_limit_utilization:
          enabled: true
        k8s.container.memory_request_utilization:
          enabled: true
        container.uptime:
          enabled: true
 
  exporters:
    otlphttp:
      endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
      compression: gzip
      headers:
        authorization: "${env:HYPERDX_API_KEY}"
 
  service:
    pipelines:
      logs:
        exporters:
          - otlphttp
      metrics:
        exporters:
          - otlphttp

Просмотр данных Kubernetes в HyperDX

Перейдите в интерфейс HyperDX — либо в экземпляр, развернутый в Kubernetes, либо через Управляемый ClickStack.

Управляемый ClickStack

Если вы используете Управляемый ClickStack, просто войдите в свой сервис ClickHouse Cloud и выберите “ClickStack” в меню слева. Вы будете автоматически аутентифицированы, и создавать пользователя не потребуется.Источники данных для журналов, метрик и трассировок будут созданы заранее.

ClickStack с открытым исходным кодом

Чтобы получить доступ к локально развернутому HyperDX, выполните локально команду проброса порта и откройте HyperDX по адресу http://localhost:8080.

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

ClickStack в productionЕсли вы не используете Управляемый ClickStack, для production мы рекомендуем использовать входной шлюз с TLS. Например:

helm upgrade my-hyperdx hyperdx/hdx-oss-v2 \
--set hyperdx.ingress.enabled=true \
--set hyperdx.ingress.host=your-domain.com \
--set hyperdx.ingress.tls.enabled=true

Чтобы просматривать данные Kubernetes, перейдите на специальную панель мониторинга по адресу /kubernetes, например: http://localhost:8080/kubernetes.Каждая из вкладок — Pods, Nodes и Namespaces — должна быть заполнена данными.

Возможности

Руководства

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

Варианты развертывания

Установите cert-manager (необязательно)

Разверните OpenTelemetry Demo (необязательно)

Архитектура демо

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

Развертывание ClickStack

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

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

Создание секрета Kubernetes с ключом API

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

Развёртывание компонентов коллектора Kubernetes

Просмотр данных Kubernetes в HyperDX

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

​Варианты развертывания

​Установите cert-manager (необязательно)

​Разверните OpenTelemetry Demo (необязательно)

​Архитектура демо

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

​Развертывание ClickStack

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

​Получение ключа API для приёма данных

​Создание секрета Kubernetes с ключом API

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

​Развёртывание компонентов коллектора Kubernetes

​Просмотр данных Kubernetes в HyperDX

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

Варианты развертывания

Установите cert-manager (необязательно)

Разверните OpenTelemetry Demo (необязательно)

Архитектура демо

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

Развертывание ClickStack

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

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

Создание секрета Kubernetes с ключом API

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

Развёртывание компонентов коллектора Kubernetes

Просмотр данных Kubernetes в HyperDX