Версия: 9.3

Инструкция по установке helm-chart monq-infra-mon

Общая информация

Цель данной инструкции — предоставить пользователю возможность самостоятельно развернуть стек мониторинга monq-infra-mon (Prometheus Operator, Prometheus, Alertmanager, Grafana, node-exporter, kube-state-metrics, blackbox-exporter) в кластере K8s, где уже работает инфраструктура MONQ.

Инструкция описывает состав решения, предполагаемый путь по развёртыванию и носит рекомендательный характер: каждая установка уникальна, частные особенности операционной системы, прав и сетевых ограничений учитываются отдельно.

Инструкция актуальна для версии чарта 1.1.1.

Для работы с данным документом пользователю необходимо иметь опыт работы с:

Kubernetes, в частности инструментами kubectl, helm
Prometheus и ресурсами ServiceMonitor
утилитой discli для копирования образов между реестрами (оффлайн режим)

Параметры целевого кластера указаны для примера и будут использованы в тексте. Для другого кластера замените их на собственные значения:

Параметр	Значение (в примере)
Целевой узел (одноузловой кластер)	`s7-monq-mon` (10.10.7.9)
Kubernetes	v1.33.13, Debian 13
Namespace компонентов MONQ	`monq-infra`
Namespace стека мониторинга	`monitoring` (создаётся по инструкции)
Внутренний реестр образов	`registry.in.mycompany.local:5000`
Ingress-контроллер	ingress-nginx, IngressClass `nginx`

Стек мониторинга устанавливается в отдельный namespace monitoring и не смешивается с компонентами MONQ.

Все команды выполняются на узле управления (control-plane), если не указано иное в инструкции. В single-node кластере узел control-plane является единственным, поэтому команды, отмеченные «на узле», выполняются там же.

Состав стека мониторинга

Компонент	Версия	Назначение
prometheus-operator	v0.94.1	Управление ресурсами Prometheus, ServiceMonitor, PrometheusRule и Alertmanager через CRD
Prometheus	v3.15.0	Сбор и хранение метрик, генерация алертов по правилам
Alertmanager	v0.34.1	Группировка, маршрутизация и доставка алертов
Grafana	13.2.3	Визуализация
node-exporter	v1.12.1	Метрики узлов (CPU, память, диски, сеть)
kube-state-metrics	v2.17.0	Метрики объектов Kubernetes
blackbox-exporter	v0.29.1	TCP-пробы доступности портов инфраструктурных сервисов (Consul, Garage S3/API, реестр образов)
Экспортёры компонентов	—	PostgreSQL exporter, Redis exporter (сайдкары). RabbitMQ, ClickHouse, ArangoDB, VictoriaMetrics, ingress-nginx (встроенные эндпоинты)

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

Перед началом работ убедитесь, что в кластере присутствуют:

компоненты СПО MONQ (postgresql, arangodb, clickhouse, redis, rabbitmq, victoriametrics)
ingress-nginx-controller (IngressClass nginx) — через него будет доступна UI Grafana, Prometheus, Alertmanager и собираются собственные метрики контроллера

⚠️ Если стек мониторинга уже развёрнут в кластере, сначала выполните его удаление (раздел «Удаление»).

⚠️ Чарт не переиспользует уже установленные компоненты. Если в кластере уже развёрнуты Prometheus Operator, Prometheus, Alertmanager, Grafana, node-exporter или kube-state-metrics — установка приведёт к конфликтам (дублирующиеся CRD, ServiceMonitor, Service/Deployment с одинаковыми именами, борьба за порты). Перед установкой удалите существующий стек мониторинга (см. раздел «Удаление»).

ℹ️ Продвинутый сценарий. Если вы понимаете, что делаете, чарт можно использовать выборочно: изучите values.yaml, отключите ненужные компоненты (prometheusOperator.enabled: false и т.д.) и разверните только недостающие. Это возможно, но — совместимость с вашей существующей конфигурацией не гарантируется, ответственность за результат на вас.

Список переменных, используемых по тексту:

${infra_namespace} — namespace инфраструктурных компонентов MONQ
${monitoring_namespace} — namespace стека мониторинга
${registry_address} — адрес внутреннего реестра образов
${node_name} — узел, на котором размещаются данные мониторинга
${domain} — базовый домен хостов ingress (в примере — in.mycompany.local)
${chart_path} — путь к архиву чарта (/tmp/monq-infra-mon-1.1.1.tgz)
${arangodb_password} — пароль ArangoDB, извлекается из секрета кластера (шаг 4)
${victoriametrics_user}, ${victoriametrics_password} — учётные данные VictoriaMetrics, извлекаются из секрета кластера (шаг 4)

