Мониторинг Kubernetes

Мониторинг Kubernetes в Наблюдателе работает через агента — один Deployment в namespace, который вы хотите наблюдать. Агент читает поды через kube API и раз в 30 секунд отправляет их статусы, рестарты, OOM, коды выхода, CPU и память, а также ошибки из логов. Права у него только на чтение: в кластере он ничего не создаёт и не меняет.

Ниже — как поставить агента, какие права он получает, зачем нужен metrics-server и что делать, если данные не пришли.

#Как установить агента в Kubernetes

1. Откройте проект в кабинете и добавьте стек (кнопка «Добавить»). Один стек — одно окружение, например namespace shop-prod.
2. На странице стека нажмите «Агент» → «Создать агента», введите название и нажмите «Создать».
3. В блоке «Где работает стек» выберите «Kubernetes» и впишите namespace в поле «Namespace» (по умолчанию default).
4. Скопируйте «Манифест nabl-agent.yaml», сохраните в файл и примените:

kubectl apply -f nabl-agent.yaml

Важно. Токен агента показывается один раз. Он уже вписан в манифест — сохраните файл в надёжном месте или запишите токен отдельно.

Агент ставится в тот же namespace, который наблюдает. Манифест — обычный YAML: его можно прочитать и поправить до kubectl apply.

#Что входит в манифест

Основная часть Deployment:

containers:
  - name: agent
    image: velgir/nabl-agent:latest
    env:
      - name: NABL_BASE_URL
        value: "https://app.nablserver.ru"
      - name: NABL_MODE
        value: "kubernetes"
      - name: NABL_INTERVAL
        value: "30"
      - name: NABL_K8S_NAMESPACES
        valueFrom:
          fieldRef:
            fieldPath: metadata.namespace
      - name: NABL_AGENT_TOKEN
        valueFrom:
          secretKeyRef:
            name: nabl-agent
            key: token
      - name: NABL_OTLP_ENABLED
        value: "true"
    resources:
      requests:
        cpu: 50m
        memory: 64Mi
      limits:
        memory: 256Mi

Полный манифест с портами и securityContext выдаёт кабинет — берите его оттуда.

#Права RBAC: что агент может в кластере

Права только на чтение:

rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "list"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["get", "list"]

Отдельный ClusterRole даёт get и list на persistentvolumes — чтобы показать, где лежит том: путь на ноде или внешнее хранилище. Содержимое томов агент не читает. Без этого ClusterRole агент работает, просто тома PVC видны без пути.

Под агента запускается без привилегий: не от root (uid 65532), файловая система только для чтения, без capabilities, seccomp RuntimeDefault. Нет ни hostPath, ни hostNetwork, ни privileged.

Проверить права самому:

kubectl auth can-i --list -n <namespace> --as=system:serviceaccount:<namespace>:nabl-agent

Агент поставлен давно? В старых манифестах не было securityContext. Добавить его можно без переустановки:

kubectl -n <namespace> patch deployment nabl-agent -p '{"spec":{"template":{"spec":{"securityContext":{"runAsNonRoot":true,"runAsUser":65532,"runAsGroup":65532,"seccompProfile":{"type":"RuntimeDefault"}},"containers":[{"name":"agent","securityContext":{"allowPrivilegeEscalation":false,"readOnlyRootFilesystem":true,"capabilities":{"drop":["ALL"]}}}]}}}}'

#Зачем нужен metrics-server

CPU и память подов агент берёт из metrics.k8s.io — его отдаёт metrics-server. Без него поды, статусы и рестарты видны, но без графиков потребления.

Проверить, есть ли metrics-server:

kubectl top pods -n <namespace>

Если команда выдаёт ошибку, установите metrics-server в кластер (в k3s и многих облачных кластерах он уже есть). Агента после этого переустанавливать не нужно.

#Несколько namespace или весь кластер

По умолчанию агент наблюдает только свой namespace. Чтобы охватить несколько, задайте NABL_K8S_NAMESPACES списком через запятую или all для всего кластера:

- name: NABL_K8S_NAMESPACES
  value: "shop,payments"

Role действует только в своём namespace, поэтому в этом случае замените Role и RoleBinding на ClusterRole и ClusterRoleBinding с теми же правилами:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: nabl-agent
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "list"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: nabl-agent
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: nabl-agent
subjects:
  - kind: ServiceAccount
    name: nabl-agent
    namespace: <namespace>

Если окружения разные (prod и staging), лучше сделать отдельные стеки и поставить по агенту в каждый namespace — так уведомления и графики не смешаются.

#Что собирает агент Kubernetes

Если под упал, агент дочитывает лог прошлого запуска, поэтому причина падения не теряется. Служебные контейнеры istio-proxy и linkerd-proxy пропускаются. Новый под, который ещё не прошёл проверку готовности и запущен меньше 5 минут, не считается нездоровым (агент 0.9.3+) — выкатки не дают ложных уведомлений.

Полные логи подов не хранятся: в Наблюдатель уходят только распознанные ошибки. Весь лог пода можно смотреть вживую в кабинете — без kubectl, см. Живые логи.

#Приём трасс и событий от приложений

Service nabl-agent открывает порты 4317 (OTLP gRPC), 4318 (OTLP HTTP) и 4319 (события и логи). Из того же namespace агент доступен как nabl-agent, из других — как nabl-agent.<namespace>.svc.cluster.local. Наружу эти порты публиковать не нужно. Подробнее — в статьях Трассировка и События и логи.

#Как проверить, что данные пошли

kubectl -n <namespace> get pods -l app=nabl-agent
kubectl -n <namespace> logs deploy/nabl-agent -f

В логе должна быть строка запуска вида nabl-agent 0.14.1 mode=kubernetes …. Через 30 секунд на странице стека появится вкладка «Поды» с Deployment-ами, StatefulSet-ами и их подами, а в разделе «Агенты» статус агента станет «Активен».

Сколько агент потребляет на самом деле:

kubectl top pod -n <namespace> -l app=nabl-agent

#Частые ошибки

Если причина не нашлась — см. решение проблем.

#Обновление и удаление

Обновить агента на образе latest:

kubectl -n <namespace> rollout restart deployment/nabl-agent

В production закрепите версию тегом или digest. Новый токен и подробности — в статье Обновление агента и токен.

Удалить агента полностью:

kubectl delete -f nabl-agent.yaml

Уйдут Deployment, Service, Secret, ServiceAccount и права — в кластере ничего не останется.

Совет. ИИ-ассистент через MCP создаст стек, выдаст манифест под ваш namespace и проверит, что поды появились. См. ИИ-ассистент.

#Что дальше

• Контейнеры — графики и статусы подов.
• Ошибки приложений — что агент находит в логах подов.
• Как работает агент — нагрузка на API-сервер и безопасность.
• Правила уведомлений — уведомления о падениях и OOM.