Runbook — Major upgrade

Когда: обновление, которое затрагивает схемы БД, формат бэкапов или ломает совместимость API. Любой релиз, помеченный как BREAKING в changeset.

Главный риск: автоматический database sync на старте — Notty синкает таблицы из схем при каждом boot. При major upgrade схемы могут поменяться несовместимо.

Pre-checks (≤ 30 мин)

• Прочитан CHANGELOG нового релиза, помечены breaking-пункты.
• Прогон upgrade-сценария на staging:
  • clone prod БД (или PITR-snapshot) → staging;
  • применить новый image;
  • прогнать smoke + критические content type read/write.
• Готов план rollback (см. rollback.md).
• Уведомлены клиенты/команды о коротком window (если ожидается).
• Сделан новый Notty snapshot: BASE_URL=... ADMIN_TOKEN=... deployment/scripts/backup.sh.
• Сделан новый managed PG snapshot вне приложения (pg_dump или provider PITR-checkpoint).

Window

1. Включить maintenance.
   • В nginx/ingress: route /api/content/** → 503 + Retry-After. Admin UI остаётся доступным операторам.
   • Альтернатива — заблокировать запись на ingress/API gateway. Runtime rate-limit не подходит для maintenance-mode: NOTTY_RATE_LIMIT_MAX нормализуется минимум до 1.
2. Дождаться дренажа фоновых джоб.
   • GET /api/admin/jobs/stats → running == 0.
   • При задержке: POST /api/admin/jobs/:id/cancel для poisoned задач.
3. Snapshot непосредственно перед апгрейдом.
4. Применить новый image (см. deploy.md, шаги Deploy).
5. Проверить database sync: GET /api/database/status — connection ok, tables_count соответствует ожиданиям.
6. Smoke: verify-deploy.sh + критические сценарии.
7. Снять maintenance.

Validation (≤ 30 мин после)

• Алёрты не возросли (/api/admin/operational-alerts/stats).
• Нет растущей backlog'и в jobs (/api/admin/jobs/stats).
• Нет растущего dead-letter в webhooks (/api/webhooks/dead-letter).
• Метрики response time восстановились к baseline.
• Все scheduled-jobs живы: GET /api/admin/scheduled-jobs.

Rollback тригер

Откатывайтесь, если:

• readiness probe не встаёт зелёной > 5 мин;
• notty_http_request_duration_seconds p95 > 2× baseline > 10 мин;
• ошибки 5xx > 1% от трафика > 5 мин;
• появились новые поломанные jobs / webhook'и, не связанные с тестируемой фичей.

См. rollback.md.

После апгрейда

• Обновить runtime-package.json если поменялись native deps версии.
• Обновить deployment/.env.example под новые env.
• Прогнать quarterly restore drill в новом релизе ( backup-automation.md ).
• Записать факт upgrade в operations log с таймингами (RTO, downtime).