Подготовка

Скопируйте архив чарта monq-infra-mon-1.1.1.tgz на узел control-plane в каталог /tmp.

helm repo add monq https://helm.monq.ru/charts

helm pull monq/monq-infra-mon --version 1.1.1 -d /tmp

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

export infra_namespace=monq-infra
export monitoring_namespace=monitoring
export registry_address=registry.in.mycompany.local:5000
export node_name=s7-monq-mon
export domain=in.mycompany.local
export chart_path=/tmp/monq-infra-mon-1.1.1.tgz

Шаг 1. Подготовка кластера

1.1 Namespace стека мониторинга

Создайте namespace (если он ещё не существует):

kubectl create namespace ${monitoring_namespace}

1.2 Метка узла

Проверьте наличие у узла метки monitoring=:

kubectl get nodes ${node_name} --show-labels | grep -o 'monitoring='
# Ожидание: monitoring=

В случае, если метка отсутствует, назначьте её:

kubectl label node ${node_name} monitoring

1.3 StorageClass

Создайте StorageClass local-storage (команда идемпотентна, безопасно выполняется повторно):

cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-storage
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: Immediate
reclaimPolicy: Delete
EOF

kubectl get sc local-storage
# Ожидание: local-storage   kubernetes.io/no-provisioner   Delete   Immediate

1.4 Каталоги на узле

Внимание! Команды выполняются на узле ${node_name}.

Создайте на узле каталоги для данных мониторинга:

mkdir -p /storage/prometheus /storage/grafana

Шаг 2. Копирование образов во внутренний реестр

Проверьте, есть ли у узла, на котором будет размещаться стек, доступ к внешним реестрам образов:

# на узле:
curl -sI --max-time 5 https://quay.io | head -1
# изолированный узел — ответа не будет

В случае, если у узла есть доступ к внешним реестрам, данный шаг пропускается: из команды шага 4 исключаются все строки --set ...image.registry= и --set ...image= — чарт будет использовать дефолтные внешние реестры.

В случае, если у узла нет доступа, выполните копирование образов стека мониторинга во внутренний реестр на узле, на котором есть доступ и к внешним реестрам, и к ${registry_address}:

discli copy quay.io/prometheus-operator/prometheus-operator:v0.94.1 \
  ${registry_address}/prometheus-operator:v0.94.1
discli copy quay.io/prometheus-operator/prometheus-config-reloader:v0.94.1 \
  ${registry_address}/prometheus-config-reloader:v0.94.1
discli copy quay.io/prometheus/prometheus:v3.15.0 \
  ${registry_address}/prometheus:v3.15.0
discli copy quay.io/prometheus/alertmanager:v0.34.1 \
  ${registry_address}/alertmanager:v0.34.1
discli copy quay.io/prometheus/node-exporter:v1.12.1 \
  ${registry_address}/node-exporter:v1.12.1
discli copy registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.17.0 \
  ${registry_address}/kube-state-metrics:v2.17.0
discli copy docker.io/grafana/grafana:13.2.3 \
  ${registry_address}/grafana:13.2.3
discli copy quay.io/prometheus/blackbox-exporter:v0.29.1 \
  ${registry_address}/blackbox-exporter:v0.29.1
# Экспортёры компонентов (потребуются на шаге 3)
discli copy docker.io/wrouesnel/postgres_exporter:v0.7.0 \
  ${registry_address}/postgres_exporter:v0.7.0
discli copy docker.io/oliver006/redis_exporter:v1.45.0-alpine \
  ${registry_address}/redis_exporter:v1.45.0-alpine

Шаг 3. Включение метрик в компонентах СПО MONQ

Чарты компонентов СПО MONQ включают мониторинг флагом monitoring.enable=true: запускается exporter-сайдкар (postgresql, redis) либо включается встроенный эндпоинт (clickhouse), создаётся сервис <имя>-monitoring.

Выполните включение сбора метрик с компонентов СПО:

# postgresql: exporter-сайдкар postgres_exporter (порт 9187)
helm upgrade postgresql monq/postgresql --reuse-values \
  --set monitoring.enable=true \
  -n ${infra_namespace} --version 1.1.0

# redis: exporter-сайдкар redis_exporter (порт 9121)
helm upgrade redis monq/redis --reuse-values \
  --set monitoring.enable=true \
  -n ${infra_namespace} --version 1.1.0

# clickhouse: встроенный prometheus-эндпоинт (порт 9363)
helm upgrade clickhouse monq/clickhouse --reuse-values \
  --set monitoring.enable=true \
  -n ${infra_namespace} --version 1.1.0

