Решение проблем

Определите, на каком слое возникает ошибка: credentials, cloud API, Kubernetes API, billing или источник метрик. Успех одного слоя не подтверждает остальные.

Быстрая диагностика

в Коннекторы → ⋮ → Проверить сохраните полный текст ошибки;
проверьте Folder ID и актуальность выбранного способа аутентификации;
если test успешен, запустите Синхронизация и отдельно проверьте inventory, billing и audit;
не расширяйте IAM-роли наугад: сопоставьте HTTP-код и ресурс, к которому нет доступа.

Ошибки подключения и cloud API

Симптом	Вероятная причина	Что сделать
`401`, `Unauthenticated`, подпись JWT	Токен истёк, JSON повреждён, ключ отозван или выбран не тот auth method	Для IAM-токена выпустите новый; для JSON проверьте валидность файла и ротацию ключа
`403` при чтении folder/compute	Сервисному аккаунту не назначены роли на выбранном каталоге	Проверьте `viewer` и `compute.viewer` на Folder ID из формы
`404` для folder или пустой inventory	Введено имя вместо ID, выбран другой каталог либо аккаунт не видит ресурс	Скопируйте ID из консоли и сравните с `yc resource-manager folder get`
`Нет связи с Yandex Cloud API`	DNS, proxy, firewall или временная недоступность API	Проверьте исходящий HTTPS из окружения Oopps.ai; повторите после устранения сети

Кластер найден, но аудит не работает

Симптом	Причина	Решение
`Forbidden`, невозможно `list nodes`	Cloud API discovery прошёл, но IAM-токен не имеет полного доступа к Kubernetes API	Для прямого SaaS-аудита согласуйте `k8s.cluster-api.cluster-admin`; либо установите агент с минимальным RBAC
Нет endpoint master	API не вернул внешний или внутренний endpoint либо недостаточно прав на чтение кластера	Проверьте Managed Kubernetes IAM и конфигурацию master
Timeout при подключении к master	Кластер имеет только private endpoint, недоступный SaaS backend	Предоставьте сетевой маршрут по политике компании или используйте in-cluster агент
Нет CA certificate	Managed Kubernetes API не вернул CA; небезопасное подключение намеренно не выполняется	Проверьте права и ответ API; не отключайте TLS verification
Workloads есть, utilization нет	metrics-server отсутствует или недоступен	Проверьте `kubectl get apiservice v1beta1.metrics.k8s.io` и `kubectl top pods -A`

Prometheus — отдельная проверка

Отсутствие данных Prometheus не означает поломку агента. Агент версии 0.1.x читает metrics-server. Prometheus/VictoriaMetrics обнаруживает и опрашивает backend; при ошибке этого пути система пытается использовать metrics-server как fallback.

Inventory работает, billing отсутствует

Сообщение	Проверка
Billing Account ID не указан	Добавьте ID платёжного аккаунта в SaaS-коннектор. В On-Prem проверьте автоопределение и настройки service account нод.
Нет доступа к платёжному аккаунту	Назначьте `billing.accounts.viewer` на самом billing account, не только на каталоге.
Облако не привязано к billing account	Сравните Cloud ID коннектора с billable object bindings нужного платёжного аккаунта.
Отчёт вернул 0 ресурсов	Проверьте период, наличие фактических начислений и привязку облака; inventory при этом может быть корректным.

Агент не передаёт метрики

kubectl -n oopps-system get pods
kubectl -n oopps-system logs -l app.kubernetes.io/name=oopps-agent --tail=100
kubectl get apiservice v1beta1.metrics.k8s.io
kubectl top pods -A

401 в логах агента означает неверный или отозванный agent token, а не ключ Yandex Cloud. Сетевой timeout к app.oopps.ai означает проблему исходящего HTTPS. Ошибка metrics API указывает на metrics-server или RBAC внутри кластера.

Что приложить к обращению в поддержку

тип установки: SaaS или On-Prem, версия On-Prem/агента;
ID коннектора и время последней попытки (без токенов и JSON-ключа);
полный текст ошибки из UI и слой, на котором она возникла;
для Kubernetes — результат команд диагностики с удалёнными чувствительными данными;
ожидаемый Folder ID / Cluster ID / Billing Account ID можно передать, но не секретный ключ.