Мониторинг Kubernetes

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

1. ​

   Установите 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
   
2. ​

   Разверните 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/

   Дополнительные сведения о демо можно найти здесь:

   • документация OpenTelemetry
   • форк, поддерживаемый ClickStack
3. ​

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

   Для развертывания ClickStack мы используем официальный Helm-чарт.

   Для этого необходимо добавить Helm-репозиторий HyperDX:

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

   Развертывание 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
   
5. ​

   Откройте интерфейс 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.

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

6. ​

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

   Приём данных в OTel collector, развёрнутом коллектором ClickStack, защищён ключом API для приёма данных.

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

7. ​

   Создание секрета 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.

8. ​

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

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

   Для этого нужно установить Helm-репозиторий OpenTelemetry:

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

   Развёртывание компонентов коллектора 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
   
10. ​

    Просмотр данных 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 — должна быть заполнена данными.