# rabbitmq: встроенный prometheus-плагин management (порт 15692),
# в кастомных образах MONQ включён
helm upgrade rabbitmq monq/rabbitmq --reuse-values \
  --set monitoring.enable=true \
  -n ${infra_namespace} --version 1.2.0

Компоненты arangodb и victoriametrics изменений не требуют — в их чартах флага нет, встроенные метрики доступны всегда (arangodb: /_admin/metrics/v2 на порту 8529, victoria-metrics: /metrics на порту 8428).

Ingress-nginx не является компонентом репозитория monq и включается отдельно: включите встроенный метрический эндпоинт (порт 10254) и отключите собственный ServiceMonitor. ServiceMonitor для ingress-nginx создаст чарт monq-infra-mon:

helm upgrade -n ingress-nginx ingress-nginx ingress-nginx/ingress-nginx \
  --version 4.12.1 --reuse-values \
  --set controller.metrics.enabled=true \
  --set controller.metrics.serviceMonitor.enabled=false

Проверьте создание сервисов:

kubectl get svc -n ${infra_namespace} | grep monitoring
# Ожидание: postgresql-monitoring, redis-monitoring,
#           clickhouse-monitoring, rabbitmq-monitoring

Шаг 4. Установка чарта

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

arangodb_password=$(kubectl get secret -n ${infra_namespace} arangodb-secret \
  -o jsonpath='{.data.ARANGO_ROOT_PASSWORD}' | base64 --decode)
victoriametrics_user=$(kubectl get secret -n ${infra_namespace} victoriametrics-secret \
  -o jsonpath='{.data.VM_AUTH_USER}' | base64 --decode)
victoriametrics_password=$(kubectl get secret -n ${infra_namespace} victoriametrics-secret \
  -o jsonpath='{.data.VM_AUTH_PASSWORD}' | base64 --decode)

⚠️ Для повышения безопасности рекомендуется создать специальные учётные записи для целей мониторинга и использовать их.

ℹ️ TCP-пробы (tcpProbes). По умолчанию проверяются порты consul (8500), garage S3 (3900) и admin API (3903) — сервисы в namespace infra, и реестр registry.in.monq.local:5000. В примере настоящей инструкции компоненты MONQ развёрнуты в namespace monq-infra, а реестр — внутренний, поэтому цели переопределены сразу в команде установки (--set-json tcpProbes.targets=...): без этого пробы указывали бы на несуществующие адреса *.infra.svc.cluster.local и алерт TcpProbeFailed срабатывал бы постоянно. Для кластера с другой топологией скорректируйте цели: name (входит в имя Probe-ресурса tcp-probe-<name>) и target вида <host>:<port>; формирование адресов — раздел 4.11 README.

Выполните установку чарта:

helm install monq-infra-mon ${chart_path} -n ${monitoring_namespace} \
  --set domain=${domain} \
  --set prometheusOperator.image.registry=${registry_address} \
  --set prometheusOperator.image.repository=prometheus-operator \
  --set prometheusOperator.configReloader.image.registry=${registry_address} \
  --set prometheusOperator.configReloader.image.repository=prometheus-config-reloader \
  --set prometheus.image.registry=${registry_address} \
  --set prometheus.image.repository=prometheus \
  --set alertmanager.image.registry=${registry_address} \
  --set alertmanager.image.repository=alertmanager \
  --set nodeExporter.image=${registry_address}/node-exporter \
  --set kubeStateMetrics.image=${registry_address}/kube-state-metrics \
  --set grafana.image.registry=${registry_address} \
  --set grafana.image.repository=grafana \
  --set blackboxExporter.image=${registry_address}/blackbox-exporter \
  --set-json tcpProbes.targets='[{"name":"consul-http","target":"consul.monq-infra.svc.cluster.local:8500"},{"name":"garage-s3","target":"garage.monq-infra.svc.cluster.local:3900"},{"name":"garage-api","target":"garage.monq-infra.svc.cluster.local:3903"},{"name":"registry","target":"registry.in.mycompany.local:5000"}]' \
  --set grafana.dashboards.redis.enabled=true \
  --set grafana.dashboards.postgresql.enabled=true \
  --set grafana.dashboards.clickhouse.enabled=true \
  --set grafana.dashboards.victoriametrics.enabled=true \
  --set serviceMonitors.postgresql.namespace=${infra_namespace} \
  --set serviceMonitors.arangodb.namespace=${infra_namespace} \
  --set serviceMonitors.arangodb.username=root \
  --set serviceMonitors.arangodb.password=${arangodb_password} \
  --set serviceMonitors.clickhouse.namespace=${infra_namespace} \
  --set serviceMonitors.redis.namespace=${infra_namespace} \
  --set serviceMonitors.rabbitmq.namespace=${infra_namespace} \
  --set serviceMonitors.victoriaMetrics.namespace=${infra_namespace} \
  --set serviceMonitors.victoriaMetrics.username=${victoriametrics_user} \
  --set serviceMonitors.victoriaMetrics.password=${victoriametrics_password}

