> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Мониторинг Kubernetes
> Начало работы с ClickStack для мониторинга Kubernetes
export const Image = ({img, alt, size}) => {
return
;
};
Это руководство позволит вам собирать журналы и метрики из вашей системы Kubernetes и отправлять их в **ClickStack** для визуализации и анализа. В качестве демонстрационных данных при желании можно использовать форк официального демо OpenTelemetry от ClickStack.
## Предварительные требования
Для работы с этим руководством вам потребуется:
* **Кластер Kubernetes** (рекомендуется v1.20+) с как минимум 32 GiB оперативной памяти и 100 GB дискового пространства, доступными на одном узле для ClickHouse.
* **[Helm](https://helm.sh/)** v3+
* **`kubectl`**, настроенный для взаимодействия с вашим кластером
## Варианты развертывания
Вы можете воспользоваться этим руководством, выбрав один из следующих вариантов развертывания:
* **ClickStack с открытым исходным кодом**: разверните ClickStack целиком в своем кластере Kubernetes, включая:
* ClickHouse
* HyperDX
* MongoDB (используется для хранения состояния и конфигурации панели мониторинга)
* **Управляемый ClickStack**, где ClickHouse и интерфейс ClickStack (HyperDX) управляются в ClickHouse Cloud. Это избавляет от необходимости запускать ClickHouse или HyperDX внутри вашего кластера.
Чтобы имитировать трафик приложения, при желании можно развернуть форк приложения [**OpenTelemetry Demo Application**](https://github.com/ClickHouse/opentelemetry-demo), подготовленный ClickStack. Это позволяет генерировать телеметрические данные, включая журналы, метрики и трассировки. Если в вашем кластере уже запущены рабочие нагрузки, этот шаг можно пропустить и отслеживать существующие поды, узлы и контейнеры.
### Установите cert-manager (необязательно)
Если в вашей конфигурации нужны TLS-сертификаты, установите [cert-manager](https://cert-manager.io/) с помощью Helm:
```shell theme={null}
# Добавить репозиторий 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` (не развернут)
* [Пересылка тегов ресурсов](/ru/clickstack/integration-examples/kubernetes#forwarding-resouce-tags-to-pods) для корреляции журналов, метрик и трассировок через переменную среды `OTEL_RESOURCE_ATTRIBUTES`.
```shell theme={null}
## скачать демонстрационный манифест-файл 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`:
```shell theme={null}
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](/ru/clickstack/ingesting-data/sdks).
*Источник: [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
Дополнительные сведения о демо можно найти здесь:
* [документация OpenTelemetry](https://opentelemetry.io/docs/demo/)
* [форк, поддерживаемый ClickStack](https://github.com/ClickHouse/opentelemetry-demo)
### Добавьте репозиторий Helm-чарта ClickStack
Для развертывания ClickStack мы используем [официальный Helm-чарт](/ru/clickstack/deployment/helm).
Для этого необходимо добавить Helm-репозиторий HyperDX:
```shell theme={null}
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo update
```
### Развертывание ClickStack
После установки Helm-чарта вы можете развернуть ClickStack в своем кластере. Можно либо запустить все компоненты, включая ClickHouse и HyperDX, в своей среде Kubernetes, либо развернуть только collector и использовать Управляемый ClickStack для ClickHouse и интерфейса HyperDX.
Следующая команда устанавливает ClickStack в пространстве имен `otel-demo`. Helm-чарт развертывает:
* Экземпляр ClickHouse
* HyperDX
* Дистрибутив OTel collector от ClickStack
* MongoDB для хранения состояния приложения HyperDX
Возможно, вам потребуется скорректировать `storageClassName` в соответствии с конфигурацией вашего кластера Kubernetes.
Если вы не развертываете OTel demo, можете изменить этот параметр, указав подходящее пространство имен.
```shell theme={null}
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, задайте следующие значения:
```shell theme={null}
helm install myrelease --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
```
Если вы предпочитаете использовать Управляемый ClickStack, можно развернуть ClickStack и [отключить входящий в комплект ClickHouse](/ru/clickstack/deployment/helm#using-clickhouse-cloud).
Сейчас чарт всегда развертывает и HyperDX, и MongoDB. Хотя эти компоненты предоставляют альтернативный способ доступа, они не интегрированы с аутентификацией ClickHouse Cloud. В этой модели развертывания эти компоненты предназначены для администраторов, [предоставляя доступ к защищенному ключу ингестии](#retrieve-ingestion-api-key), необходимому для ингестии через развернутый OTel collector, но не должны быть доступны конечным пользователям.
```shell theme={null}
# укажите учетные данные ClickHouse Cloud
export CLICKHOUSE_URL= # полный URL https
export CLICKHOUSE_USER=
export 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 будет отсутствовать:
```shell theme={null}
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.
```shell theme={null}
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](http://localhost:8080), чтобы перейти в интерфейс HyperDX.
Создайте пользователя, указав имя пользователя и пароль, которые соответствуют требованиям сложности.
### Получение ключа API для приёма данных
Приём данных в OTel collector, развёрнутом коллектором ClickStack, защищён ключом API для приёма данных.
Перейдите в [`Team Settings`](http://localhost:8080/team) и скопируйте `Ingestion API Key` из раздела `API Keys`. Этот ключ API обеспечивает безопасную ингестию данных через OpenTelemetry Collector.
### Создание секрета Kubernetes с ключом API
Создайте новый секрет Kubernetes с ключом API для приёма данных и ConfigMap, содержащий адрес OTel collector, развернутого с помощью Helm-чарта ClickStack. Позднее другие компоненты будут использовать эти ресурсы, чтобы отправлять данные в OTel collector, развернутый с помощью Helm-чарта ClickStack:
```shell theme={null}
# создать секрет с ключом API для приёма данных
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_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 для приёма данных вступили в силу.
```shell theme={null}
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:
```shell theme={null}
# Добавить репозиторий 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 для централизованного анализа.
Сначала установите коллектор в виде развертывания:
```shell theme={null}
# скачать файл манифеста
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
```
```yaml theme={null}
# 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 в виде ДемонСета для сбора метрик и журналов на уровне узлов и подов:
```shell theme={null}
# скачать файл манифеста
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
```
```yaml theme={null}
# 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, просто войдите в свой сервис ClickHouse Cloud и выберите "ClickStack" в меню слева. Вы будете автоматически аутентифицированы, и создавать пользователя не потребуется.
Источники данных для журналов, метрик и трассировок будут созданы заранее.
Чтобы получить доступ к локально развернутому HyperDX, выполните локально команду проброса порта и откройте HyperDX по адресу [http://localhost:8080](http://localhost:8080).
```shell theme={null}
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. Например:
```shell theme={null}
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](http://localhost:8080/kubernetes).
Каждая из вкладок — Pods, Nodes и Namespaces — должна быть заполнена данными.