Стадия жизненного цикла модуля: Общедоступная версия
У модуля есть требования для установки
Триггеры
Триггеры (alerting rules) определяют условия создания алертов при отклонении значений метрик от ожидаемых порогов.
Триггеры описываются в группах правил и задаются как элементы массива spec.rules.
Если у правила указано поле alert, оно считается триггером и используется для создания алертов.
Виды групп правил с триггерами
Поддерживаются три типа групп правил, в которых могут быть определены триггеры:
| Тип группы правил | Область видимости | У кого есть доступ |
|---|---|---|
| Системные группы правил (ClusterObservabilityMetricsRulesGroup) | Уровень кластера | Администраторы DKP |
| Проектные группы правил (ObservabilityMetricsRulesGroup) | Уровень проекта (неймспейса) | Пользователи соответствующего проекта |
| Общедоступные (propagated) группы правил (ClusterObservabilityPropagatedMetricsRulesGroup) | Создаются на уровне кластера и автоматически доступны во всех проектах | Пользователи всех проектов |
Описание типов групп правил:
-
Системные группы правил (ClusterObservabilityMetricsRulesGroup) — используются для описания триггеров уровня платформы и компонентов кластера. Создаются и управляются администраторами DKP.
-
Проектные группы правил (ObservabilityMetricsRulesGroup) — используются для описания триггеров, относящихся к конкретному проекту (неймспейсу). Пользователи проекта могут создавать и редактировать их в рамках настроенных прав доступа.
-
Общедоступные (propagated) группы правил (ClusterObservabilityPropagatedMetricsRulesGroup) — создаются на уровне кластера и автоматически становятся доступны во всех проектах.
Дополнительные лейблы алертов, поставляемых с DKP
Модуль observability позволяет добавлять дополнительные лейблы к триггерам алертов, поставляемых с DKP.
Для этого используется ресурс ClusterObservabilityAlertAdditionalLabels.
Дополнительные лейблы применяются только к алертам, созданным с помощью ресурсов ClusterObservabilityMetricsRulesGroup и ClusterObservabilityPropagatedMetricsRulesGroup с лейблом heritage: deckhouse.
Чтобы добавить лейблы к пользовательским алертам, создаваемым с помощью ресурсов ObservabilityMetricsRulesGroup и ClusterObservabilityMetricsRulesGroup, используйте поле spec.rules.labels.
Примеры конфигурации:
-
Добавление лейбла ко всем алертам кластера:
apiVersion: observability.deckhouse.io/v1alpha1 kind: ClusterObservabilityAlertAdditionalLabels metadata: name: all-alerts spec: alertSelector: matchExpressions: - key: alertname operator: Exists additionalLabels: example-label-name: example-label-value -
Добавление лейбла
severity=Infoдля алертов сseverity_level7,8,9:apiVersion: observability.deckhouse.io/v1alpha1 kind: ClusterObservabilityAlertAdditionalLabels metadata: name: severity-info-low-priority spec: alertSelector: matchExpressions: - key: severity_level operator: In values: ["7", "8", "9"] additionalLabels: severity: Info -
Добавление лейбла
team=customдля алертов с указанными именами:apiVersion: observability.deckhouse.io/v1alpha1 kind: ClusterObservabilityAlertAdditionalLabels metadata: name: deckhouse-team-routing spec: alertSelector: matchExpressions: - key: alertname operator: In values: - D8CNIMisconfigured - D8DeckhouseIsNotOnReleaseChannel - D8DeckhouseIsNotOnReleaseChannel additionalLabels: team: custom
Группы триггеров
Группы триггеров используются для логической компоновки правил мониторинга и управления их параметрами на уровне набора правил.
Группы удобны для объединения триггеров, относящихся к одному компоненту, сервису или проекту, а также для применения единого интервала вычисления ко всем правилам группы.
Уведомления
Модуль observability предоставляет механизмы настройки доставки уведомлений об алертах
и разграничения доступа к каналам уведомлений на уровне кластера и проектов.
Поддерживаются следующие каналы доставки:
Email;Telegram;Slack;Webhook;ExpressMessenger;Zabbix.
Параметры подключения зависят от вида канала и настраиваются через соответствующий Kubernetes-ресурс.
Защита учётных данных канала
Поля с учётными данными защищены маркером x-kubernetes-sensitive-data: без прав на субресурс
<resource>/sensitive API-сервер отдаёт их как <omitted> в get/list/watch и маскирует в
журнале аудита. Права на /sensitive есть у всех, кто может создавать/редактировать сам канал; уровни без права
записи их не получают.
Требует feature gate CRDSensitiveData у kube-apiserver — включён по умолчанию начиная с DKP 1.77; на более ранних версиях маркер не действует, и учётные данные остаются доступными для чтения.
Виды каналов уведомлений
Поддерживаются три типа каналов уведомлений:
| Тип каналов | Область видимости | Кто может создавать |
|---|---|---|
| Системные каналы (ClusterObservabilityNotificationChannel) | Уровень кластера | Администраторы DKP |
| Проектные каналы (ObservabilityNotificationChannel) | Уровень проекта (неймспейса) | Пользователи соответствующего проекта |
| Общедоступные (propagated) каналы (ClusterObservabilityPropagatedNotificationChannel) | Создаются на уровне кластера и автоматически доступны во всех проектах | Администраторы DKP |
Описание видов каналов:
-
Системные каналы (ClusterObservabilityNotificationChannel) — используются для доставки уведомлений уровня кластера. Доступны в веб-интерфейсе Deckhouse в разделе «Система» → «Управление системой» → «Мониторинг» → «Настройка уведомлений» → «Каналы уведомлений».
-
Проектные каналы (ObservabilityNotificationChannel) — позволяют настраивать доставку уведомлений в рамках конкретного проекта. Доступны в веб-интерфейсе Deckhouse в соответствующем проекте → «Мониторинг» → «Настройка уведомлений» → «Каналы уведомлений».
-
Общедоступные (propagated) каналы (ClusterObservabilityPropagatedNotificationChannel) — создаются на уровне кластера и автоматически становятся доступными во всех проектах для доставки уведомлений. Для создания используется ресурс ClusterObservabilityPropagatedNotificationChannel или консольная утилита
d8.
Настройка HTTP-клиента Webhook-канала
Для каналов с spec.type: Webhook можно дополнительно настроить параметры исходящих HTTP-запросов в spec.webhook.httpConfig.
Доступны 3 взаимоисключающих варианта аутентификации:
basicAuth;authorization;oauth2.
Обязательные и опциональные поля
- Обязательное поле для Webhook-канала:
spec.webhook.url spec.webhook.httpConfig— опциональный блок- При использовании
oauth2обязательны поляoauth2.clientIdиoauth2.tokenUrl
Помимо аутентификации, в httpConfig доступны:
- параметры транспорта (
enableHttp2); - настройки прокси (
proxyUrl,noProxy,proxyFromEnvironment,proxyConnectHeader); - настройки TLS (
tlsConfig); - пользовательские заголовки (
httpHeaders).
Для OAuth2 есть два уровня настроек:
httpConfig.proxy*иhttpConfig.tlsConfigприменяются к запросам отправки webhook;httpConfig.oauth2.proxy*иhttpConfig.oauth2.tlsConfigприменяются к запросам получения OAuth2-токена.
Перечисленные ниже поля устарели и игнорируются из соображений безопасности. Они по-прежнему принимаются схемой CRD для обратной совместимости, но не имеют эффекта:
followRedirects— редиректы никогда не выполняются, поскольку редирект заставляет Alertmanager обратиться по адресу, который выбирает получатель уведомления;- поля с путями к файлам
passwordFile,credentialsFile,clientSecretFile,tlsConfig.caFile,tlsConfig.certFile,tlsConfig.keyFileиhttpHeaders.<name>.files— файлы больше не читаются из контейнера Alertmanager. Используйте соответствующее inline-поле (password,credentials,clientSecret) либоhttpHeaders.<name>.values/.secrets.
Пример с basicAuth:
apiVersion: observability.deckhouse.io/v1alpha1
kind: ClusterObservabilityNotificationChannel
metadata:
name: webhook-channel-basic-auth
spec:
type: Webhook
webhook:
url: https://hooks.example/webhook
httpConfig:
basicAuth:
username: notify-user
password: notify-secretПример с authorization:
apiVersion: observability.deckhouse.io/v1alpha1
kind: ClusterObservabilityNotificationChannel
metadata:
name: webhook-channel-authorization
spec:
type: Webhook
webhook:
url: https://hooks.example/webhook
httpConfig:
authorization:
type: Bearer
credentials: opaque-tokenПример с oauth2:
apiVersion: observability.deckhouse.io/v1alpha1
kind: ClusterObservabilityNotificationChannel
metadata:
name: webhook-channel-oauth2
spec:
type: Webhook
webhook:
url: https://hooks.example/webhook
httpConfig:
oauth2:
clientId: my-client
clientSecret: my-secret
tokenUrl: https://idp.example/token
scopes:
- read
- write
endpointParams:
audience: myappНастройка Zabbix-канала
Для каналов с spec.type: Zabbix Alertmanager отправляет алерты в Zabbix Server или Zabbix Proxy
в push-режиме по протоколу Zabbix sender (trapper).
Обязательные и опциональные поля
-
Обязательное поле:
spec.zabbix.server— адрес Zabbix Server или Zabbix Proxy. -
Обязательное поле:
spec.zabbix.clusterName— произвольная строка, которая становится техническим именем объекта Host в Zabbix, которому принадлежат отправляемые элементы данных и импортированный шаблон. Выберите любое значение, уникальное среди всех кластеров/каналов, указывающих на один и тот же Zabbix (например, публичный домен кластера, если он у вас есть, или любой другой идентификатор, которым в команде уже называют этот кластер). -
spec.zabbix.port— порт sender-протокола (по умолчанию10051). -
spec.zabbix.hostGroup— имя группы хостов (host group) в Zabbix, в которую помещается Host этого кластера. По умолчанию —Deckhouse. -
Sender-соединение с Zabbix шифруется по умолчанию, сертификат проверяется по системному хранилищу доверенных сертификатов. В
spec.zabbix.tlsсертификаты задаются содержимым в формате PEM:ca— CA Zabbix;certиkey— клиентский сертификат, обязательный для режима сертификатов Zabbix (это взаимный TLS;insecureSkipVerifyэтого требования не снимает);serverName;skipServerNameVerification— проверять цепочку сертификата, но не имя, для сертификата Zabbix без Subject Alternative Name (требуетca);insecureSkipVerify.caFile,certFileиkeyFileустарели и игнорируются. Режим Zabbix PSK не поддерживается.spec.zabbix.disableTLS: trueполностью отключает шифрование — для Zabbix Server/Proxy без TLS на trapper-порту.spec: zabbix: tls: ca: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- cert: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- skipServerNameVerification: true -
spec.zabbix.api— опциональное поле; включает автоматический импорт поставляемого шаблона через API Zabbix (см. «Автоматический импорт через API Zabbix» ниже). Если не задано, формируется толькоConfigMapдля ручного импорта.
Когда алерт перестал гореть
- Погасший алерт отправляется ещё один раз со значением
0, и его триггер гаснет сразу. - В следующем уведомлении алерта уже нет в discovery-данных, поэтому Zabbix помечает его элемент как
lost и удаляет по истечении
lifetimediscovery-правила (1 час) — алерт пропадает и из Latest data. - Страховка: триггер также гаснет, если в элемент алерта ничего не приходило 5 минут (например, алерт заглушили silence’ом и уведомление о resolve не отправлялось).
Поскольку проверка свежести опирается на переотправку алертов, spec.notification.repeatInterval
для Zabbix-канала ограничен сверху значением 2m (большее значение молча уменьшается); дефолт 30s
подходит. spec.alert.groupByLabels для Zabbix-каналов игнорируется: все алерты, подошедшие под
политику, отправляются вместе в каждом уведомлении — этого требуют discovery-правила Zabbix. Какие
именно алерты отправляются, по-прежнему задаёт spec.alert.selector.
Элемент d8alerts.sender.heartbeat поддерживается свежим постоянно работающим алертом платформы
DeadMansSwitch — он роутится в канал так же, как любой другой алерт, через селектор привязанной
ObservabilityNotificationPolicy. Узкий селектор (например severity="critical") нужно явно
дополнить матчем alertname="DeadMansSwitch", чтобы heartbeat работал. Через nodata() на этом
элементе Zabbix обнаруживает обрыв пути.
Heartbeat-элемент есть только в шаблоне ClusterObservabilityNotificationChannel. В namespace-scoped
ObservabilityNotificationChannel и в ClusterObservabilityPropagatedNotificationChannel
DeadMansSwitch не попадает, поэтому в их шаблонах heartbeat-элемента нет.
Регистрация шаблона в Zabbix: вручную или автоматически
Поставляемый шаблон (формат zabbix_export) уже включает Host и Host Group кластера
(spec.zabbix.clusterName/hostGroup), поэтому после импорта больше ничего вручную настраивать не
нужно. Есть два способа завести его в Zabbix:
Ручной импорт (доступен всегда)
Контроллер всегда формирует шаблон в ConfigMap канала, независимо от spec.zabbix.api. Имя и
неймспейс зависят от вида канала:
| Вид канала | Имя ConfigMap | Неймспейс |
|---|---|---|
ObservabilityNotificationChannel |
<имя-канала>-zabbix-template |
тот же, что у канала |
ClusterObservabilityNotificationChannel |
cluster-<имя-канала>-zabbix-template |
неймспейс модуля |
ClusterObservabilityPropagatedNotificationChannel |
propagated-<имя-канала>-zabbix-template |
неймспейс модуля |
Извлеките его — например, для проектного канала my-zabbix-channel в неймспейсе my-namespace:
kubectl get configmap my-zabbix-channel-zabbix-template -n my-namespace \
-o jsonpath='{.data.template\.yaml}' > d8alerts-sender.yamlЗатем импортируйте этот файл в Zabbix дважды, строго в таком порядке:
- Сбор данных → Шаблоны → Импорт — создаёт шаблон, группу шаблонов и группу узлов сети. Узел сети из файла на этом шаге Zabbix не импортирует.
- Сбор данных → Узлы сети → Импорт (тот же файл) — создаёт узел сети
spec.zabbix.clusterNameв группеspec.zabbix.hostGroupи привязывает к нему шаблон. Шаблон на этом шаге не создаётся, поэтому без первого шага импорт завершится ошибкой.
Автоматический импорт через API Zabbix (опционально)
Если задать spec.zabbix.api, контроллер импортирует тот же самый отрендеренный шаблон прямо в
Zabbix через его JSON-RPC API (configuration.import), в дополнение к (а не вместо) ConfigMap
выше:
spec:
type: Zabbix
zabbix:
server: zabbix.example.com
clusterName: my-cluster
hostGroup: Deckhouse
api:
url: https://zabbix.example.com/api_jsonrpc.php
token: <zabbix-api-токен>spec.zabbix.api.url— адрес JSON-RPC API Zabbix; если схема не указана, используетсяhttps://. Это другой адрес, чемspec.zabbix.server: у Zabbix Proxy нет своего API, поэтомуapi.urlдолжен указывать на центральный Zabbix Server. Требуется Zabbix ≥6.4.spec.zabbix.api.token— API-токен Zabbix. Заведите отдельный токен с максимально урезанной по правам ролью (ограниченной нужной template group и host group), а не используйте учётную запись Super Admin.spec.zabbix.api.tlsConfig— опциональные настройки TLS для HTTPS-соединения с API Zabbix:ca,cert,key(содержимое PEM, как вspec.zabbix.tls),serverName,insecureSkipVerify.caFile,certFileиkeyFileустарели и игнорируются.
Если импорт не удался, смотрите логи observability-controller — сообщение failed to import zabbix template via api. Типичные причины ошибок: API Zabbix недоступен, токен неверен, у роли токена не
хватает прав на нужный template group/host group, или версия Zabbix меньше 6.4. Импорт повторяется
автоматически на каждом reconcile (например, после правки канала или при следующем рестарте
контроллера), так что временная ошибка исчезает сама, без каких-либо действий.
Выбор адреса Zabbix-сервера
Предпочитайте стабильное DNS-имя литералу IP для spec.zabbix.server и spec.zabbix.api.url — для
Zabbix внутри кластера это DNS-имя Kubernetes Service, а не IP ноды или пода. Admission-webhook
выдаёт неблокирующее предупреждение на литеральные IP.
Правила уведомлений
Правила уведомлений позволяют определить, по какому каналу должны отправляться уведомления для алерта (или группы алертов).
Первое уведомление по новой группе алертов отправляется сразу. Последующие изменения группы (новые
алерты в ней, разрешённые алерты) отправляются в пределах 10 секунд (или repeatInterval, если он
короче), с той же частотой повторяются попытки для канала, приёмник которого стабильно отвечает
ошибкой. spec.notification.repeatInterval задаёт, как часто повторно отправляется неизменившаяся,
всё ещё горящая группа.
| Тип правил | Описание | Как настроить |
|---|---|---|
| Системные правила уведомлений | Позволяют настроить правила для отправки системных алертов. Cистемные правила могут использовать только системные каналы уведомлений. Доступны в веб-интерфейсе Deckhouse в разделе «Система» → «Управление системой» → «Мониторинг» → «Настройки уведомлений» → «Правила уведомлений». | Используйте ресурс ClusterObservabilityNotificationPolicy. |
| Проектные правила уведомлений | Позволяют настроить правила для отправки проектных алертов. Проектные правила могут использовать проектные или стандартные кластерные каналы уведомлений, но не системные каналы уведомлений. Доступны в веб-интерфейсе Deckhouse в соответствующем проекте → «Мониторинг» → «Настройки уведомлений» → «Правила уведомлений». | Используйте ресурс ObservabilityNotificationPolicy. |
Отключение уведомлений
В ситуациях, когда уведомления ожидаются заранее (например, при плановых работах или тестировании),
модуль observability позволяет отключить отправку уведомлений для алертов, соответствующих заданным условиям.
| Тип отключений | Описание | Как настроить |
|---|---|---|
| Системные отключения уведомлений | Позволяют настроить правила отключения отправки системных алертов. Доступны в веб-интерфейсе Deckhouse в разделе «Система» → «Управление системой» → «Мониторинг» → «Настройки уведомлений» → «Отключение уведомлений». | Используйте ресурс ClusterObservabilityNotificationSilence. |
| Проектные отключения уведомлений | Позволяют настроить правила отключения отправки проектных алертов. Доступны в веб-интерфейсе Deckhouse в соответствующем проекте → «Мониторинг» → «Настройки уведомлений» → «Отключение уведомлений». | Используйте ресурс ObservabilityNotificationSilence. |
Алерты
Модуль observability обеспечивает разграничение прав доступа к алертам уровня кластера и проектов,
а также позволяет просматривать список активных и завершённых алертов.
Активные алерты разделяются по уровню критичности:
- критические (
critical, S1–S3); - предупреждающие (
warning, S4–S6); - информационные (
info, S7–S9).
При просмотре алерта пользователь может увидеть общую информацию, лейблы, аннотации и график.
Виды алертов
Поддерживаются два типа алертов:
| Тип алертов | Область видимости | У кого есть доступ |
|---|---|---|
| Системные алерты (ClusterObservabilityAlerts) | Уровень кластера | Администраторы DKP |
| Проектные алерты (ObservabilityAlerts) | Уровень проекта (неймспейса) | Пользователи соответствующего проекта |
Описание видов алертов:
-
Системные алерты (ClusterObservabilityAlerts) — относятся к компонентам кластера DKP. Полный список активных и завершенных системных алертов доступен в веб-интерфейсе Deckhouse в разделе «Система» → «Управление системой» → «Мониторинг» → «Активные алерты».
-
Проектные алерты (ObservabilityAlerts) — относятся к ресурсам конкретного проекта (неймспейса). Полный список активных и завершенных проектных алертов доступен в веб-интерфейсе Deckhouse в соответствующем проекте → «Мониторинг» → «Активные алерты».
Алерты DeadMansSwitch и PrometheusUnavailable
DeadMansSwitch
DeadMansSwitch — это служебный алерт, который срабатывает непрерывно, тем самым подтверждая нормальную работу Prometheus и всего пайплайна доставки алертов.
Если DeadMansSwitch перестает поступать, начинает срабатывать алерт PrometheusUnavailable.
По умолчанию алерт DeadMansSwitch отправляется во все настроенные каналы уведомлений, если для них не задана фильтрация по лейблам в политиках уведомлений. В каналах типа Zabbix он не отображается как problem, а обновляет элемент d8alerts.sender.heartbeat (см. Настройка Zabbix-канала).
Чтобы не засорять список алертов, DeadMansSwitch скрыт из вывода команды d8 k get clusterobservabilityalerts (list/watch).
Чтобы получить его напрямую, используйте следующую команду:
d8 k get clusterobservabilityalert deadmansswitchОтключение этого алерта не рекомендуется, но при необходимости это можно сделать вручную с помощью параметра deadMansSwitch.enabled в настройках модуля.
При ручном отключении алерт PrometheusUnavailable не создается.
PrometheusUnavailable
PrometheusUnavailable (ранее — MissingDeadMansSwitch) — это алерт, который срабатывает, если DeadMansSwitch не поступает более 2 минут.
Это указывает на проблему в пайплайне доставки алертов. Возможные причины:
- недоступен Prometheus;
- нарушено взаимодействие между Prometheus и Alertmanager;
- иная проблема, препятствующая отправке алертов.
Алерт PrometheusUnavailable является системным и отображается как в веб-интерфейсе Deckhouse, так и в выводе команды d8 k get clusterobservabilityalerts.
Алерт NodePingPacketLoss
NodePingPacketLoss срабатывает, если потери ICMP-пакетов до узла кластера, которые агент сбора метрик измеряет с каждого узла, превышают 5% за 5 минут и остаются выше этого порога ещё 5 минут. Уровень важности алерта — S4, лейбл destination_node указывает узел, до которого теряются пакеты.
Модуль observability создаёт этот алерт, только пока модуль monitoring-ping выключен. Пока monitoring-ping включён, он сохраняет собственное правило с тем же именем и выражением, поэтому алерт существует ровно в одном экземпляре. Правило создаётся как ресурс ClusterObservabilityMetricsRulesGroup observability-node-ping-node-ping-0.
Алерт ObservabilityPingExternalTargetsNotMigrated
ObservabilityPingExternalTargetsNotMigrated срабатывает, если список externalTargets ModuleConfig monitoring-ping не удалось скопировать в параметр opagent.pingExternalTargets ModuleConfig observability, потому что он превышает ограничение этого параметра (не более 1000 записей, host не из одних пробелов длиной от 1 до 253 символов, name — не длиннее 253 символов). Лейбл limit указывает превышенное ограничение: maxItems, host или name. Уровень важности алерта — S5, алерт срабатывает, если условие выполняется 10 минут.
Чтобы устранить проблему, задайте opagent.pingExternalTargets в ModuleConfig observability вручную — списком в пределах ограничений или [], если внешние цели не нужны. Алерт прекращается, когда параметр задан, старый список укладывается в ограничения или ModuleConfig monitoring-ping удалён.
Алерт ObservabilityMonitoringPingModuleEnabled
ObservabilityMonitoringPingModuleEnabled срабатывает, пока включён модуль monitoring-ping: узлы кластера и внешние хосты теперь пингует агент сбора метрик модуля observability, и модуль monitoring-ping больше не нужен. Пока он включён, агент не пингует на узлах, где работает под monitoring-ping, а алерт NodePingPacketLoss по-прежнему создаёт monitoring-ping. Уровень важности алерта — S8, алерт срабатывает через 5 минут после обновления модуля observability.
Внешние цели пинга (externalTargets ModuleConfig monitoring-ping) по возможности автоматически копируются в opagent.pingExternalTargets ModuleConfig observability. Если ModuleConfig observability управляется внешним инструментом (Argo CD, Flux, kubectl apply из CI), скопированное значение не сохранится: добавьте opagent.pingExternalTargets в управляемый манифест.
Чтобы устранить проблему:
-
Если ModuleConfig
monitoring-pingсуществует и в нём заданexternalTargets, проверьте, что те же цели есть вopagent.pingExternalTargetsModuleConfigobservability:d8 k get mc monitoring-ping -o jsonpath='{.spec.settings.externalTargets}' d8 k get mc observability -o jsonpath='{.spec.settings.opagent.pingExternalTargets}' -
Выключите модуль
monitoring-ping. Модуль включён по умолчанию, поэтому его ModuleConfig может не существовать; команда работает в обоих случаях:d8 platform module disable monitoring-ping
Алерт прекращается, когда модуль monitoring-ping выключен.