При необходимости доставки алертов в Telegram после установки выполните раздел «Шаг 6. Уведомления в Telegram (опционально)».

Проверьте состояние подов:

kubectl -n ${monitoring_namespace} get pods -w
# Следить, пока все поды не станут Running:
#   prometheus-operator-*, prometheus-monq-infra-mon-0,
#   alertmanager-monq-infra-mon-0, grafana-*, kube-state-metrics-*, node-exporter-*,
#   blackbox-exporter-*

Проверьте состояние хранилища:

kubectl get pv | grep monq-infra-mon
# Ожидание (каждый PV привязан к своему PVC):
#   monq-infra-mon-prometheus-pv   50Gi   ...   Bound   monitoring/prometheus-monq-infra-mon-db-...
#   monq-infra-mon-grafana-pv      5Gi    ...   Bound   monitoring/grafana

kubectl get pvc -n ${monitoring_namespace}
# Ожидание: все PVC — Bound

Шаг 5. Проверка

Для проверки стека мониторинга через веб-интерфейс, настройте на машине, с которой он будет открываться (на Linux — /etc/hosts, на Windows — C:\Windows\System32\drivers\etc\hosts), разрешение адресов Ingress:

# пример
10.10.7.9  grafana.in.mycompany.local prometheus.in.mycompany.local alertmanager.in.mycompany.local

Или используйте корпоративные DNS службы.

Адреса:

UI	URL
Grafana	http://grafana.in.mycompany.local/
Prometheus	http://prometheus.in.mycompany.local/
Alertmanager	http://alertmanager.in.mycompany.local/

5.1 Поды и ресурсы

kubectl -n ${monitoring_namespace} get pods
kubectl -n ${monitoring_namespace} get servicemonitor
# Ожидание: apiserver, arangodb, blackbox-exporter, clickhouse,
#           ingress-nginx-controller, kube-state-metrics, kubelet,
#           node-exporter, postgres, rabbitmq, redis, victoria-metrics

kubectl -n ${monitoring_namespace} get probe
# Ожидание: tcp-probe-consul-http, tcp-probe-garage-s3,
#           tcp-probe-garage-api, tcp-probe-registry

kubectl -n ${monitoring_namespace} get prometheusrule
# Ожидание, группы правил: arangodb, blackbox, clickhouse, ingress-nginx,
# kube-state-metrics, kubernetes (+ additional), node-exporter,
# postgresql, rabbitmq, redis, victoria-metrics

5.2 Prometheus — targets

Откройте http://prometheus.in.mycompany.local/ → Status → Targets. Ожидаются UP: node (node-exporter), kube-state-metrics, kubelet, apiserver, ingress-nginx, postgresql, redis, clickhouse, arangodb, rabbitmq, victoria-metrics, blackbox-exporter, а также цели TCP-проб monitoring/tcp-probe-consul-http, tcp-probe-garage-s3, tcp-probe-garage-api, tcp-probe-registry (через prober blackbox-exporter).

Проверка доступности портов (Prometheus → Graph):

probe_success        # 1 — порт принимает соединения, 0 — нет (алерт TcpProbeFailed через 2m)

5.3 Grafana

Откройте http://grafana.in.mycompany.local/, логин admin, пароль monq-infra-mon (grafana.adminPassword в values). Ожидается:

datasource prometheus (uid prometheus) — активна.
datasource alertmanager (uid alertmanager, плагин Prometheus AlertManager Datasource) — только при grafana.alertmanager.enabled=true (по умолчанию выключено).
все дашборды имеют переменную datasource (тип datasource) — источник метрик выбирается в шапке дашборда, по умолчанию выбран Prometheus.
дашборды non-editable (allowUiUpdates: false) — нажатие «Save» в интерфейсе Grafana изменения не сохранит.

Шаг 6. Уведомления в Telegram (опционально)

Раздел опционален. В случае, если доставка алертов в Telegram не требуется, он пропускается.

Доставка выполняется нативно — без дополнительных сервисов: интеграция Telegram входит в состав Alertmanager.

В ресурсе AlertmanagerConfig значение токена не хранится: там задаётся ссылка на секрет Kubernetes (botToken: {name, key}), оператор подставляет значение из секрета при формировании конфигурации Alertmanager.

