Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Мониторинг 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:

# Add Cert manager repo 

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.
## download demo Kubernetes manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# wget alternative
# 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

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

helm install my-hyperdx hyperdx/hdx-oss-v2   --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo
Управляемый ClickStack

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

# укажите учетные данные 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

В целях безопасности сервис использует 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.

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

Интерфейс HyperDX

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

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

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

Копирование ключа API

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

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

# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# create a ConfigMap pointing to the ClickStack OTel collector deployed above
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.

Данные HyperDX в Kubernetes

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

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

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

# Add Otel Helm repo
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 для централизованного анализа.

Сначала установите коллектор в виде развертывания:

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# install the helm chart
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
 
# We only want one of these collectors - any more and we'd produce duplicate data
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect Kubernetes events.
  # Adds the k8sobject receiver to the logs pipeline and collects Kubernetes events by default.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configures the Kubernetes Cluster Receiver to collect cluster-level metrics.
  # Adds the k8s_cluster receiver to the metrics pipeline and adds the necessary rules to ClusteRole.
  # More Info: 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 в виде ДемонСета для сбора метрик и журналов на уровне узлов и подов:

# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# install the helm chart
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
   
# Required to use the kubeletstats cpu/memory utilization metrics
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configures the Kubernetes Processor to add Kubernetes metadata.
  # Adds the k8sattributes processor to all the pipelines and adds the necessary rules to ClusterRole.
  # More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
    # The label's exact name will be the key.
    extractAllPodLabels: true
    # When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
    # The annotation's exact name will be the key.
    extractAllPodAnnotations: true
  # Configures the collector to collect node, pod, and container metrics from the API server on a kubelet..
  # Adds the kubeletstats receiver to the metrics pipeline and adds the necessary rules to ClusterRole.
  # More Info: 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:
    # Configures additional kubelet metrics
    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

Чтобы просматривать данные Kubernetes, перейдите на специальную панель мониторинга по адресу /kubernetes, например: http://localhost:8080/kubernetes.

Каждая из вкладок — Pods, Nodes и Namespaces — должна быть заполнена данными.

ClickHouse в Kubernetes
Navigation