Учебный гайд: Прикладная часть 11. Интеграция с реальным API: от спецификации до деплоя

Тема: Прикладная часть 11. Интеграция с реальным API: от спецификации до деплоя

Уровень сложности: Средний

Расчётное время изучения: 4-6 часов

Предварительные требования: Знакомство с концепциями SDD (Specify, Plan, Tasks, Implement, Validate) из частей 7-9 первого тома.

Понимание принципов командного ревью (часть 16 первого тома).

Базовые знания работы с CLI (командной строкой) и Python.

Общее понимание работы вебхуков и REST API.

Цели обучения: Освоить локальный конвейер обработки инцидентов: от сырого вебхука до нормализованного события и проверки готовности (readiness).

Научиться применять 25-балльную модель оценки готовности (readiness) для принятия решения о допуске авто-ремедиации.

Понимать и уметь выявлять блокирующие условия (audit_trace, stateful workloads) до выполнения реальных действий.

Освоить разделение фаз в SDD, чтобы спецификация (specify) не подменяла собой этап реализации (implement).

Уметь классифицировать ошибки API и конвейера согласно таксономии (VALIDATION_ERROR, LLM_CALL_FAILED и др.) для выбора стратегии восстановления.

Обзор: Данная глава посвящена практической интеграции с реальным API в контексте управления инцидентами и авто-ремедиации. Вы научитесь безопасно проводить конвейер от получения сырого вебхука (Grafana/PagerDuty) до контролируемого деплоя или перезапуска. В качестве основного учебного кейса выступает производственный инцидент high_memory_usage. Глава демонстрирует, как с помощью скриптов из examples/real-api/ нормализовать данные, пройти шлюз готовности на основе 25-балльной рубрики и выполнить пробный прогон (dry-run), гарантируя, что запрещенные действия будут заблокированы, а разрешенные — строго обоснованы.

Ключевые концепции: Readiness (готовность): Формальная оценка конвейера по 25-балльной шкале. Включает 5 категорий (Spec, Implementation, Verification, Process, Security), оцениваемых от 0 до 5. Порог для автоматического допуска — 23/25. Если балл ниже, конвейер переходит в полуручной режим.

Sdd-разделение фаз: Методология, разделяющая жизненный цикл изменения на фазы: Specify (пользовательская история), Plan (стратегия), Tasks (шаги), Implement (применение), Validate (проверка). Защищает систему от преждевременного выполнения команд ('сразу лечить').

Audit trace (аудит-трейс): Причинно-следственный связующий журнал, который соединяет входящий вебхук, пользовательские команды (например, /sdd:specify), созданные спецификации и различия (diff) через уникальный incident_id. Обеспечивает доказуемость и воспроизводимость инцидента.

Dry-run (пробный прогон): Имитация выполнения действия против списка заранее согласованных действий (pre-approved actions) без внесения реальных изменений в инфраструктуру. Позволяет убедиться, что действие разрешено спецификацией.

Error taxonomy (таксономия ошибок): Классификация сбоев API (например, VALIDATION_ERROR, TOOL_EXECUTION_FAILED), которая позволяет оркестратору выбирать правильную стратегию восстановления (остановка, повтор, деградация, эскалация) вместо вывода общего статуса 'failed'.

Degraded mode (деградированный режим): Состояние системы, при котором авто-ремедиация отключается (например, при падении LLM или низком рейтинге Readyiness), но система продолжает сохранять доказательства и предлагать шаги оператору для ручного подтверждения.

Практические упражнения: Название: Нормализация входящих вебхуков

Проблема: Вы получили сырые полезные данные от систем мониторинга Grafana и PagerDuty. Вам необходимо запустить скрипт нормализации и убедиться, что выходной JSON совпадает с эталонным событием инцидента поле-в-поле.

Решение: 1. Перейдите в каталог примера: cd book2/examples/real-api

1. Запустите скрипт нормализации с указанием путей к фикстурам:

python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json

1. Убедитесь, что скрипт завершился с кодом возврата 0. Если код отличен от нуля, проверьте stderr на наличие ошибок валидации схемы.

Сложность: beginner

Название: Проверка шлюза готовности (Readiness)

Проблема: Оцените три различных состояния системы с помощью скрипта проверки готовности: проходной (24/25), сбой по аудиту (22/25) и сбой по stateful-нагрузке (24/25, но нет бэкапа).

Решение: Запустите скрипты по очереди и проанализируйте вывод:

1. python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json (Ожидание: код 0, PASS).
2. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json (Ожидание: код 1, BLOCK по причине audit_trace_coverage).
3. python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json (Ожидание: код 1, BLOCK по причине отсутствия подтвержденной резервной копии для stateful).

Сложность: intermediate

Название: Пробный прогон разрешенных и запрещенных действий

Проблема: Используйте скрипт dry-run для проверки двух действий против спецификации high_memory_usage. Первое действие (restart_pod) должно быть разрешено, а второе (delete_namespace) — заблокировано как неавторизованное.

Решение: 1. Запустите разрешенное действие: python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod Убедитесь, что код возврата 0 и в stdout есть PASS.

