AI Platform Docs

Состав компонента

Процесс/Сервис	Назначение	Основные сигналы
API	Каталог, получение записи и поиск с учетом прав доступа	Работоспособность, готовность, время ответа, коды 401/403/404/503
Kubernetes Reconciler	Мониторинг Service, EndpointSlice и разрешенных HTTPRoute	Свежесть покрытия, ошибки наблюдения, повторный список, задержка согласования
Outbox Relay	Публикация зафиксированных событий в Redpanda	Возраст неопубликованной записи, попытки, срок владения, ошибки брокера
Search Indexer	Обновление разрешений SpiceDB и документов OpenSearch	Отставание группы потребителя, повторные события, ошибки проекции
Search Reindex	Построение нового поколения поискового индекса	Состояние задания, смещения разделов, количество документов, контрольный набор
Retention	Применение сроков хранения	Время завершения, ошибки удаления, сохранность неопубликованной очереди

PostgreSQL хранит метаданные. Redpanda, SpiceDB и OpenSearch являются производными или внешними проекциями и восстанавливаются из метаданных и событий.

Получение сведений о состоянии

После явного выбора контекста и пространства имен допустимы команды чтения:

kubectl -n "$REGISTRY_NAMESPACE" get deploy,pod,svc,endpointslice,job,lease kubectl -n "$REGISTRY_NAMESPACE" get events --sort-by=.lastTimestamp kubectl -n "$REGISTRY_NAMESPACE" logs
deploy/ap-agent-registry-kubernetes-reconciler --all-pods --tail=200 kubectl -n "$REGISTRY_NAMESPACE" logs
deploy/ap-agent-registry-api --all-pods --tail=200

Важно: Не помещайте значение токена, текст карточки, запрос поиска, вектор и внутренний адрес в запрос.

Устаревшие данные мониторинга Kubernetes

Признак: алерт AgentRegistryObservationCoverageStale, потеря готовности Reconciler или исчезновение доступных интерфейсов.

Проверьте возраст покрытия, ошибки данных мониторинга, ответы 410, ограничение запросов Kubernetes и лидера сервисов Reconciler.

Возраст покрытия	Поведение
≤ 30 с	Покрытие свежее, ресурсы доступны
> 30 с	Покрытие устарело; catalog, interface и search скрыты
> 300 с ±20 %	Периодический full resync — полное подтверждение наличия/отсутствия

Убедитесь, что потоки Service и EndpointSlice свежие для каждого явно сопоставленного пространства имен.
Проверьте только права get/list/watch через RoleBinding. Чтение Secret, Pod, Deployment и всего кластера не требуется.
При 410 Gone дождитесь полного повторного списка.
При перезапуске лидера сервисов Reconciler, новый владелец должен сначала выполнить полную синхронизацию и только потом считать покрытие свежим.

Потеря готовности агента

Проверьте все EndpointSlice, принадлежащие сервису агента: управляющий контроллер, тип адреса, порт и признаки ready, serving, terminating.

При отсутствии доступного EndpointSlice:

агент не доступен из обычной выдачи для вызова;
удаляется публичный интерфейс;
каталог, интерфейс и поиск транзакционно скрываются; инициируется отзыв поисковой проекции;
разрешения доступа (owner/viewer в SpiceDB) сохраняются, потому что логическая сущность агента не удалена.

Восстанавливайте исходный агентский сервис или Low-code Runtime. Пересозданный сервис получает новый UID и проходит полную проверку.

Ошибка разрешений SpiceDB

Признак: AgentRegistryPermissionCleanupFailing или ответы authorization_unavailable.

Считайте затронутый агент недоступным до завершения восстановления.
Проверьте состояние SpiceDB и код ошибки авторизационного запроса.
После восстановления дождитесь повторной операции Reconciler.
Убедитесь, что разрешение владельца (owner) удалено либо создано в соответствии с текущим состоянием.

Откат БД SpiceDB не приведет к восстановлению.

Отказ поиска

При отказе сервиса эмбеддингов (embedding) поиск возвращает 503.
При отказе OpenSearch поиск возвращает 503.
Просмотр списка и одной записи продолжается, если PostgreSQL и SpiceDB исправны.
После восстановления создайте новое поколение индекса.
Переключайте псевдоним только после проверки количества, контрольного набора и догонки потока событий.
Храните прежнее поколение не менее семи дней для быстрого возврата.

Не редактируйте отдельные документы OpenSearch вручную.

Задержка транзакционной очереди

Признак: AgentRegistryOutboxPublishFailing или рост возраста самой старой неопубликованной записи.

Проверьте Redpanda, права на топик, срок хранения и владельца блокировки.
Не меняйте published_at вручную.
После истечения периода блокировки запись должна стать доступной повторной попытки.
Повторная доставка допустима: Search Indexer устраняет повторы по идентификатору события и версии агрегата.
После восстановления убедитесь, что очередь сокращается, а группа потребителя продвигается.

Миграции и восстановление

Задание миграции и проверка при запуске используют транзакционную блокировку PostgreSQL. При ошибке:

остановите деплой версии;
сохраните номер Alembic и ошибку базы;
верните совместимый образ приложения;
выполняйте понижение версии схемы только после проверки сохранности данных;
не запускайте разрушительный SQL из интерактивного контейнера.

Цели восстановления: Agent Registry — RTO 60 минут и RPO 5 минут; SpiceDB — RTO 30 минут и RPO 5 минут.

OpenSearch восстанавливается из метаданных и не имеет внутреннего механизма, гарантирующего сохранность.

Сервис Agent Registry