Параметры для данного кластера. Значения указаны для примера, замените их на фактические (в командах этого раздела используются переменные ${telegram_chat_id} и ${telegram_bot_token}):

Параметр	Значение (в примере)
Чат (группа), `${telegram_chat_id}`	`-1001234567890` (идентификатор группы — со знаком минус. Бот должен быть добавлен в группу)
Токен бота, `${telegram_bot_token}`	`123456789:AAExampleTokenValue1234567890`
Отправляемая критичность	`severity: warning`, `severity: critical` (алерты с `severity: info` не доставляются)

Внимание! Токен бота даёт полный доступ к нему. Не публикуйте его в открытых источниках. При компрометации перевыпустите токен через бота @BotFather.

6.1. Секрет с токеном бота

Создайте секрет в namespace стека мониторинга (команда идемпотентна):

kubectl create secret generic monq-infra-mon-telegram-bot \
  -n ${monitoring_namespace} \
  --from-literal=token=${telegram_bot_token} \
  --dry-run=client -o yaml | kubectl apply -f -

6.2. Настройка Alertmanager

После создания секрета (6.1) добавьте получателя telegram и маршрут, направляющий в него алерты с severity warning/critical, командой helm upgrade с сохранением текущих параметров (--reuse-values). Алерты с severity: info останутся без доставки (receiver null). Флаг --set-json — вариант --set для вложенных и списочных значений (значение задаётся строкой JSON), остальные ключи alertmanager.specConfig (корневой маршрут, groupBy, интервалы) сохраняются без изменений:

helm upgrade monq-infra-mon ${chart_path} -n ${monitoring_namespace} \
  --reuse-values \
  --set-json alertmanager.specConfig.receivers='[{"name":"null"},{"name":"telegram","telegramConfigs":[{"chatID":${telegram_chat_id},"botToken":{"name":"monq-infra-mon-telegram-bot","key":"token"}}]}]' \
  --set-json alertmanager.specConfig.route.routes='[{"matchers":[{"name":"severity","value":"warning|critical","matchType":"=~"}],"receiver":"telegram"}]'

Удаление

# 1. Убрать мониторинг
helm uninstall monq-infra-mon -n ${monitoring_namespace}

# 2. Удалить оставшийся PVC Prometheus: Helm его НЕ удаляет (его создаёт
#    prometheus-operator), пока он жив, PV висит в Terminating
kubectl delete pvc -n ${monitoring_namespace} -l prometheus=monq-infra-mon --ignore-not-found

# 3. Проверить: PVC в monitoring пусты, PV monq-infra-mon-* исчезли
kubectl get pvc -n ${monitoring_namespace}
kubectl get pv | grep monq-infra-mon

# 4. (если PV всё ещё Terminating) снять finalizer вручную:
kubectl patch pv monq-infra-mon-prometheus-pv -p '{"metadata":{"finalizers":null}}'

# 5. (по желанию) удалить namespace целиком
kubectl delete ns ${monitoring_namespace}

# 6. (опционально) вернуть компоненты без метрик
helm upgrade postgresql monq/postgresql --reuse-values --set monitoring.enable=false -n ${infra_namespace} --version 1.1.0
# аналогично для redis (1.1.0), clickhouse (1.1.0), rabbitmq (1.2.0)

# 7. (если выполнялся шаг 6) удалить секрет токена Telegram-бота
kubectl delete secret monq-infra-mon-telegram-bot -n ${monitoring_namespace} --ignore-not-found

Данные на узле не стираются при удалении PV: содержимое /storage/prometheus и /storage/grafana остаётся. При повторной установке чарта новые PV привяжутся к тем же путям и данные сохранятся (история Prometheus, БД и плагины Grafana).

CRD prometheus-operator после helm uninstall останутся в кластере (helm их не удаляет). При полном удалении мониторинга: tar -xzOf ${chart_path} monq-infra-mon/crds/operatorCrd.yaml | kubectl delete -f -.

Общая информация​

Состав стека мониторинга​

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

Подготовка​

Шаг 1. Подготовка кластера​

1.1 Namespace стека мониторинга​

1.2 Метка узла​

1.3 StorageClass​

1.4 Каталоги на узле​

Шаг 2. Копирование образов во внутренний реестр​

Шаг 3. Включение метрик в компонентах СПО MONQ​

Шаг 4. Установка чарта​

Шаг 5. Проверка​

5.1 Поды и ресурсы​

5.2 Prometheus — targets​

5.3 Grafana​

Шаг 6. Уведомления в Telegram (опционально)​

6.1. Секрет с токеном бота​

6.2. Настройка Alertmanager​

Удаление​