1. Запустите запрещенное действие:

python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace Убедитесь, что код возврата 1 и в stderr указана причина блокировки (действие не среди pre-approved).

Сложность: intermediate

Название: Заполнение рубрики готовности для собственного кейса

Проблема: Основываясь на 25-балльной модели, оцените гипотетический (или ваш текущий) конвейер. Заполните таблицу из 5 категорий, укажите артефакты-доказательства и выявите блокирующие условия, чтобы достичь порога 23/25.

Решение: 1. Создайте таблицу со столбцами: Категория, Балл, Артефакт-доказательство, Причина снижения.

1. Пройдитесь по Spec, Implementation, Verification, Process, Security.
2. Для Spec убедитесь, что есть WHY/WHAT/constraints.
3. Для Security проверьте наличие отката и emergency stop.
4. Если итог ниже 23/25, составьте список изменений (например: 'Добавить формальный триггер эскалации', 'Реализовать dry-run для ветки scale-up').

Сложность: advanced

Кейсы: Название: Производственный инцидент high_memory_usage

Сценарий: Система мониторинга Grafana фиксирует memory_percent=93 на поде api-7b4 в namespace appointments-api в течение 10 минут. PagerDuty повышает уровень инцидента до critical. Поступает webhook, инициирующий процесс авто-ремедиации системы.

Задача: Необходимо снизить потребление памяти (предотвратить OOMKill), не нарушив работу сервиса. Запуск автоматического скрипта, который просто перезапускает или удаляет ресурсы, рискован — можно потерять stateful-данные или расширить радиус последствий ошибки. Система должна понять, разрешено ли ей действовать автоматически, и какое действие минимально.

Решение: 1. Нормализация: Скрипт normalize_webhook.py объединяет данные из Grafana и PagerDuty в единый incident_event (incident_id=HM-2026-05-17-01).

1. Шлюз готовности: check_readiness.py оценивает конвейер. Если audit_trace ниже 1.0 или workload stateful без бэкапа — действие блокируется до вмешательства человека.
2. Пробный прогон: dry_run.py проверяет действие restart_pod против спецификации (pre-approved actions).
3. Исполнение: Если readiness >= 23/25 и dry_run дал PASS, инициируется перезапуск с обязательным мониторингом двух окон и наличием пути отката через 6 минут.

Результат: Автоматизированный конвейер безопасно изолировал проблему. Разрешенное действие было выполнено с полным аудитом (audit trail). Попытка конвейера выполнить неразрешенное или опасное действие была жестко заблокирована шлюзом безопасности, что предотвратило потенциальный сбой всего сервиса.

Извлечённые уроки: Specify не должен содержать конкретных команд (например, kubectl delete), он должен описывать WHY и WHAT.

Радиус последствий должен быть ограничен (например, только один конкретный pod).

Отказы системы (например, проблема с LLM) должны переводить её в degraded mode, а не останавливать полностью без объяснений.

Полная авто-ремедиация без участия человека (human-review) на критическом пути остается рискованной практикой (фронтиром).

Связанные концепции: Readiness Model

Audit Trace

Dry-run

Error Taxonomy

Degraded Mode

Советы по изучению: Начинайте с запуска готовых скриптов в book2/examples/real-api/. Не пытайтесь сразу настроить полноценный Kubernetes или GitOps — для учебного прохода важна логика работы скриптов.

Обратите особое внимание на фикстуры readiness_block_*.json. Попробуйте изменить в них значения (например, повысить audit_trace_coverage до 1.0) и посмотрите, как изменится результат работы check_readiness.py.

Сравните 'Плохой' и 'Хороший' примеры спецификаций (Specify) из текста. Поймите, почему выбор конкретной реализации на этапе спецификации блокирует гибкость планирования.

Всегда фиксируйте свои прогоны и решения (например, в capstone/readiness.md). Интеграция с API — это не только код, но и артефакты доказательства (audit trace).

Дополнительные ресурсы: Учебные скрипты (examples/real-api): Папка с готовым к запуску конвейером без внешних зависимостей (stdlib Python).

Github spec kit: Фреймворк для практического применения фаз Specify → Plan → Tasks → Implement.

Приложение d (калибровка порогов): Раздел D.5 содержит таблицы для настройки порогов readiness (Низкий/По умолчанию/Высокий) под разные типы production-среды.

Book/part-12-mvp.md: Опорный материал из первого тома, описывающий работу с SQLite, на основе которого построен сценарий high_memory_usage.

Резюме: В этой главе вы изучили, как превратить хаос из реальных API-вебхуков (Grafana, PagerDuty) в строгий, управляемый и доказуемый процесс авто-ремедиации. Главный вывод: любое автоматическое действие должно проходить через шлюз готовности (Readiness Gate). Использование 25-балльной модели оценки и обязательный пробный прогон (dry-run) гарантируют, что система не выйдет за пределы заданного радиуса последствий. SDD-разделение фаз и аудит-трейс обеспечивают прозрачность: если система не может доказать свою готовность (например, из-за неполного аудита), она переводится в безопасный полуручной режим.